~maphew/leo-editor/doc-edits : contents of leo/doc/LeoDocs.leo at revision 6172

~maphew/leo-editor/doc-edits : (revision 6172)
<?xml version="1.0" encoding="utf-8"?>
<!-- Created by Leo (http://leoeditor.com/leo_toc.html) -->
<?xml-stylesheet ekr_test?>
<leo_file xmlns:leo="http://www.leo-editor.org/2011/leo" >
<leo_header file_format="2" tnodes="0" max_tnode_index="0" clone_windows="0"/>
<globals body_outline_ratio="0.5" body_secondary_ratio="0.5">
	<global_window_position top="50" left="50" height="500" width="700"/>
	<global_log_window_position top="0" left="0" height="0" width="0"/>
</globals>
<preferences/>
<find_panel_settings/>
<vnodes>
<v t="ekr.20070610174018"><vh>Startup</vh>
<v t="ekr.20070325123558"><vh>@chapters</vh></v>
<v t="ekr.20050407144417"><vh>@settings</vh>
<v t="ekr.20111108052738.5507"><vh>@shortcuts</vh></v>
<v t="ekr.20130816100419.17299"><vh>@string target_language = rest</vh></v>
<v t="ekr.20100907092300.4440"><vh>Inkscape options</vh>
<v t="ekr.20100907092300.4441"><vh>@string inkscape-template = ../docs/inkscape-template.svg</vh></v>
<v t="ekr.20100907092300.4442"><vh>@string inkscape-bin = "c:\Program Files (x86)\Inkscape\inkscape.exe"</vh></v>
</v>
<v t="ekr.20101009114830.4724"><vh>File options</vh>
<v t="ekr.20080923182326.1"><vh>@@bool create_nonexistent_directories = True</vh></v>
<v t="ekr.20080412124815.1"><vh>@bool fixedWindow = False</vh></v>
<v t="ekr.20101009114830.4723"><vh>@bool put_expansion_bits_in_leo_files = False</vh></v>
</v>
<v t="ekr.20101009114830.4725"><vh>Plugins options</vh>
<v t="ekr.20050407144342"><vh>@page http plugin</vh>
<v t="ekr.20050407144342.1"><vh>@bool http_active = False</vh></v>
<v t="ekr.20050407144342.2"><vh>@int  port = 8080</vh></v>
<v t="ekr.20050407144342.3"><vh>@string rst_http_attributename = rst_http_attribute</vh></v>
</v>
<v t="ekr.20050812123002"><vh>@page rst3 options</vh>
<v t="ekr.20131009050634.17658"><vh>@bool rst3_call_docutils = False</vh></v>
<v t="ekr.20131009050634.17625"><vh>@bool rst3_code_mode = False</vh></v>
<v t="ekr.20050812123002.7"><vh>@bool rst3_format_headlines = True</vh></v>
<v t="ekr.20131009050634.17627"><vh>@bool rst3_generate_rst = True</vh></v>
<v t="ekr.20131009050634.17610"><vh>@bool rst3_http_server_support = False</vh></v>
<v t="ekr.20050812123002.6"><vh>@bool rst3_massage_body = False</vh></v>
<v t="ekr.20131009050634.17630"><vh>@bool rst3_show_headlines = True</vh></v>
<v t="ekr.20131009052848.6456"><vh>@bool rst3_show_leo_directives = True</vh></v>
<v t="ekr.20131009050634.17631"><vh>@bool rst3_show_organizer_nodes = True</vh></v>
<v t="ekr.20131009050634.17622"><vh>@bool rst3_verbose = True</vh></v>
<v t="ekr.20131009050634.17623"><vh>@bool rst3_write_intermediate_file = True</vh></v>
<v t="ekr.20051202072010"><vh>@string rst3_default_path =</vh></v>
<v t="ekr.20131009050634.17616"><vh>@string rst3_stylesheet_path = ..\doc</vh></v>
<v t="sps.20100708213227.44914"><vh>@string rst3_write_intermediate_extension = .txt</vh></v>
<v t="ekr.20050812123002.1"><vh>Http options...</vh>
<v t="ekr.20050812123002.2"><vh>@bool rst3_clear_http_attributes = False</vh></v>
<v t="ekr.20050812123002.3"><vh>@string rst3_http_attributename = 'rst_http_attribute'</vh></v>
<v t="ekr.20050812123002.4"><vh>@bool rst3_http_server_support = False</vh></v>
<v t="ekr.20050812123002.5"><vh>@string rst3_node_begin_marker = 'http-node-marker-'</vh></v>
</v>
</v>
</v>
</v>
<v t="ekr.20131017051340.16847"><vh>Buttons</vh>
<v t="ekr.20111017085134.16158"><vh> Slideshow Buttons</vh>
<v t="ekr.20111017085134.16159"><vh>@@button copy-@screenshot-node</vh>
<v t="ekr.20111017085134.16160"><vh>@screenshot</vh>
<v t="ekr.20111017085134.16161"><vh>To Do List</vh>
<v t="ekr.20111017085134.16162"><vh>Urgent</vh></v>
<v t="ekr.20111017085134.16163"><vh>Important</vh></v>
<v t="ekr.20111017085134.16164"><vh>Soon</vh></v>
<v t="ekr.20111017085134.16165"><vh>Whenever</vh></v>
</v>
<v t="ekr.20111017085134.16166"><vh>Diary</vh>
<v t="ekr.20111017085134.16167"><vh>2009</vh>
<v t="ekr.20111017085134.16168"><vh>Jul 2009</vh></v>
<v t="ekr.20111017085134.16169"><vh>Aug 2009</vh></v>
<v t="ekr.20111017085134.16170"><vh>Sep 2009</vh></v>
<v t="ekr.20111017085134.16171"><vh>Oct 2009</vh></v>
<v t="ekr.20111017085134.16172"><vh>Nov 2009</vh></v>
<v t="ekr.20111017085134.16173"><vh>Dec 2009</vh></v>
</v>
<v t="ekr.20111017085134.16174"><vh>2010</vh></v>
</v>
</v>
<v t="ekr.20111017085134.16175"><vh>@select Urgent</vh></v>
<v t="ekr.20111017085134.16176"><vh>@@button ins-@slide-nodes</vh></v>
<v t="ekr.20111017085134.16177"><vh>@@button make-slide @key=Alt-8</vh></v>
<v t="ekr.20111017085134.16178"><vh>@@button make-slide-show @key=Alt-8</vh></v>
<v t="ekr.20111017085134.16179"><vh>@@button meld</vh>
<v t="ekr.20111017085134.16180"><vh>class MeldController</vh>
<v t="ekr.20111017085134.16181"><vh>utils</vh>
<v t="ekr.20111017085134.16182"><vh>finalize &amp; fix</vh></v>
<v t="ekr.20111017085134.16183"><vh>has_at_no_screenshot_node</vh></v>
<v t="ekr.20111017085134.16184"><vh>match</vh></v>
</v>
<v t="ekr.20111017085134.16185"><vh>run &amp; helpers</vh>
<v t="ekr.20111017085134.16186"><vh>adjust_slideshow &amp; helper</vh>
<v t="ekr.20111017085134.16187"><vh>adjust_slide_node &amp; helpers</vh>
<v t="ekr.20111017085134.16188"><vh>add_at_url_final_output_file</vh></v>
<v t="ekr.20111017085134.16189"><vh>add_image_directive</vh></v>
<v t="ekr.20111017085134.16190"><vh>delete_at_url_built_slide_node</vh></v>
</v>
</v>
<v t="ekr.20111017085134.16191"><vh>check &amp; helpers</vh>
<v t="ekr.20111017085134.16192"><vh>check_dir</vh></v>
<v t="ekr.20111017085134.16193"><vh>count_slide_nodes</vh></v>
</v>
<v t="ekr.20111017085134.16194"><vh>copy_files &amp; helper</vh>
<v t="ekr.20111017085134.16195"><vh>copy_file</vh></v>
</v>
<v t="ekr.20111017085134.16196"><vh>get_wink_screenshots</vh></v>
</v>
</v>
</v>
<v t="ekr.20111017085134.16197"><vh>@@button renumber nodes</vh></v>
</v>
<v t="ekr.20111017085134.16198"><vh>@@button remove-image-directives</vh></v>
<v t="ekr.20111017085134.16199"><vh>@@button remove-built-slides</vh></v>
<v t="ekr.20111017085134.16200"><vh>@@button remove-final-output</vh></v>
</v>
<v t="ekr.20130803073926.17120"><vh>@@button clean-mail</vh></v>
<v t="sps.20100708203040.19008"><vh>@@button generate-full-userguide</vh>
<v t="sps.20100708203040.19009"><vh>&lt;&lt; html manual &gt;&gt;</vh></v>
<v t="sps.20100708203040.19010"><vh>&lt;&lt; pdf manual &gt;&gt;</vh></v>
</v>
<v t="ville.20090705224948.5734"><vh>@@button generate-userguide</vh>
<v t="ville.20090705225609.5736"><vh>&lt;&lt; html manual &gt;&gt;</vh></v>
<v t="ville.20090705225609.5738"><vh>&lt;&lt; pdf manual &gt;&gt;</vh></v>
</v>
<v t="ekr.20131016083406.16724"><vh>@button make-sphinx @key=Alt-.</vh></v>
</v>
<v t="ekr.20131017051340.16850"><vh>Scripts</vh>
<v t="ekr.20101111175617.5037"><vh>Script: get-plugin-docstrings</vh>
<v t="ekr.20101111175617.56915"><vh>class controller</vh>
<v t="ekr.20101112045055.13356"><vh>allowDir</vh></v>
<v t="ekr.20101112222250.5322"><vh>allowFile</vh></v>
<v t="ekr.20101112045055.13355"><vh>createDocs</vh></v>
<v t="ekr.20101112045055.13354"><vh>createSummary</vh></v>
<v t="ekr.20101111175617.14683"><vh>getDocString</vh></v>
<v t="ekr.20101112045055.13357"><vh>getFirstParagraph</vh></v>
<v t="ekr.20101111175617.24328"><vh>openPlugins</vh></v>
<v t="ekr.20101111175617.5787"><vh>run</vh></v>
</v>
</v>
<v t="ekr.20131013060803.16851"><vh>Script: generate position trace</vh></v>
</v>
<v t="ekr.20131017051340.16816"><vh>Unused documentation</vh>
<v t="ekr.20131017051340.16831"><vh>@@rst html/IPythonBridge.html</vh>
<v t="ekr.20131017051340.16832"><vh>@rst-no-head links</vh></v>
<v t="ekr.20131017051340.16833"><vh>Introduction</vh></v>
<v t="ekr.20131017051340.16834"><vh>Installation and startup</vh></v>
<v t="ekr.20131017051340.16835"><vh>Accessing IPython from Leo</vh></v>
<v t="ekr.20131017051340.16836"><vh>Accessing Leo nodes from IPython</vh></v>
<v t="ekr.20131017051340.16837"><vh>@cl definitions</vh></v>
<v t="ekr.20131017051340.16838"><vh>Special node types</vh></v>
<v t="ekr.20131017051340.16839"><vh>Launching ILeo from IPython</vh></v>
<v t="ekr.20131017051340.16840"><vh>Declaring custom push-to-ipython handlers</vh></v>
<v t="ekr.20131017051340.16841"><vh>Example code snippets</vh></v>
<v t="ekr.20131017051340.16842"><vh>Example use case: pylab</vh></v>
<v t="ekr.20131017051340.16843"><vh>Magic functions</vh></v>
<v t="ekr.20131017051340.16844"><vh>Acknowledgements and history</vh></v>
</v>
<v t="ekr.20131017051340.16779"><vh>@@rst html/leoInspect.html</vh>
<v t="ekr.20131017051340.16780"><vh>A query language</vh></v>
<v t="ekr.20131017051340.16781"><vh>Comparing leoInspect and Pylint</vh></v>
<v t="ekr.20131017051340.16782"><vh>Still to do</vh></v>
<v t="ekr.20131017051340.16783"><vh>Theory of operation</vh>
<v t="ekr.20131017051340.16784"><vh>Getters</vh></v>
<v t="ekr.20131017051340.16785"><vh>Computing token ranges</vh>
<v t="ekr.20131017051340.16786"><vh>Token-info prepass</vh></v>
<v t="ekr.20131017051340.16787"><vh>token_range</vh></v>
</v>
</v>
</v>
</v>
</v>
<v t="ekr.20050831195449"><vh>Read me first</vh></v>
<v t="ekr.20100805171546.4412"><vh>Web pages</vh>
<v t="ville.20090609182215.5676"><vh>@auto-rst treecaching.txt</vh></v>
<v t="ekr.20090428133936.2"><vh>@edit html\conf.py</vh></v>
<v t="ekr.20101112045055.5064" descendentVnodeUnknownAttributes="7d7100285503302e3171017d710255097374725f6174696d657103550c313337363431323739362e3071047355013071057d71066803550c313337363431323932332e307107735503302e3071087d71096803550c313337363431323932372e30710a73752e"><vh>@file plugin_catalog.py</vh></v>
<v t="ekr.20101112045055.5065"><vh>@url docs generated from plugin_catalog.py</vh></v>
<v t="ekr.20131005214621.16088"><vh>Home page</vh>
<v t="ekr.20100808060203.4273"><vh>@file html/index.html</vh></v>
</v>
<v t="ekr.20131008041326.16065"><vh>Links page</vh>
<v t="ekr.20130807203905.16606"><vh>@edit html/leoLinks.html</vh></v>
</v>
<v t="ekr.20090711120622.10446"><vh>Screen shots page</vh>
<v t="ekr.20090711120622.10447"><vh>@rst html/screen-shots.html</vh>
<v t="ekr.20090811090022.14452"><vh>Windows screen shots</vh></v>
<v t="ekr.20090811090022.14453"><vh>Linux screen shots</vh></v>
</v>
</v>
<v t="ekr.20101007100904.4372"><vh>Slideshows</vh>
<v t="ekr.20101028110015.8271" descendentVnodeUnknownAttributes="7d710028550b302e312e312e382e342e3171017d7102580b0000007374725f6c656f5f706f7371035800000000710473550b302e312e312e382e332e3171057d7106580b0000007374725f6c656f5f706f737107680473550b302e312e312e382e352e3171087d7109580b0000007374725f6c656f5f706f73710a680473550b302e312e312e382e322e31710b7d710c580b0000007374725f6c656f5f706f73710d680473752e"><vh>@file slideshows.txt</vh></v>
<v t="ekr.20100821182153.4343"><vh>@rst html/slides.html</vh></v>
</v>
<v t="ekr.20131005214621.16089"><vh>TOC</vh>
<v t="ekr.20090428102353.1"><vh>@edit html\leo_toc.html.txt</vh></v>
</v>
<v t="ekr.20101115152915.4937"><vh>wikipedia entry</vh></v>
</v>
<v t="ekr.20040414161647"><vh>Leo's Documentation</vh>
<v t="ekr.20131017094004.16739"><vh>How to...</vh>
<v t="ekr.20090401113141.1"><vh>How to generate odt/rtf/pdf files</vh>
<v t="ekr.20090620131445.5595"><vh>Post from ville</vh></v>
<v t="ekr.20090401113141.2"><vh>@rst c:\prog\test\test.html</vh>
<v t="ekr.20090401113141.4"><vh>section 1</vh></v>
</v>
</v>
<v t="ekr.20101104024804.4898"><vh>How to generate these docs</vh></v>
</v>
<v t="ekr.20101025080245.5794"><vh>Preliminaries</vh>
<v t="ekr.20131008041326.16079"><vh>@rst html/preliminaries.html</vh>
<v t="ekr.20131017174814.17479"><vh>Preface</vh></v>
<v t="ekr.20050831184021.4"><vh>What people are saying about Leo</vh>
<v t="ekr.20050830074815.1"><vh>Leo is revolutionary</vh></v>
<v t="ekr.20050830074815.2"><vh>Leo is a showcase Python application</vh></v>
<v t="ekr.20050830074815.3"><vh>Leo is fun, even addicting</vh></v>
<v t="ekr.20050830074815.4"><vh>Leo is a flexible, powerful IDE</vh></v>
<v t="ekr.20050830074815.5"><vh>Leo is a superb outliner</vh></v>
<v t="ekr.20050830074815.6"><vh>Leo is an excellent PIM</vh></v>
<v t="ekr.20050830074815.8"><vh>Leo is a superb documentation tool</vh></v>
<v t="ekr.20050830074815.9"><vh>Leo simplifies the understanding of complex systems</vh></v>
<v t="ekr.20050830074815.10"><vh>Leo is stable, well designed and well supported</vh></v>
<v t="ekr.20050830074815.11"><vh>Longer quotes...</vh>
<v t="ekr.20050830074815.12"><vh> Speed Ream's slashdot article</vh></v>
<v t="ekr.20050830074815.13"><vh>Joe Orr</vh></v>
<v t="ekr.20050830074815.14"><vh>Dan Winkler</vh></v>
<v t="ekr.20050830074815.15"><vh>Dan Winkler 2</vh></v>
<v t="ekr.20050830074815.16"><vh>Dan Winkler 3</vh></v>
</v>
</v>
<v t="ekr.20040414172218.4"><vh>Acknowledgements</vh>
<v t="ekr.20040416080538"><vh>@rst-no-head special mentions</vh></v>
</v>
<v t="ekr.20090221070927.1"><vh>Leo's MIT License</vh></v>
</v>
</v>
<v t="ekr.20131008041326.16092"><vh>Installing &amp; running Leo</vh>
<v t="ekr.20131015104133.16766"><vh>@rst html/getting-started.html</vh></v>
<v t="ekr.20111127144911.5544"><vh>@rst html/download.html</vh></v>
<v t="ekr.20131008041326.16094"><vh>@rst html/installing.html</vh>
<v t="ekr.20101125062332.5090"><vh>Installing packages</vh></v>
<v t="ekr.20100817101952.4303"><vh>Installing Leo itself</vh>
<v t="ekr.20100731112744.7276"><vh>Installing Leo on Windows</vh>
<v t="ekr.20130807203905.16602"><vh>Using the single-click installer</vh></v>
<v t="ekr.20130807203905.16603"><vh>Installing from sources</vh>
<v t="ekr.20130807203905.16597"><vh>Creating Windows file associations</vh></v>
</v>
</v>
<v t="ekr.20100731112744.7274"><vh>Installing Leo on Linux</vh></v>
<v t="ekr.20100731112744.7275"><vh>@rst-ignore Installing Leo on MacOS X</vh></v>
<v t="ekr.20120229094652.15098"><vh>Installing Leo on MacOs 10.7 Lion</vh></v>
<v t="ekr.20100817101952.4306"><vh>Contributing to Leo with bzr</vh></v>
</v>
</v>
<v t="ekr.20131008041326.16140"><vh>@rst html/running.html</vh>
<v t="ekr.20131008041326.16151"><vh>Running Leo</vh>
<v t="ekr.20131008041326.16152"><vh>Running Leo the first time</vh></v>
<v t="ekr.20131008041326.16153"><vh>Running Leo in batch mode</vh></v>
<v t="ekr.20131008041326.16154"><vh>Running Leo from a console window</vh></v>
<v t="ekr.20131008041326.16155"><vh>The .leo directory</vh></v>
</v>
<v t="ekr.20131008041326.16156"><vh>Leo's command-line options</vh></v>
</v>
</v>
<v t="ekr.20050831195331.1"><vh>FAQ</vh>
<v t="ekr.20050830115714"><vh>@rst html\FAQ.html</vh>
<v t="ekr.20050830120007"><vh>@rst-no-head Links (FAQ)</vh></v>
<v t="ekr.20050830115714.26"><vh>Customizing Leo</vh>
<v t="ekr.20050830115714.29"><vh>How can I add support for a new language?</vh></v>
<v t="ekr.20050830115714.30"><vh>How do I submit a plugin?</vh></v>
<v t="ekr.20050830120844"><vh>How do I add a new menu item from a plugin?</vh></v>
<v t="ekr.20060805094325"><vh>How can I use Leo's legacy key bindings?</vh></v>
<v t="ekr.20060915112109"><vh>How can I enable and disable support for psyco?</vh></v>
<v t="ekr.20091105080104.9031"><vh>How do I specify qt fonts?</vh></v>
<v t="ekr.20110531155858.20564"><vh>How do I set selection colors?</vh></v>
</v>
<v t="ekr.20090212054250.5"><vh>Getting Leo</vh>
<v t="ekr.20090212054250.6"><vh>Where can I get official releases of Leo?</vh></v>
<v t="ekr.20080603124653.1"><vh>How do I use bzr to get the latest sources from Leo's launchpad site?</vh></v>
<v t="ekr.20090212054250.7"><vh>How can I get recent bzr snapshots of Leo?</vh></v>
</v>
<v t="ekr.20070623145346"><vh>Installing Leo</vh>
<v t="ekr.20090202191501.7"><vh>Leo's installer failed, what do I do?</vh></v>
<v t="ekr.20060329101442"><vh>Nothing (or almost nothing) happens when I start Leo.  What should I do?</vh></v>
<v t="ekr.20070623145346.1"><vh>Running Python setup.py install from the leo directory doesn't work.  Why not?</vh></v>
</v>
<v t="ekr.20050830115714.1"><vh>Learning to use Leo</vh>
<v t="ekr.20050830115714.2"><vh>What's the best way to learn to use Leo?</vh></v>
<v t="ekr.20050830115714.4"><vh>Why should I use clones?</vh></v>
<v t="ekr.20050830115714.7"><vh>When is using a section better than using a method?</vh></v>
<v t="ekr.20060111192108"><vh>When is deleting a node dangerous?</vh></v>
<v t="ekr.20110521135104.18151"><vh>Why doesn't Leo support cross-file clones?</vh></v>
<v t="ekr.20110531155858.20559"><vh>How does EKR (Leo's developer) use Leo?</vh></v>
<v t="ekr.20120229094652.15152"><vh>How does Leo handle clone conflicts?</vh></v>
</v>
<v t="ekr.20101025080245.6084"><vh>Leo in Shared environments</vh>
<v t="ekr.20050830115714.12"><vh>How should I use Leo with bzr/git/hg/svn/cvs?</vh></v>
<v t="ekr.20090706042206.14718"><vh>How can I use Leo cooperatively without sentinels?</vh></v>
<v t="ekr.20120229094652.15137"><vh>What's the recommended way to upgrade Leo?</vh></v>
</v>
<v t="ekr.20050830115714.118"><vh>Tips and techniques</vh>
<v t="ekr.20050830115714.113"><vh>How can I create a template .leo file?</vh></v>
<v t="ekr.20050830115714.120"><vh>How can I display graphics in Leo?</vh></v>
<v t="ekr.20070622185234"><vh>How can I do a simple find and replace?</vh></v>
<v t="ekr.20050830115714.74"><vh>How can I import many files at once?</vh></v>
<v t="ekr.20120229094652.15099"><vh>How can I make commonly-used scripts widely accessible?</vh></v>
<v t="ekr.20120229094652.15124"><vh>How can I restore focus without using the mouse</vh></v>
<v t="ekr.20060822111759"><vh>How can I reuse @button nodes in multiple files?</vh></v>
<v t="ekr.20050830115714.116"><vh>How can I show Leo files with Excel?</vh></v>
<v t="ekr.20120229094652.15148"><vh>How can I use BibTeX citations from Leo?</vh></v>
<v t="ekr.20130807203905.16526"><vh>How can I use bzr to check Leo's importers?</vh></v>
<v t="ekr.20050830120857"><vh>How can I use Leo to develop Leo itself?</vh></v>
<v t="ekr.20050830115714.119"><vh>How can I use two copies of Leo to advantage?</vh></v>
<v t="ekr.20080527063511.1"><vh>What is an easy way to profile code?</vh></v>
</v>
<v t="ekr.20050830115714.76"><vh>Trouble shooting</vh>
<v t="ekr.20090130144433.1"><vh>How do I get help?</vh></v>
<v t="ekr.20090130144433.2"><vh>How do I report bugs?</vh></v>
<v t="ekr.20080813064908.2"><vh>My old .leo files won't load using Leo 4.5 or later. What should I do?</vh></v>
<v t="ekr.20050830115714.115"><vh>Error messages from the rst3 plugin aren't helpful. What can I do?</vh></v>
<v t="ekr.20050906090012"><vh>How can I run Leo from a console window?</vh></v>
<v t="ekr.20050830115714.77"><vh>How can I use Python's pdb debugger with Leo?</vh></v>
<v t="ekr.20050830115714.17"><vh>I can't write Imported files.  What's going on?</vh></v>
<v t="ekr.20060329101442"></v>
<v t="ekr.20050830115714.117"><vh>The new Python decorator syntax causes problems.  What can I do?</vh></v>
<v t="ekr.20070623145346.1"></v>
<v t="ekr.20070816092449"><vh>I can't run the LeoBridge module outside of leo/core.  What should I do?</vh></v>
<v t="ekr.20101026082911.5538"><vh>Why didn't Leo update my @shadow outline as expected?</vh></v>
<v t="ekr.20120229094652.15130"><vh>Why do Qt windows disappear in my scripts?</vh></v>
</v>
<v t="ekr.20071026055929"><vh>Unicode issues</vh>
<v t="ekr.20061021164213"><vh>I can not enter non-ascii characters.  What can I do?</vh></v>
<v t="ekr.20050830115714.9"><vh>Some characters in external files look funny. What can I do?</vh></v>
<v t="ekr.20060917130130"><vh>I get weird results when defining unicode strings in scripts.  What is going on?</vh></v>
<v t="ekr.20050830115714.10"><vh>Some characters are garbled when importing files. What can I do?</vh></v>
<v t="ekr.20071026055929.1"><vh>Python's print statement shows 'byte hash' for unicode characters.  What can I do?</vh></v>
</v>
<v t="ekr.20050830115714.13"><vh>Using external files</vh>
<v t="ekr.20050830115714.14"><vh>How do I inhibit sentinels in external files?</vh></v>
<v t="ekr.20050830115714.16"><vh>How do I prevent Leo from expanding sections?</vh></v>
<v t="ekr.20050830115714.18"><vh>How can I create Javascript comments?</vh></v>
<v t="ekr.20050830115714.19"><vh>How can I disable PHP comments?</vh></v>
<v t="ekr.20050830115714.20"><vh>How can I use Leo with unsupported languages?</vh></v>
<v t="ekr.20050830115714.21"><vh>How do I make external files start with a shebang line?</vh></v>
<v t="ekr.20050830115714.24"><vh>Can @file trees contain material not in the external file?</vh></v>
<v t="ekr.20050830115714.25"><vh>How can I use Leo with older C compilers</vh></v>
<v t="ekr.20060529053407"><vh>Why can't I use @ignore directives in @file trees?</vh></v>
<v t="shadow.20080825171547.9"><vh>How can I avoid getting long lines in external files?</vh></v>
</v>
</v>
</v>
<v t="ekr.20091130111843.6787"><vh>Tutorials</vh>
<v t="ekr.20091130111843.6788"><vh>@rst html\tutorial.html</vh></v>
<v t="ekr.20131008041326.16203"><vh>@rst html\tutorial-basics.html</vh>
<v t="ekr.20131008041326.16204"><vh>@rst-no-head links &amp; markup</vh></v>
<v t="ekr.20131002211347.6456"><vh>Command names</vh></v>
<v t="ekr.20131002055813.15973"><vh>Leo's main window</vh></v>
<v t="ekr.20131004191204.16079"><vh>Operations on windows, panes &amp; files</vh></v>
<v t="ekr.20131002055813.19835"><vh>Operations on nodes</vh></v>
<v t="ekr.20131002055813.19036"><vh>Selecting and moving outline nodes</vh></v>
<v t="ekr.20131002055813.19037"><vh>Moving the cursor in text panes</vh></v>
<v t="ekr.20131001100335.15946"><vh>The minibuffer &amp; completions</vh></v>
<v t="ekr.20131001100335.15938"><vh>Finding &amp; replacing text</vh></v>
<v t="ekr.20131002055813.19837"><vh>Undoing and redoing changes</vh></v>
<v t="ekr.20131001100335.15947"><vh>Getting help</vh></v>
<v t="ekr.20131004064408.16020"><vh>Leo directives</vh></v>
<v t="ekr.20131001100335.15940"><vh>Configuring Leo</vh></v>
<v t="ekr.20131009100732.19038"><vh>Plugins</vh></v>
<v t="ekr.20131003040744.18221"><vh>Creating external files with @file and @all</vh></v>
<v t="ekr.20131005214621.16090"><vh>Summary</vh></v>
</v>
<v t="ekr.20131008041326.16222"><vh>@rst html\tutorial-pim.html</vh>
<v t="ekr.20131008041326.16248"><vh>@rst-no-head links &amp; markup</vh></v>
<v t="ekr.20131004073415.16044"><vh>Clones</vh></v>
<v t="ekr.20131018100353.16706"><vh>Clones accelerate work flow by creating views</vh></v>
<v t="ekr.20131009100732.16760"><vh>Using abbreviations and templates</vh></v>
<v t="ekr.20131009100732.16737"><vh>Using URLs</vh></v>
<v t="ekr.20131008041326.16066"><vh>Summary</vh></v>
</v>
<v t="ekr.20131008041326.16241"><vh>@rst html\tutorial-rst3.html</vh>
<v t="ekr.20131008041326.16250"><vh>@rst-no-head links &amp; markup</vh></v>
<v t="ekr.20131001100335.15939"><vh>Overview</vh>
<v t="ekr.20131009100732.16754"><vh>Specify settings</vh></v>
<v t="ekr.20131009100732.16748"><vh>Create the @rst tree</vh></v>
<v t="ekr.20131009100732.16750"><vh>Give your document a title</vh></v>
<v t="ekr.20131009100732.16755"><vh>Special headlines</vh></v>
<v t="ekr.20131009100732.16751"><vh>Write your document</vh></v>
<v t="ekr.20131009100732.16752"><vh>Run the rst3 command</vh></v>
</v>
<v t="ekr.20131009100732.16753"><vh>Further study</vh></v>
<v t="ekr.20131005214621.16128"><vh>Summary</vh></v>
</v>
<v t="ekr.20131008041326.16245"><vh>@rst html\tutorial-programming.html</vh>
<v t="ekr.20131008041326.16252"><vh>@rst-no-head links &amp; markup</vh></v>
<v t="ekr.20131003040744.18222" a="O"><vh>Creating source code with @others</vh></v>
<v t="ekr.20131008041326.16054"><vh>Using @first and @last</vh></v>
<v t="ekr.20131008041326.16055"><vh>Using @path</vh></v>
<v t="ekr.20131016021541.16894"><vh>Using @edit nodes</vh></v>
<v t="ekr.20131008041326.16056"><vh>Using @auto nodes</vh></v>
<v t="ekr.20131008041326.16246"><vh>Summary</vh></v>
</v>
<v t="ekr.20040403171740"><vh>@rst html\tutorial-scripting.html</vh>
<v t="ekr.20050812134441.1"><vh>@rst-no-head markup &amp; links</vh></v>
<v t="ekr.20131013060803.16852"><vh>Hello world</vh></v>
<v t="ekr.20070120075236"><vh>Predefined symbols: c, g and p</vh></v>
<v t="ekr.20131014053720.16810"><vh>Vnodes</vh></v>
<v t="ekr.20131014050027.16801"><vh>Positions</vh></v>
<v t="ekr.20131012060912.16775"><vh>Generators</vh></v>
<v t="ekr.20131014053720.16809"><vh>Capturing positions</vh></v>
<v t="ekr.20131016084446.16726"><vh>Further study</vh></v>
<v t="ekr.20101124083644.5052"><vh>Autocompletion</vh></v>
<v t="ekr.20131017051340.16815"><vh>Calltips</vh></v>
<v t="ekr.20050903161843"><vh>Using @button nodes</vh></v>
<v t="ekr.20131008041326.16058"><vh>Using @test nodes</vh></v>
<v t="ekr.20131016021541.16893"><vh>Summary</vh></v>
<v t="ekr.20131017051340.16732"><vh>@rst-ignore-tree scripting examples</vh>
<v t="ekr.20131017051340.16733"><vh>An example outline</vh></v>
<v t="ekr.20131017051340.16735"><vh>Example position scripts</vh></v>
</v>
</v>
</v>
<v t="ekr.20131008041326.16080"><vh>Users Guide</vh>
<v t="ekr.20131008041326.16082"><vh>@rst html/usersguide.html</vh></v>
<v t="EKR.20040524104904.211"><vh>Customizing Leo</vh>
<v t="ekr.20050901101608.4"><vh>@rst html\customizing.html</vh>
<v t="ekr.20050901102055"><vh>@rst-no-head links</vh></v>
<v t="EKR.20040524104904.140"><vh>Specifying settings</vh>
<v t="ekr.20090116130002.1"><vh>Configuration directories</vh></v>
<v t="ekr.20090116094356.2"><vh>Search order for settings files</vh></v>
<v t="ekr.20090116094356.3"><vh>Safe rules for local settings</vh></v>
<v t="ekr.20070317043727"><vh>Organizer nodes</vh></v>
<v t="ekr.20080411111008.1"><vh>\@ignore and \@if nodes</vh></v>
<v t="ekr.20070317043727.2"><vh>Simple settings nodes</vh></v>
<v t="ekr.20070317043727.3"><vh>Complex settings nodes</vh>
<v t="ekr.20090116094356.5"><vh>\@button</vh></v>
<v t="ekr.20090116094356.6"><vh>\@commands</vh></v>
<v t="ekr.20090116094356.7"><vh>\@data</vh></v>
<v t="ekr.20090116094356.8"><vh>\@enabled-plugins</vh></v>
<v t="ekr.20090116094356.11"><vh>\@font</vh></v>
<v t="ekr.20090116094356.10"><vh>\@menuat</vh></v>
<v t="ekr.20090116094356.9"><vh>\@menus</vh></v>
<v t="ekr.20090116094356.14"><vh>\@mode</vh></v>
<v t="ekr.20090116094356.13"><vh>\@recentfiles</vh></v>
<v t="ekr.20090116094356.12"><vh>\@shortcuts</vh></v>
</v>
</v>
<v t="ekr.20060105214753"><vh>Input modes</vh></v>
<v t="ekr.20050306090601"><vh>Adding extensible attributes to nodes and .leo files</vh></v>
<v t="ekr.20080310093038.4"><vh>Translating Leo's menus and messages</vh></v>
<v t="ekr.20100122073254.11655"><vh>Writing new importers</vh></v>
</v>
</v>
<v t="ekr.20050831184021.1"><vh>Creating documents with the rst3 Command</vh>
<v t="ekr.20050818163826"><vh>@rst html\rstplugin3.html</vh>
<v t="ekr.20050818163826.1"><vh>@rst-no-head links</vh></v>
<v t="ekr.20100810203016.4296"><vh>@rst-ignore</vh>
<v t="ekr.20050818163826.6"><vh>Options that set command names</vh></v>
<v t="ekr.20050818163826.4"><vh>Advanced topics</vh>
<v t="ekr.20100810203016.4298"><vh>Modes</vh></v>
<v t="ekr.20100810091118.4301"><vh>Code mode options</vh></v>
<v t="ekr.20100810091118.4306"><vh>Rst mode options</vh></v>
<v t="ekr.20050818163826.10"><vh>The code-block directive</vh></v>
</v>
</v>
<v t="ekr.20100809162244.4289"><vh>Tutorial</vh>
<v t="ekr.20100809162244.4292"><vh>Step 1: Create the @rst node</vh>
<v t="ekr.20100809162244.4298"><vh>Set global options</vh></v>
<v t="ekr.20100809162244.4297"><vh>Set your document's title</vh></v>
</v>
<v t="ekr.20100809162244.4295"><vh>Step 2: Write your document</vh></v>
<v t="ekr.20100809162244.4296"><vh>Step 3: Run the rst3 command</vh></v>
<v t="ekr.20100809162244.4301"><vh>Go forth and experiment</vh></v>
</v>
<v t="ekr.20100813075851.4296"><vh>Options</vh>
<v t="ekr.20100809122216.4286"><vh>General options</vh></v>
<v t="ekr.20050818163826.7"><vh>Headline commands</vh></v>
<v t="ekr.20050818163826.8"><vh>Option doc parts</vh></v>
<v t="ekr.20050818163826.9"><vh>Defaults for options</vh></v>
<v t="ekr.20050818163826.5"><vh>Http plugin options</vh></v>
<v t="ekr.20110612104631.16414"><vh>Section expansion options</vh></v>
</v>
<v t="ekr.20100813075851.4297"><vh>Other topics</vh>
<v t="ekr.20100810091118.4298"><vh>Markup doc parts</vh></v>
<v t="ekr.20050818163826.11"><vh>Required cascading style sheets</vh></v>
<v t="ekr.20060527103630"><vh>Controlling the rst3 command from scripts</vh></v>
</v>
<v t="ekr.20050818163826.13"><vh>Further study</vh></v>
<v t="ekr.20050818163826.16"><vh>Acknowledgements</vh></v>
<v t="ekr.20050818163826.14"><vh>Theory of operation</vh></v>
</v>
</v>
<v t="ekr.20050912125144"><vh>Plugins</vh>
<v t="ekr.20050912125144.1"><vh>@rst html\plugins.html</vh>
<v t="ekr.20050912125735"><vh>@rst-no-head links</vh></v>
<v t="ekr.20070814104719"><vh>Enabling plugins</vh></v>
<v t="ekr.20101113063552.9398"><vh>Summary</vh></v>
<v t="ekr.20130815102041.15619"><vh>Recently added plugins</vh>
<v t="ekr.20130815102041.15628"><vh>leomylyn.py</vh></v>
<v t="ekr.20130815102041.15618"><vh>printing.py</vh></v>
<v t="ekr.20130815102041.15630"><vh>screen_capture.py</vh></v>
<v t="ekr.20130815102041.15631"><vh>screencast.py</vh></v>
<v t="ekr.20130815102041.15632"><vh>timestamp.py</vh></v>
</v>
<v t="ekr.20101113063552.9528"><vh>Gui-independent plugins</vh>
<v t="ekr.20101113063552.9412"><vh>Commands &amp; directives</vh>
<v t="ekr.20101113063552.9413"><vh>add_directives.py</vh></v>
<v t="ekr.20101113063552.9414"><vh>bzr_qcommands.py</vh></v>
<v t="ekr.20101113063552.9415"><vh>empty_leo_file.py</vh></v>
<v t="ekr.20101113063552.9416"><vh>import_cisco_config.py</vh></v>
<v t="ekr.20101113063552.9417"><vh>initinclass.py</vh></v>
<v t="ekr.20101113063552.9418"><vh>leo_interface.py</vh></v>
<v t="ekr.20101113063552.9419"><vh>lineNumbers.py</vh></v>
<v t="ekr.20101113063552.9420"><vh>macros.py</vh></v>
<v t="ekr.20101113063552.9421"><vh>mod_autosave.py</vh></v>
<v t="ekr.20101113063552.9422"><vh>mod_read_dir_outline.py</vh></v>
<v t="ekr.20101113063552.9423"><vh>mod_timestamp.py</vh></v>
<v t="ekr.20101113063552.9798"><vh>nodeActions.py</vh></v>
<v t="ekr.20101113063552.9425"><vh>outline_export.py</vh></v>
<v t="ekr.20101113063552.9426"><vh>paste_as_headlines.py</vh></v>
<v t="ekr.20101113063552.9427"><vh>pretty_print.py</vh></v>
<v t="ekr.20101113063552.9428"><vh>quickMove.py</vh></v>
<v t="ekr.20101113063552.9429"><vh>setHomeDirectory.py</vh></v>
<v t="ekr.20101113063552.9430"><vh>word_count.py</vh></v>
</v>
<v t="ekr.20101113063552.9431"><vh>Debugging</vh>
<v t="ekr.20101113063552.9432"><vh>debugger_pudb.py</vh></v>
<v t="ekr.20101113063552.9433"><vh>dump_globals.py</vh></v>
<v t="ekr.20101113063552.9434"><vh>enable_gc.py</vh></v>
<v t="ekr.20101113063552.9435"><vh>quit_leo.py</vh></v>
<v t="ekr.20101113063552.9436"><vh>trace_gc_plugin.py</vh></v>
<v t="ekr.20101113063552.9437"><vh>trace_keys.py</vh></v>
<v t="ekr.20101113063552.9438"><vh>trace_tags.py</vh></v>
</v>
<v t="ekr.20101113063552.9439"><vh>External programs</vh>
<v t="ekr.20101113063552.9440"><vh>ipython.py</vh></v>
<v t="ekr.20101113063552.9441"><vh>mod_tempfname.py</vh></v>
<v t="ekr.20101113063552.9442"><vh>open_shell.py</vh></v>
<v t="ekr.20101113063552.9443"><vh>tomboy_import.py</vh></v>
<v t="ekr.20101113063552.9444"><vh>vim.py</vh></v>
<v t="ekr.20101113063552.9445"><vh>xemacs.py</vh></v>
<v t="ekr.20101113063552.9446"><vh>word_export.py</vh></v>
</v>
<v t="ekr.20101113063552.9447"><vh>Files and nodes</vh>
<v t="ekr.20101113063552.9448"><vh>active_path.py</vh></v>
<v t="ekr.20101113063552.9449"><vh>at_folder.py</vh></v>
<v t="ekr.20101113063552.9450"><vh>at_produce.py</vh></v>
<v t="ekr.20101113063552.9451"><vh>at_view.py</vh></v>
<v t="ekr.20101113063552.9452"><vh>backlink.py</vh></v>
<v t="ekr.20101113063552.9453"><vh>datenodes.py</vh></v>
<v t="ekr.20101113063552.9454"><vh>expfolder.py</vh></v>
<v t="ekr.20101113063552.9455"><vh>FileActions.py</vh></v>
<v t="ekr.20101113063552.9456"><vh>geotag.py</vh></v>
<v t="ekr.20101113063552.9457"><vh>leocursor.py</vh></v>
<v t="ekr.20101113063552.9458"><vh>mime.py</vh></v>
<v t="ekr.20101113063552.9459"><vh>multifile.py</vh></v>
<v t="ekr.20101113063552.9460"><vh>niceNosent.py</vh></v>
<v t="ekr.20101113063552.9461"><vh>read_only_nodes.py</vh></v>
<v t="ekr.20101113063552.9462"><vh>run_nodes.py</vh></v>
<v t="ekr.20101113063552.9464"><vh>startfile.py</vh></v>
<v t="ekr.20101113063552.9466"><vh>xsltWithNodes.py</vh></v>
</v>
<v t="ekr.20101113063552.9467"><vh>Scripting</vh>
<v t="ekr.20050912125735.363"><vh>dyna_menu</vh></v>
<v t="ekr.20101113063552.9468"><vh>leoscreen.py</vh></v>
<v t="ekr.20101113063552.9469"><vh>mod_scripting.py</vh></v>
<v t="ekr.20101113063552.9470"><vh>script_io_to_body.py</vh></v>
</v>
<v t="ekr.20101113063552.9471"><vh>Servers</vh>
<v t="ekr.20101113063552.9472"><vh>leoremote.py</vh></v>
<v t="ekr.20101113063552.9473"><vh>mod_http.py</vh></v>
</v>
<v t="ekr.20101113063552.9474"><vh>Slideshows and screenshots</vh>
<v t="ekr.20101113063552.9475"><vh>screenshots.py</vh></v>
<v t="ekr.20101113063552.9463"><vh>slideshow.py</vh></v>
</v>
<v t="ekr.20101113063552.9476"><vh>Text formatting</vh>
<v t="ekr.20101113063552.9477"><vh>bibtex.py</vh></v>
<v t="ekr.20101113063552.9478"><vh>dtest.py</vh></v>
<v t="ekr.20101113063552.9800"><vh>leo_to_html.py</vh></v>
<v t="ekr.20101113063552.9480"><vh>leo_to_rtf.py</vh></v>
</v>
<v t="ekr.20101113063552.9482"><vh>User interface</vh>
<v t="ekr.20101113063552.9483"><vh>UNL.py</vh></v>
<v t="ekr.20101113063552.9484"><vh>chapter_hoist.py</vh></v>
<v t="ekr.20101113063552.9485"><vh>detect_urls.py</vh></v>
<v t="ekr.20101113063552.9486"><vh>EditAttributes.py</vh></v>
<v t="ekr.20101113063552.9487"><vh>interact.py</vh></v>
<v t="ekr.20101113063552.9488"><vh>maximizeNewWindows.py</vh></v>
<v t="ekr.20101113063552.9489"><vh>mod_framesize.py</vh></v>
<v t="ekr.20101113063552.9794"><vh>plugins_menu.py</vh></v>
<v t="ekr.20101113063552.9491"><vh>redirect_to_log.py</vh></v>
<v t="ekr.20101113063552.9492"><vh>scripts_menu.py</vh></v>
<v t="ekr.20101113063552.9493"><vh>zenity_file_dialogs.py</vh></v>
</v>
</v>
<v t="ekr.20101113063552.9399"><vh>Qt only plugins</vh>
<v t="ekr.20101113063552.9400"><vh>attrib_edit.py</vh></v>
<v t="ekr.20131009100732.19039"><vh>bookmarks.py</vh></v>
<v t="ekr.20101113063552.9401"><vh>colorize_headlines.py</vh></v>
<v t="ekr.20101113063552.9402"><vh>contextmenu.py</vh></v>
<v t="ekr.20101113063552.9403"><vh>nav_qt.py</vh></v>
<v t="ekr.20101113063552.9404"><vh>projectwizard.py</vh></v>
<v t="ekr.20101113063552.9405"><vh>quicksearch.py</vh></v>
<v t="ekr.20101113063552.9406"><vh>scrolledmessage.py</vh></v>
<v t="ekr.20101113063552.9407"><vh>spydershell.py</vh></v>
<v t="ekr.20101113063552.9408"><vh>stickynotes.py</vh></v>
<v t="ekr.20101113063552.9409"><vh>todo.py</vh></v>
<v t="ekr.20131009100732.19040"><vh>valuespace.py</vh></v>
<v t="ekr.20101113063552.9410"><vh>viewrendered.py</vh></v>
<v t="ekr.20101113063552.9411"><vh>graphcanvas.py</vh></v>
</v>
</v>
</v>
<v t="ekr.20131005214621.16130"><vh>Directives Reference</vh>
<v t="ekr.20131009065148.31758"><vh>@rst html/directives.html</vh>
<v t="ekr.20050828160132"><vh>@rst-no-head links</vh></v>
<v t="ekr.20100806170836.4392"><vh>Part 1: \@&lt;file&gt; directives</vh>
<v t="ekr.20100806170836.4393"><vh>\@asis &lt;path&gt;</vh></v>
<v t="ekr.20100806170836.4396"><vh>\@auto &lt;path&gt;</vh></v>
<v t="ekr.20100806170836.4395"><vh>\@edit &lt;path&gt;</vh></v>
<v t="ekr.20100806170836.4403"><vh>\@file &lt;path&gt; (aka @thin)</vh></v>
<v t="ekr.20100806170836.4399"><vh>\@nosent &lt;path&gt;</vh></v>
<v t="ekr.20100806170836.4402"><vh>\@shadow &lt;path&gt;</vh></v>
</v>
<v t="ekr.20100806170836.4411"><vh>Part 2: \@all and \@others</vh></v>
<v t="ekr.20100806170836.4398"><vh>Part 3: Syntax coloring directives</vh></v>
<v t="ekr.20100806170836.4408"><vh>Part 4: Dangerous directives</vh></v>
<v t="ekr.20100804133903.7262"><vh>Part 5: All other directives</vh></v>
</v>
</v>
<v t="EKR.20040524104904.99"><vh>Commands Reference</vh>
<v t="ekr.20050901101608.2"><vh>@rst html\commands.html</vh>
<v t="ekr.20050901101852"><vh>@rst-no-head links</vh></v>
<v t="EKR.20040524104904.100"><vh>File commands</vh>
<v t="EKR.20040524104904.101"><vh>Loading, Saving and Reverting Files</vh></v>
<v t="EKR.20040524104904.102"><vh>Communicating with external editors</vh></v>
<v t="EKR.20040524104904.108"><vh>Importing Files into Leo Outlines</vh></v>
<v t="EKR.20040524104904.109"><vh>Exporting Files from Leo Outlines</vh></v>
<v t="EKR.20040524104904.110"><vh>Quitting Leo</vh></v>
</v>
<v t="EKR.20040524104904.111"><vh>Edit commands</vh>
<v t="EKR.20040524104904.112"><vh>Undoing changes</vh></v>
<v t="EKR.20040524104904.113"><vh>Cutting, pasting and selecting text</vh></v>
<v t="EKR.20040524104904.114"><vh>Indenting body text</vh></v>
<v t="ekr.20050313102319"><vh>Adding and deleting comments in body text</vh></v>
<v t="EKR.20040524104904.115"><vh>Creating nodes from body text</vh></v>
<v t="EKR.20040524104904.116"><vh>Converting leading blanks and tabs in body text</vh></v>
<v t="EKR.20040524104904.117"><vh>Executing Python scripts in body text</vh></v>
<v t="EKR.20040524104904.118"><vh>Finding and replacing text</vh>
<v t="ekr.20120319065417.8792"><vh>Overview</vh></v>
<v t="ekr.20120319065417.8790"><vh>Basic searches</vh></v>
<v t="ekr.20120319065417.8791"><vh>find-all, clone-find-all &amp; clone-find-all-flattened</vh></v>
<v t="ekr.20120319065417.8797"><vh>Replace commands</vh></v>
<v t="ekr.20120319065417.8798"><vh>Incremental find commands</vh></v>
<v t="ekr.20120319065417.8794"><vh>Commands that set find options</vh></v>
<v t="ekr.20120319065417.8795"><vh>Word search and regex search commands</vh></v>
<v t="ekr.20120319065417.8788"><vh>Find settings</vh></v>
</v>
<v t="EKR.20040524104904.134"><vh>Go To Line Number</vh></v>
<v t="EKR.20040524104904.136"><vh>Inserting the date and time</vh></v>
<v t="EKR.20040524104904.137"><vh>Reformatting paragraphs in body text</vh></v>
<v t="EKR.20040524104904.139"><vh>Matching brackets and parenthesis</vh></v>
<v t="ekr.20120319170934.6104"><vh>Indenting body text automatically</vh></v>
<v t="ekr.20120319170934.6105"><vh>Creating and destroying multiple body editors</vh></v>
<v t="ekr.20120319170934.6110"><vh>Using chapters</vh></v>
</v>
<v t="EKR.20040524104904.143"><vh>Outline commands</vh>
<v t="ekr.20120319170934.6096"><vh>Creating and destroying nodes</vh></v>
<v t="ekr.20120319170934.6095"><vh>Expanding &amp; contracting nodes</vh></v>
<v t="ekr.20120319170934.6097"><vh>Cutting, pasting and deleting nodes</vh></v>
<v t="ekr.20120319170934.6094"><vh>Navigating through the outline</vh></v>
<v t="ekr.20120319170934.6098"><vh>Moving &amp; Reorganizing nodes</vh></v>
<v t="ekr.20120319170934.6099"><vh>Cloning nodes</vh></v>
<v t="ekr.20120319170934.6100"><vh>Marking nodes</vh></v>
<v t="ekr.20120319170934.6101"><vh>Dragging nodes</vh></v>
<v t="EKR.20040524104904.148"><vh>Hoisting &amp; De-hoisting nodes</vh></v>
<v t="EKR.20040524104904.144"><vh>Checking outlines</vh></v>
<v t="ekr.20120319170934.6108"><vh>Resizing panes</vh></v>
</v>
<v t="EKR.20040524104904.151"><vh>Window commands</vh></v>
<v t="EKR.20040524104904.157"><vh>Help commands</vh></v>
</v>
</v>
</v>
<v t="ekr.20101025080245.5798"><vh>Leo and Other Programs</vh>
<v t="ekr.20131008041326.16100"><vh>@rst html/leoandotherprograms.html</vh></v>
<v t="ekr.20061025065357"><vh>Leo and Emacs</vh>
<v t="ekr.20061025065357.1"><vh>@rst html\emacs.html</vh>
<v t="ekr.20061025065357.2"><vh>@rst-no-head links</vh></v>
<v t="ekr.20061025081359"><vh>Controlling Leo from Emacs using Pymacs</vh></v>
<v t="ekr.20061025070825.1"><vh>Functions in leoPymacs.py</vh></v>
<v t="ekr.20061025142434"><vh>The minibuffer</vh></v>
</v>
</v>
<v t="ekr.20080203101507"><vh>ILeo - the IPython bridge</vh>
<v t="ekr.20080203101507.1"><vh>@rst html\IPythonBridge.html</vh>
<v t="ekr.20080203101507.2"><vh>@rst-no-head links</vh></v>
<v t="vivainio.20080302174639.1"><vh>Overview</vh></v>
<v t="vivainio.20080302174639.2"><vh>Starting ILeo</vh></v>
<v t="ekr.20131001045038.18981"><vh>Running Leo scripts from IPython</vh></v>
<v t="ekr.20131001045038.18980"><vh>Running IPython scripts from Leo</vh></v>
<v t="ekr.20131001045038.18979"><vh>ILeo as an IPython notebook</vh></v>
<v t="ekr.20131001045038.17448"><vh>Acknowledgements and history</vh></v>
</v>
</v>
<v t="ekr.20070317033759"><vh>Embedding Leo with the leoBridge module</vh>
<v t="ekr.20070317033759.1"><vh>@rst html\leoBridge.html</vh>
<v t="ekr.20070317033759.2"><vh>@rst-no-head links</vh></v>
<v t="ekr.20070317033759.3"><vh>The basics</vh></v>
<v t="ekr.20071210094621"><vh>Running leoBridge from within Leo</vh></v>
</v>
</v>
<v t="TL.20080804095315.1"><vh>Using Vim with Leo</vh>
<v t="TL.20080804095315.2"><vh>@rst html\vimBindings.html</vh>
<v t="TL.20080804095315.4"><vh>Installing vim bindings</vh></v>
<v t="TL.20080804095315.5"><vh>General commands</vh></v>
<v t="TL.20080804095315.6"><vh>Body pane commands</vh></v>
<v t="TL.20080804095315.7"><vh>Outline commands</vh></v>
<v t="TL.20080804095315.8"><vh>Commands not supported</vh></v>
<v t="TL.20080804095315.9"><vh>Avoiding changes to 'tag' files</vh></v>
</v>
</v>
<v t="ekr.20060913164304"><vh>Using ZODB with Leo</vh>
<v t="ekr.20060913164304.1"><vh>@rst html\zodb.html</vh>
<v t="ekr.20060913164311"><vh>@rst-no-head links</vh></v>
<v t="ekr.20060913170145"><vh>Configuring Leo to use zodb</vh></v>
<v t="ekr.20060913170403"><vh>Initing zodb</vh></v>
<v t="ekr.20060913170403.1"><vh>Writing data to zodb</vh></v>
<v t="ekr.20060913175437"><vh>Defining zodb keys</vh></v>
<v t="ekr.20060913170403.2"><vh>Reading data from zodb</vh></v>
<v t="ekr.20060913175437.1"><vh>About connections</vh></v>
<v t="ekr.20060913165542.1"><vh>Convenience routines</vh>
<v t="ekr.20060913165542.2"><vh>g.init_zodb (pathToZodbStorage,verbose=True)</vh></v>
<v t="ekr.20060913165542.3"><vh>v.detach()</vh></v>
</v>
</v>
</v>
</v>
<v t="ekr.20101025080245.5799"><vh>Advanced Topics</vh>
<v t="ekr.20131008041326.16099"><vh>@rst html/intermediatetopics.html</vh></v>
<v t="ekr.20060430221745"><vh>Controlling syntax coloring</vh>
<v t="ekr.20060430221745.1"><vh>@rst html\coloring.html</vh>
<v t="ekr.20060430222753"><vh>@rst-no-head links</vh></v>
<v t="ekr.20060830142929"><vh>Syntax coloring settings</vh></v>
<v t="ekr.20060430220749"><vh>Files</vh></v>
<v t="ekr.20060502084233"><vh>The colorizer's inner loop</vh></v>
<v t="ekr.20060502084233.1"><vh>Format of colorizer control files</vh>
<v t="ekr.20060502100550"><vh>Ruleset names</vh></v>
<v t="ekr.20060502090516"><vh>x.properties</vh></v>
<v t="ekr.20060510085547"><vh>Attribute dictionaries and x.attributesDictDict</vh></v>
<v t="ekr.20060502090516.1"><vh>Keyword dictionaries and x.keywordsDictDict</vh></v>
<v t="ekr.20060502090516.2"><vh>Rules, rules dictionaries and x.rulesDictDict</vh></v>
<v t="ekr.20060503072213"><vh>x.importDict and imported versus delegated rulesets</vh></v>
</v>
<v t="ekr.20060502122950"><vh>Rule methods</vh>
<v t="ekr.20060503064515"><vh>Arguments to rule methods</vh></v>
<v t="ekr.20060502122950.7"><vh>match_eol_span</vh></v>
<v t="ekr.20060502122950.10"><vh>match_eol_span_regexp</vh></v>
<v t="ekr.20060502122950.13"><vh>match_keywords</vh></v>
<v t="ekr.20060502122950.14"><vh>match_mark_following</vh></v>
<v t="ekr.20060502125223"><vh>match_mark_previous</vh></v>
<v t="ekr.20060502122950.40"><vh>match_seq</vh></v>
<v t="ekr.20060502122950.41"><vh>match_seq_regexp</vh></v>
<v t="ekr.20060502122950.42"><vh>match_span</vh></v>
<v t="ekr.20060502122950.47"><vh>match_span_regexp</vh></v>
<v t="ekr.20060502122950.48"><vh>match_terminate</vh></v>
</v>
</v>
</v>
<v t="ekr.20060612102055"><vh>Writing Plugins</vh>
<v t="ekr.20060612103240"><vh>@rst html\writingPlugins.html</vh>
<v t="ekr.20060612103824"><vh>@rst-no-head links</vh></v>
<v t="ekr.20131008041326.16053"><vh>Writing Plugins</vh></v>
<v t="EKR.20040524104904.224"><vh>Important security warnings</vh></v>
<v t="peckj.20130813123907.6841"><vh>Documenting plugins</vh></v>
<v t="ekr.20131012191145.16789"><vh>c ivars &amp; properties</vh></v>
<v t="ekr.20050903074833"><vh>Handling events</vh>
<v t="ekr.20050903074833.1"><vh>Summary of event handlers</vh></v>
</v>
<v t="EKR.20040524104904.240"><vh>Support for unit testing</vh></v>
</v>
</v>
<v t="ekr.20070628083442"><vh>Unit testing with Leo</vh>
<v t="ekr.20070628083442.1"><vh>@rst html\unitTesting.html</vh>
<v t="ekr.20070628083442.2"><vh>@rst-no-head links</vh></v>
<v t="ekr.20070628084351"><vh>Using @test nodes</vh></v>
<v t="ekr.20070628094515.1"><vh>Using @suite nodes</vh></v>
<v t="ekr.20120229094652.15125"><vh>Using @mark-for-unit-tests</vh></v>
<v t="ekr.20070628094515.2"><vh>How the unit test commands work</vh></v>
<v t="ekr.20080729064227.6"><vh>\@button timer</vh></v>
<v t="ekr.20080729064227.7"><vh>\@button profile</vh></v>
</v>
</v>
<v t="ekr.20060527105211"><vh>Debugging with Leo</vh>
<v t="ekr.20060527105617"><vh>@rst html\debuggers.html</vh>
<v t="ekr.20060527105804"><vh>@rst-no-head links</vh></v>
<v t="ekr.20070116062405"><vh>Using g.trace and g.pdb</vh></v>
<v t="ekr.20060527112801"><vh>Settings for winpdb</vh></v>
<v t="ekr.20070115172724"><vh>Debugging scripts with winpdb</vh>
<v t="ekr.20070115172724.1"><vh>The debug command</vh></v>
<v t="ekr.20070115172724.3"><vh>The execute-script command with explicit debugger breaks</vh></v>
</v>
</v>
</v>
<v t="ekr.20080730212711.14"><vh>Using @shadow</vh>
<v t="ekr.20080730212711.15"><vh>@rst html\atShadow.html</vh>
<v t="ekr.20080730212711.16"><vh>@rst-no-head links</vh></v>
<v t="ekr.20080730212711.39"><vh>Overview</vh></v>
<v t="ekr.20080730212711.42"><vh>Creating @shadow trees</vh></v>
<v t="ekr.20080730212711.40"><vh>What the update algorithm does</vh></v>
<v t="ekr.20080730212711.52"><vh>Aha: boundary cases don't matter</vh></v>
</v>
</v>
<v t="ekr.20131015104133.16763"><vh>A scripting miscellany</vh>
<v t="ekr.20131015091948.16784"><vh>@rst html\scripting-miscellany.html</vh>
<v t="ekr.20110531155858.20563"><vh>Creating minimal outlines</vh></v>
<v t="ekr.20111115063523.13619"><vh>Creating Qt Windows from Leo scripts</vh></v>
<v t="ekr.20071026183116"><vh>g.app.gui.run* methods run dialogs</vh></v>
<v t="ekr.20040403173920.19"><vh>Getting commander preferences</vh></v>
<v t="ekr.20050907094633"><vh>Getting configuration settings</vh></v>
<v t="ekr.20080922124033.1"><vh>Getting interactive input from scripts</vh></v>
<v t="ekr.20080109074102"><vh>Inserting and deleting icons</vh></v>
<v t="ekr.20040403173920.18"><vh>Invoking commands from scripts</vh></v>
<v t="ekr.20050417072710.1"><vh>Making operations undoable</vh></v>
<v t="ekr.20100506062734.11593"><vh>Modifying plugins with @script scripts</vh></v>
<v t="ekr.20090223065025.3"><vh>Modifying the body pane directly</vh></v>
<v t="ekr.20070122093626"><vh>Recovering vnodes</vh></v>
<v t="ekr.20120317130339.8282"><vh>Retaining pointers to Qt windows</vh></v>
<v t="ekr.20040403173920.24"><vh>Running Leo in batch mode</vh></v>
<v t="ekr.20081205084002.2"><vh>Working with directives and paths</vh></v>
<v t="ekr.20131012060912.16788"><vh>Writing g.es output to other tabs</vh></v>
<v t="ekr.20131014053720.16816"><vh>\@button example</vh></v>
</v>
</v>
<v t="ekr.20131008041326.16178"><vh>Exploring Leo's Code Base</vh>
<v t="ekr.20131009065148.31760"><vh>@rst html/theory.html</vh>
<v t="ekr.20131011050613.16868"><vh>How to explore Leo's sources</vh>
<v t="ekr.20131012060912.16768"><vh>Finding commands</vh></v>
<v t="ekr.20131011050613.16870"><vh>Finding key-handling code</vh></v>
<v t="ekr.20131011050613.16871"><vh>Finding redraw and refocus code</vh></v>
<v t="ekr.20131011050613.16862"><vh>Debugging with g.trace, g.callers &amp; g.pdb</vh></v>
</v>
<v t="ekr.20131012060912.16769"><vh>Special topics</vh>
<v t="ekr.20131011050613.16860"><vh>The design of Leo's classes</vh></v>
<v t="ekr.20131011050613.16876"><vh>Fragile methods</vh></v>
<v t="ekr.20131011050613.16866"><vh>Read long comments with caution</vh></v>
<v t="ekr.20131011050613.16815"><vh>Startup</vh></v>
<v t="EKR.20040524104904.268"><vh>Unicode</vh></v>
<v t="ekr.20131012060912.16770"><vh>Why key handling is complex</vh></v>
</v>
</v>
</v>
<v t="ekr.20131019035402.17557"><vh>The Leonine world</vh>
<v t="ekr.20131019035402.17573"><vh>@rst html\leonine-world.html</vh></v>
</v>
</v>
<v t="ekr.20131008041326.16091"><vh>Cheat Sheet</vh>
<v t="ekr.20131007143750.16070"><vh>@rst html\cheatsheet.html</vh>
<v t="ekr.20131019061259.16693"><vh>Key bindings</vh>
<v t="ekr.20131015035606.16778"><vh>Selecting outline nodes</vh></v>
<v t="ekr.20131015035606.16800"><vh>Moving outline nodes</vh></v>
<v t="ekr.20131015035606.16780"><vh>Moving the cursor</vh></v>
</v>
<v t="ekr.20131015035606.16801"><vh>Frequently used commands</vh></v>
<v t="ekr.20131015035606.16786"><vh>Leo directives</vh></v>
<v t="ekr.20131015035606.16788"><vh>Settings</vh></v>
<v t="ekr.20131016103844.16730"><vh>Notable Plugins</vh></v>
<v t="ekr.20131015035606.16799"><vh>External files (@&lt;file&gt; nodes)</vh></v>
<v t="ekr.20131007143750.16074"><vh>Scripting</vh>
<v t="ekr.20131019061259.16686"><vh>Pre-defined symbols</vh></v>
<v t="ekr.20131019061259.16687"><vh>Generators</vh></v>
<v t="ekr.20131019061259.16688"><vh>Commands class</vh></v>
<v t="ekr.20131019061259.16690"><vh>vnode class</vh></v>
<v t="ekr.20131019061259.16691"><vh>position class</vh></v>
<v t="ekr.20131019061259.16692"><vh>leo.core.leoGlobals module</vh></v>
</v>
</v>
</v>
<v t="ekr.20050831184021.5"><vh>Appendices &amp; glossary</vh>
<v t="ekr.20131008041326.16341"><vh>@rst html/appendices.html</vh>
<v t="ekr.20050831232205"><vh>@rst-no-head links</vh></v>
<v t="EKR.20040524104904.357"><vh>Format of .leo files</vh></v>
<v t="ekr.20060921064744.1"><vh>Format of external files</vh></v>
<v t="EKR.20040524104904.354"><vh>Unicode reference</vh></v>
<v t="ekr.20120319170934.6109"><vh>Valid URL's</vh></v>
<v t="ekr.20131008041326.16177"><vh>History of Leo</vh>
<v t="ekr.20050901102147"><vh>@rst-no-head links</vh></v>
<v t="ekr.20050902105852"><vh>Beginnings</vh></v>
<v t="ekr.20050902105852.1"><vh>Breakthrough</vh></v>
<v t="ekr.20050902105852.2"><vh>Apple and YellowBox</vh></v>
<v t="ekr.20050902105852.3"><vh>Borland C++</vh></v>
<v t="ekr.20050902105852.4"><vh>Discovering Python</vh></v>
<v t="ekr.20050902105852.5"><vh>SourceForge</vh></v>
<v t="ekr.20050902105852.6"><vh>Allowing sentinel lines in external files</vh></v>
<v t="ekr.20050902105852.7"><vh>Untangling @file is easy!</vh></v>
<v t="ekr.20050902105852.8"><vh>Leo 3.x: Continuous improvement</vh></v>
<v t="ekr.20050902105852.9"><vh>Leo 4.0: Eliminating error 'recovery'</vh></v>
<v t="ekr.20050902105852.10"><vh>Leo 4.1: The debut of gnx's</vh></v>
<v t="ekr.20050902105852.11"><vh>Leo 4.2: Complete at last</vh></v>
<v t="ekr.20050902105852.12"><vh>Leo 4.3 Settings</vh></v>
<v t="ekr.20060629083935"><vh>Leo 4.4 The minibuffer and key bindings</vh></v>
<v t="ekr.20080315115427.568"><vh>Leo 4.4.x Improvements</vh></v>
<v t="ekr.20101025080245.6085"><vh>Leo 4.5 @shadow files</vh></v>
<v t="ekr.20101025080245.6086"><vh>Leo 4.6 Caching, Qt and more</vh></v>
<v t="ekr.20101025080245.6087"><vh>Leo 4.7 The one node world and Python 3k</vh></v>
<v t="ekr.20101025080245.6089"><vh>Leo 4.8 Simple sentinels &amp; better data recovery</vh></v>
<v t="ekr.20131008041326.16253"><vh>Leo 4.9 Qt, autocompleter, vr pane</vh></v>
<v t="ekr.20050902100834"><vh>@rst-ignore-tree Details</vh>
<v t="EKR.20040524104904.247"><vh>Versions</vh></v>
<v t="EKR.20040524104904.248"><vh>Designing @file trees</vh>
<v t="EKR.20040524104904.249"><vh>Deciding to do Leo2</vh></v>
<v t="EKR.20040524104904.250"><vh>A prototype</vh></v>
<v t="EKR.20040524104904.251"><vh>User interaction</vh></v>
<v t="EKR.20040524104904.252"><vh>The write code</vh></v>
<v t="EKR.20040524104904.253"><vh>The read code</vh></v>
<v t="EKR.20040524104904.254"><vh>The load/save code</vh></v>
<v t="EKR.20040524104904.255"><vh>Attributes, mirroring and dummy nodes</vh></v>
<v t="EKR.20040524104904.256"><vh>Clones</vh></v>
<v t="EKR.20040524104904.257"><vh>Error recovery, at last</vh></v>
</v>
</v>
</v>
<v t="ekr.20050901084134"><vh>Why I like Python</vh>
<v t="ekr.20050901092232.2"><vh>Clarity</vh></v>
<v t="ekr.20050901092232.3"><vh>Power</vh></v>
<v t="ekr.20050901092232.4"><vh>Safety</vh></v>
<v t="ekr.20050901092232.5"><vh>Speed</vh></v>
<v t="ekr.20050901092232.6"><vh>Conclusions</vh></v>
</v>
</v>
<v t="ekr.20091111112709.6672"><vh>@rst html/glossary.html</vh>
<v t="ekr.20100804133903.7250"><vh>\@</vh></v>
<v t="ekr.20100804133903.7251"><vh>A - C</vh></v>
<v t="ekr.20100804133903.7252"><vh>D - G</vh></v>
<v t="ekr.20100804133903.7253"><vh>H - L</vh></v>
<v t="ekr.20100804133903.7254"><vh>M - O</vh></v>
<v t="ekr.20100804133903.7255"><vh>P - R</vh></v>
<v t="ekr.20100804133903.7256"><vh>S - Z</vh></v>
</v>
</v>
<v t="ekr.20060620094033"><vh>What's New...</vh>
<v t="ekr.20101025080245.5791"><vh>@rst html/what-is-new.html</vh>
<v t="ekr.20071116062917.2"><vh>@rst-no-head links</vh></v>
<v t="ekr.20120320153011.6055"><vh>Leo 4.10</vh>
<v t="ekr.20120320153011.8400"><vh>New features &amp; commands</vh>
<v t="ekr.20120320153011.8201"><vh>Weightless unit testing</vh></v>
</v>
<v t="ekr.20120320153011.6808"><vh>Plugins</vh></v>
<v t="ekr.20120320153011.8537"><vh>Scripts</vh></v>
<v t="ekr.20120320153011.6826"><vh>Settings</vh></v>
<v t="ekr.20120320153011.6056"><vh>Bugs fixed</vh></v>
</v>
<v t="ekr.20120320153011.8551"><vh>Previous versions</vh>
<v t="ekr.20110601105631.19349"><vh>Leo 4.9</vh>
<v t="ekr.20110601105631.19360"><vh>Bugs fixed</vh></v>
<v t="ekr.20110601105631.19484"><vh>Deprecated/removed features</vh></v>
<v t="ekr.20110601105631.19481"><vh>Major improvements</vh>
<v t="ekr.20110602091552.16899"><vh>Completed Leo's autocompleter</vh></v>
<v t="ekr.20110602091552.16898"><vh>Greatly improved the viewrendered plugin</vh></v>
</v>
<v t="ekr.20110601105631.19434"><vh>New and improved features</vh>
<v t="ekr.20110601105631.19435"><vh>Colorizing</vh></v>
<v t="ekr.20110601105631.19480"><vh>Command-line arguments &amp; settings</vh></v>
<v t="ekr.20110601105631.19464"><vh>File handling</vh></v>
<v t="ekr.20110601105631.19441"><vh>Gui</vh></v>
<v t="ekr.20110601105631.19482"><vh>Improved commands</vh></v>
<v t="ekr.20110601105631.19463"><vh>New commands</vh></v>
<v t="ekr.20110601105631.19473"><vh>Scripting</vh></v>
</v>
<v t="ekr.20110604105805.16766"><vh>New in 4.9 b2</vh></v>
<v t="ekr.20110611085637.5009"><vh>New in 4.9 b3</vh>
<v t="ekr.20110611085637.5010"><vh>4.9 b3: Bugs fixed</vh></v>
<v t="ekr.20110611085637.5012"><vh>4.9 b3: New features</vh></v>
</v>
<v t="ekr.20110613172008.15106"><vh>New in 4.9 b4</vh></v>
<v t="ekr.20110616100929.14851"><vh>New in 4.9 rc1</vh></v>
</v>
<v t="ekr.20101025080245.5805"><vh>Leo 4.8</vh>
<v t="ekr.20101025080245.6077"><vh>New sentinels</vh></v>
<v t="ekr.20101025080245.6078"><vh>Drag and drop files into Leo</vh></v>
<v t="ekr.20101025080245.5980"><vh>Scripting improvements</vh></v>
<v t="ekr.20101025080245.6080"><vh>Improved @url nodes</vh></v>
<v t="ekr.20101104173324.5141"><vh>New &amp; improved commands</vh>
<v t="ekr.20101025080245.6079"><vh>Improved abbreviations commands</vh></v>
</v>
<v t="ekr.20101025080245.6081"><vh>New plugins</vh></v>
<v t="ekr.20101025080245.6006"><vh>New settings &amp; command-line args</vh></v>
<v t="ekr.20101025080245.5985"><vh>Other improvements</vh></v>
</v>
<v t="ekr.20100129054823.11924"><vh>Leo 4.7</vh>
<v t="ekr.20101025080245.6088"><vh>The one-node world</vh></v>
<v t="ekr.20100129054823.17680"><vh>Leo supports Python 3.x</vh></v>
<v t="ekr.20100129054823.11928"><vh>Improved file handling</vh></v>
<v t="ekr.20100129054823.11931"><vh>New command-line options</vh></v>
<v t="ekr.20100211221936.7098"><vh>New commands</vh></v>
<v t="ekr.20100129054823.11934"><vh>New settings</vh></v>
<v t="ekr.20100129054823.11935"><vh>Improved plugins</vh></v>
</v>
<v t="ekr.20090324145450.20"><vh>Leo 4.6</vh>
<v t="ekr.20090620073906.12095"><vh>Improved unit testing</vh></v>
<v t="ekr.20090324145450.23"><vh>Improved file handling</vh></v>
<v t="ekr.20090620082840.5608"><vh>Improved handling of rST files</vh></v>
<v t="ekr.20090324145450.27"><vh>New code features</vh></v>
<v t="ekr.20090324145450.36"><vh>New command-line options</vh></v>
<v t="ekr.20090324145450.40"><vh>New commands</vh></v>
<v t="ekr.20090324145450.46"><vh>New and improved directives</vh></v>
<v t="ekr.20090324145450.49"><vh>New settings</vh></v>
<v t="ekr.20090324145450.54"><vh>Plugins</vh></v>
</v>
<v t="ekr.20080806211440.185"><vh>Leo 4.5</vh>
<v t="ekr.20080806211440.188"><vh>Major new features</vh></v>
<v t="ekr.20080806211440.253"><vh>Major code reorganizations</vh></v>
<v t="ekr.20080806211440.256"><vh>Minor new features</vh></v>
<v t="ekr.20080806211440.189"><vh>New settings</vh></v>
</v>
<v t="ekr.20080314081157.127"><vh>Leo 4.4.8</vh>
<v t="ekr.20080314081157.124"><vh>New features</vh></v>
<v t="ekr.20080314081157.128"><vh>New and improved plugins</vh></v>
<v t="ekr.20080314081157.125"><vh>New settings</vh></v>
</v>
<v t="ekr.20071217093444"><vh>Leo 4.4.6</vh>
<v t="ekr.20071217093444.5"><vh>New commands</vh></v>
<v t="ekr.20080116071239"><vh>New features</vh></v>
<v t="ekr.20071217093444.6"><vh>New settings</vh></v>
</v>
<v t="ekr.20071116062917"><vh>Leo 4.4.5</vh>
<v t="ekr.20071116063202"><vh>Bug fixed</vh></v>
<v t="ekr.20071116062917.3"><vh>New features</vh></v>
<v t="ekr.20071116062917.18"><vh>New commands</vh></v>
<v t="ekr.20071116063649"><vh>New settings</vh></v>
</v>
<v t="ekr.20070809145744"><vh>Leo 4.4.4</vh>
<v t="ekr.20071004103659"><vh>The Great Graph Aha</vh></v>
<v t="ekr.20070806090226.15"><vh>Added support for @auto files</vh>
<v t="ekr.20070806095535.1"><vh>What @auto does</vh></v>
<v t="ekr.20070809141529"><vh>Perfect import checks</vh></v>
<v t="ekr.20070806101412"><vh>Commands related to @auto</vh></v>
<v t="ekr.20070806100055"><vh>Extending the code: adding new parsers</vh></v>
</v>
<v t="ekr.20070920092716"><vh>New commands for resolving cvs conflicts</vh></v>
<v t="ekr.20070809145744.5"><vh>New kinds of settings trees</vh>
<v t="ekr.20071001122703"><vh>@buttons trees</vh></v>
<v t="ekr.20071004110818"><vh>@menus trees</vh></v>
</v>
<v t="ekr.20070809145744.6"><vh>New plugins</vh></v>
<v t="ekr.20071005100213"><vh>Leo's core is now compatible with jython</vh></v>
<v t="ekr.20071026180804"><vh>Improved prototype for icons in headlines</vh></v>
<v t="ekr.20070809145744.7"><vh>Minor improvements</vh></v>
<v t="ekr.20070809145744.4"><vh>Summary of new commands</vh></v>
</v>
<v t="ekr.20070513113903"><vh>Leo 4.4.3</vh></v>
<v t="ekr.20060928172457"><vh>Leo 4.4.2</vh>
<v t="ekr.20060929043325"><vh>A major code reorg</vh></v>
<v t="ekr.20061009111417.18"><vh>New commands</vh></v>
<v t="ekr.20060928172457.4"><vh>New features</vh></v>
<v t="ekr.20060928172457.5"><vh>New and improved plugins</vh></v>
<v t="ekr.20061009111417.11"><vh>Settings</vh></v>
<v t="ekr.20060929043325.1"><vh>ZODB scripting</vh></v>
</v>
<v t="ekr.20060620094033.1"><vh>Leo 4.4.1</vh>
<v t="ekr.20060620130636"><vh>New commands</vh></v>
<v t="ekr.20060620095949.15"><vh>New features</vh></v>
<v t="ekr.20060620130943"><vh>New and improved plugins</vh></v>
<v t="ekr.20060620095949.25"><vh>New settings</vh></v>
<v t="ekr.20070622212732"><vh>Improved settings</vh></v>
<v t="ekr.20060620095655"><vh>Minor improvements</vh></v>
</v>
<v t="ekr.20060620094033.2"><vh>Leo 4.4</vh>
<v t="ekr.20070622212132"><vh>New commands</vh></v>
<v t="ekr.20060620133820.16"><vh>New features</vh></v>
<v t="ekr.20060620140130"><vh>New and improved plugins</vh></v>
<v t="ekr.20060620140228"><vh>New and improved settings</vh></v>
</v>
</v>
</v>
</v>
<v t="ekr.20101026082911.5536"><vh>Release notes</vh>
<v t="ekr.20100805165051.7177" descendentVnodeUnknownAttributes="7d710028550a302e302e31322e302e3771017d710255097374725f6174696d657103550c313337363431323238302e30710473550b302e302e332e302e322e3371057d71066803550c313337363431323838382e307107735510302e302e31322e312e302e372e302e3171087d710958090000007374725f6174696d65710a550c313337363431323238382e30710b73550e302e302e31322e302e372e302e31710c7d710d6803550c313337363431323238382e30710e735509302e302e312e302e30710f7d71106803550c313337363431323837322e30711173550b302e302e332e312e312e3371127d71136803550c313337363431323838392e30711473550c302e302e31322e312e302e3771157d711658090000007374725f6174696d657117550c313337363431323238302e30711873752e"><vh>@file release_notes.txt</vh></v>
</v>
</v>
<v t="ekr.20130926053913.15854"><vh>Leo 4.11 b1 Release notes</vh>
<v t="ekr.20130926053913.16258"><vh>a1 and a2 releases</vh>
<v t="ekr.20130926053913.16131"><vh>Bugs</vh>
<v t="ekr.20130926053913.16132"><vh>Bugs: minor</vh>
<v t="ekr.20130926053913.16133"><vh>Clear previous focus-border after alt-tab</vh></v>
<v t="ekr.20130926053913.16134"><vh>Don't horizontally scroll body pane if word wrapping</vh></v>
<v t="ekr.20130926053913.16135"><vh>Execute selected script now works again</vh></v>
<v t="ekr.20130926053913.16136"><vh>Fixed activateMenu</vh></v>
<v t="ekr.20130926053913.16137"><vh>Fixed bug 1021849: typo in path for icon of desktop shortcut</vh></v>
<v t="ekr.20130926053913.16138"><vh>Fixed bug 1194209: Inconsistent Window Titles</vh></v>
<v t="ekr.20130926053913.16139"><vh>Fixed bug 879338: Global tables in leoApp.py should describe all languages known to the colorizer</vh></v>
<v t="ekr.20130926053913.16140"><vh>Fixed bug 971171: re .leoRecentFiles</vh></v>
<v t="ekr.20130926053913.16141"><vh>Fixed bug 981849: incorrect body content shown</vh></v>
<v t="ekr.20130926053913.16142"><vh>Fixed bug 998090: save file as doesn't remove entry from open file list</vh></v>
<v t="ekr.20130926053913.16143"><vh>Fixed bug: selected node was not always restored properly</vh></v>
<v t="ekr.20130926053913.16144"><vh>Fixed bugs 971166 &amp; 979142 re copy/paste</vh></v>
<v t="ekr.20130926053913.16145"><vh>Fixed crash after viewrendered-hide</vh></v>
<v t="ekr.20130926053913.16146"><vh>Fixed crasher in active_path.py</vh></v>
<v t="ekr.20130926053913.16147"><vh>Fixed crasher in flattenOutline</vh></v>
<v t="ekr.20130926053913.16148"><vh>Fixed crasher in leoBridge</vh></v>
<v t="ekr.20130926053913.16149"><vh>fixed crasher involving g.importFromPath</vh></v>
<v t="ekr.20130926053913.16150"><vh>Fixed failing unit tests in distro</vh></v>
<v t="ekr.20130926053913.16151"><vh>fixed get_fn in viewrendered plugin</vh></v>
<v t="ekr.20130926053913.16152"><vh>Fixed import problems discovered by importing 2to3</vh></v>
<v t="ekr.20130926053913.16153"><vh>Fixed missing search text bug</vh></v>
<v t="ekr.20130926053913.16154"><vh>fixed problem with file:/// url's on Windows</vh></v>
<v t="ekr.20130926053913.16155"><vh>Fixed problems with scrolling when saving</vh></v>
<v t="ekr.20130926053913.16156"><vh>Fixed scrolling problem with scrollwheel</vh></v>
<v t="ekr.20130926053913.16157"><vh>Fixed several problems with c-to-py command</vh></v>
<v t="ekr.20130926053913.16158"><vh>Fixed special cases of auto-completion of commands</vh></v>
<v t="ekr.20130926053913.16159"><vh>Fixed undo problems in headlines</vh></v>
<v t="ekr.20130926053913.16160"><vh>Increased the width of find/change text</vh></v>
<v t="ekr.20130926053913.16161"><vh>Made sure tab completion only happens on explicit tab</vh></v>
<v t="ekr.20130926053913.16162"><vh>Made sure the new load code loads plugins at most once</vh></v>
<v t="ekr.20130926053913.16163"><vh>Minimize scrolling during paste-text</vh></v>
<v t="ekr.20130926053913.16164"><vh>Restore focus on window activation</vh></v>
<v t="ekr.20130926053913.16165"><vh>Restored special case for run-selected-unit-tests</vh></v>
<v t="ekr.20130926053913.16166"><vh>Rewrote and tested at.deleteUnvisitedNodes</vh></v>
<v t="ekr.20130926053913.16167"><vh>Rewrote and tested p.deletePositionsInList</vh></v>
<v t="ekr.20130926053913.16168"><vh>Running unit tests no longer change the selected tab</vh></v>
<v t="ekr.20130926053913.16169"><vh>The @auto read code now catches failed asserts in import code.</vh></v>
<v t="ekr.20130926053913.16170"><vh>Wont Fix bug 903640: Import of Python files containing the strings "&lt;&lt;" and "&gt;&gt;" does not work</vh></v>
</v>
<v t="ekr.20130926053913.16171"><vh>Bugs: serious</vh>
<v t="ekr.20130926053913.16172"><vh>Added ubuntu only menu kludge</vh></v>
<v t="ekr.20130926053913.16173"><vh>Created a dummy tab when only one tab would otherwise be opened</vh></v>
<v t="ekr.20130926053913.16174"><vh>Fixed another scrolling bug</vh></v>
<v t="ekr.20130926053913.16175"><vh>Fixed bug 1184855: data loss with command line 'leo somefile.ext'</vh></v>
<v t="ekr.20130926053913.16176"><vh>Fixed scrolling problem with multiple editors</vh></v>
</v>
</v>
<v t="ekr.20130926053913.16177"><vh>Code</vh>
<v t="ekr.20130926053913.16178"><vh>Added c.deletePositionsInList</vh></v>
<v t="ekr.20130926053913.16179"><vh>Added c2 keyword arg to c.bringToFront</vh></v>
<v t="ekr.20130926053913.16180"><vh>Added default button to dialog methods</vh></v>
<v t="ekr.20130926053913.16181"><vh>Added external/leosax.py to leoPyRef.leo</vh></v>
<v t="ekr.20130926053913.16182"><vh>Added g.getActualColor</vh></v>
<v t="ekr.20130926053913.16183"><vh>Added g.restore_selection_range</vh></v>
<v t="ekr.20130926053913.16184"><vh>Added leo/extensions/sh.py</vh></v>
<v t="ekr.20130926053913.16185"><vh>Added local pylint suppressions</vh></v>
<v t="ekr.20130926053913.16186"><vh>baseNativeTree.onHeadChanged now truncates headlines</vh></v>
<v t="ekr.20130926053913.16187"><vh>Cached syntax coloring</vh></v>
<v t="ekr.20130926053913.16188"><vh>g.pdb now does qtGui stuff</vh></v>
<v t="ekr.20130926053913.16189"><vh>Improved g.trace</vh></v>
<v t="ekr.20130926053913.16190"><vh>Integrated free_layout into Leo's core</vh></v>
<v t="ekr.20130926053913.16191"><vh>Removed unused files from leo/modes directory</vh></v>
<v t="ekr.20130926053913.16192"><vh>SherlockTracer now shows returned values</vh></v>
</v>
<v t="ekr.20130926053913.16193"><vh>Contrib branch</vh>
<v t="ekr.20130926053913.16194"><vh>Dumping leo docs to excel</vh></v>
<v t="ekr.20130926053913.16195"><vh>Full text searches</vh></v>
<v t="ekr.20130926053913.16196"><vh>LeoReader: Leo as web app</vh></v>
<v t="ekr.20130926053913.16197"><vh>QML notebook</vh></v>
<v t="ekr.20130926053913.16198"><vh>Templates with macro expansions</vh></v>
</v>
<v t="ekr.20130926053913.16199"><vh>Commands: new and improved</vh>
<v t="ekr.20130926053913.16200"><vh>Added docstrings for all commands</vh></v>
<v t="ekr.20130926053913.16201"><vh>All viewrended commands now start with vr</vh></v>
<v t="ekr.20130926053913.16202"><vh>Allow periods before section names in headlines</vh></v>
<v t="ekr.20130926053913.16203"><vh>Alt-Home &amp; Alt-End collapse all possible nodes</vh></v>
<v t="ekr.20130926053913.16204"><vh>Ensure selected @test node is run</vh></v>
<v t="ekr.20130926053913.16205"><vh>Fixed dabbrev commands</vh></v>
<v t="ekr.20130926053913.16206"><vh>go-anywhere command (quicksearch plugin)</vh></v>
<v t="ekr.20130926053913.16207"><vh>Help commands now use &lt;pre&gt; formatting if docutils is not available</vh></v>
<v t="ekr.20130926053913.16208"><vh>help-for-command executes apropos commands</vh></v>
<v t="ekr.20130926053913.16209"><vh>help-for-python now uses vr window</vh></v>
<v t="ekr.20130926053913.16210"><vh>help-for-regular-expressions command</vh></v>
<v t="ekr.20130926053913.16211"><vh>Improved incremental search commands</vh></v>
<v t="ekr.20130926053913.16212"><vh>leoscreen-jump-to-error command</vh></v>
<v t="ekr.20130926053913.16213"><vh>normalize-whitespace</vh></v>
<v t="ekr.20130926053913.16214"><vh>parse-body command</vh></v>
<v t="ekr.20130926053913.16215"><vh>print-buttons command</vh></v>
<v t="ekr.20130926053913.16216"><vh>Refresh from disk menu command now refreshes all selected nodes</vh></v>
<v t="ekr.20130926053913.16217"><vh>Show all commands after &lt;alt-x&gt;&lt;tab&gt;</vh></v>
<v t="ekr.20130926053913.16218"><vh>vr-expand/contract commands</vh></v>
<v t="ekr.20130926053913.16219"><vh>zoom-in/out commands</vh></v>
</v>
<v t="ekr.20130926053913.16220"><vh>Gui improvements</vh>
<v t="ekr.20130926053913.16221"><vh>@wrap now suppresses horizontal scrolling</vh></v>
<v t="ekr.20130926053913.16222"><vh>All @button nodes now show call tips</vh></v>
<v t="ekr.20130926053913.16223"><vh>Change focus-border color depending on input state</vh></v>
<v t="ekr.20130926053913.16224"><vh>Dark colorizing theme</vh></v>
<v t="ekr.20130926053913.16225"><vh>Sublime Text 2 (A dark colorizing theme)</vh></v>
<v t="ekr.20130926053913.16226"><vh>Use ctrl-click to open url's</vh></v>
</v>
<v t="ekr.20130926053913.16227"><vh>New features</vh>
<v t="ekr.20130926053913.16228"><vh>About @testsetup</vh></v>
<v t="ekr.20130926053913.16229"><vh>Added support for @testclass</vh></v>
<v t="ekr.20130926053913.16230"><vh>Added support for sessions</vh></v>
<v t="ekr.20130926053913.16231"><vh>Allow cloned siblings</vh></v>
<v t="ekr.20130926053913.16232"><vh>Allow clones anywhere in @file nodes</vh></v>
<v t="ekr.20130926053913.16233"><vh>Major additions to abbreviations</vh></v>
<v t="ekr.20130926053913.16234"><vh>Major improvements made to abbreviations</vh></v>
<v t="ekr.20130926053913.16235"><vh>Warn if same .leo file open in another Leo instance</vh></v>
</v>
<v t="ekr.20130926053913.16236"><vh>New languages and importers</vh>
<v t="ekr.20130926053913.16237"><vh>Added importer .otl files</vh></v>
<v t="ekr.20130926053913.16238"><vh>Added importer for .ipynb importer</vh></v>
<v t="ekr.20130926053913.16239"><vh>Added importer for TypeScript files</vh></v>
<v t="ekr.20130926053913.16240"><vh>Added importer for vimoutliner imports and @auto-otl</vh></v>
<v t="ekr.20130926053913.16241"><vh>Added support for clojure syntax coloring</vh></v>
</v>
<v t="ekr.20130926053913.16242"><vh>Plugins</vh>
<v t="ekr.20130926053913.16243"><vh>New plugins</vh>
<v t="ekr.20130926053913.16244"><vh>leomylyn.py</vh></v>
<v t="ekr.20130926053913.16245"><vh>printing.py</vh></v>
<v t="ekr.20130926053913.16246"><vh>screen_capture.py</vh></v>
<v t="ekr.20130926053913.16247"><vh>screencast.py</vh></v>
<v t="ekr.20130926053913.16248"><vh>timestamp.py</vh></v>
</v>
<v t="ekr.20130926053913.16249"><vh>Improved plugins</vh>
<v t="ekr.20130926053913.16250"><vh>bookmarks.py</vh></v>
<v t="ekr.20130926053913.16251"><vh>ipython.py</vh></v>
<v t="ekr.20130926053913.16252"><vh>valuespace.py</vh></v>
<v t="ekr.20130926053913.16253"><vh>viewrendered.py</vh></v>
</v>
</v>
<v t="ekr.20130926053913.16254"><vh>Scripts</vh>
<v t="ekr.20130926053913.16255"><vh>Full tree preview</vh></v>
</v>
<v t="ekr.20130926053913.16256"><vh>Settings &amp; options</vh></v>
<v t="ekr.20130926053913.16257"><vh>Web site improvements</vh></v>
</v>
<v t="ekr.20130926053913.16259"><vh>b1 release</vh>
<v t="ekr.20130926053913.16353"><vh>** Improved abbreviations</vh></v>
<v t="ekr.20130926053913.16363"><vh>Code improvements</vh>
<v t="ekr.20130926053913.16348"><vh>simplified creation of event filters in qtGui.py</vh></v>
<v t="ekr.20130926053913.16358"><vh>added strip_data argument to config.getData</vh></v>
<v t="ekr.20130926053913.16347"><vh>Removed unused binding &amp; gui code</vh></v>
</v>
<v t="ekr.20130926053913.16362"><vh>Fixed bugs</vh>
<v t="ekr.20130926053913.16361"><vh>Can't fix (yet) bug 1090950: refresh from disk - cut node ressurection</vh></v>
<v t="ekr.20130926053913.16346"><vh>cycle-all-focus now works with the Spell Tab enabled</vh></v>
<v t="ekr.20130926053913.16334"><vh>Fixed annoying reformat-paragraph bug</vh></v>
<v t="ekr.20130926053913.16350"><vh>Fixed autocompletion crasher</vh></v>
<v t="ekr.20130926053913.16336"><vh>Fixed bug  869385: Chapters make the nav_qt.py plugin useless</vh></v>
<v t="ekr.20130926053913.16359"><vh>Fixed bug  879338: Global tables in leoApp.py should describe all languages known</vh>
<v t="ekr.20130926053913.16360"><vh>Extra keys</vh></v>
</v>
<v t="ekr.20130926053913.16319"><vh>Fixed bug 1019794: p.copyTreeFromSelfTo, chould deepcopy p.v.u</vh></v>
<v t="ekr.20130926053913.16330"><vh>Fixed bug 1028986: create relative urls when dragging binary files to Leo</vh></v>
<v t="ekr.20130926053913.16329"><vh>Fixed bug 1046195: character encoding changes when dragging outline between leo files</vh></v>
<v t="ekr.20130926053913.16338"><vh>Fixed bug 1046728: quickstart.leo 'auto nodes' example is not working</vh></v>
<v t="ekr.20130926053913.16331"><vh>Fixed bug 1074812: certain .leo file causes "IndexError: list index out of range"</vh></v>
<v t="ekr.20130926053913.16343"><vh>Fixed bug 1099035: Leo yank and kill behaviour not quite the same as emacs</vh></v>
<v t="ekr.20130926053913.16332"><vh>Fixed bug 1132821: Leo replaces a soft link with a real file</vh></v>
<v t="ekr.20130926053913.16357"><vh>Fixed bug 1160660: File-Compare-Leo-Files creates "other file" clones</vh></v>
<v t="ekr.20130926053913.16315"><vh>Fixed bug 1162307: Undoing a headline change does not change focus to the headline</vh></v>
<v t="ekr.20130926053913.16337"><vh>Fixed bug 1175013: leo/plugins/spellpyx.txt is both source controlled and customized</vh></v>
<v t="ekr.20130926053913.16316"><vh>Fixed bug 1182695: the tricky string that leo can not handle</vh></v>
<v t="ekr.20130926053913.16345"><vh>Fixed bug 1182864: goto-global-line cmd bug</vh></v>
<v t="ekr.20130926053913.16328"><vh>Fixed bug 1185409: importing binary files puts binary content in body editor</vh></v>
<v t="ekr.20130926053913.16324"><vh>Fixed bug 1193819: Script buttons cant "go to script" after outline changes</vh></v>
<v t="ekr.20130926053913.16318"><vh>Fixed bug 1193870 Delete Menu doesn't work in Qt</vh></v>
<v t="ekr.20130926053913.16344"><vh>Fixed bug 1208659 leo parsed the wrong line number of html file</vh></v>
<v t="ekr.20130926053913.16312"><vh>Fixed bug 1208942: Leo holding directory/file handles after file close?</vh></v>
<v t="ekr.20130926053913.16321"><vh>Fixed bug 1223383: Garbled text with BOM-marked files</vh>
<v t="ekr.20130926053913.16322"><vh> report</vh></v>
<v t="ekr.20130926053913.16323"><vh> what I did</vh></v>
</v>
<v t="ekr.20130926053913.16335"><vh>Fixed bug 1224586: Reorganizing @chapter nodes breaks chapter menu</vh></v>
<v t="ekr.20130926053913.16341"><vh>Fixed bug 1226358 File URL's are broken on MacOS</vh></v>
<v t="ekr.20130926053913.16355"><vh>Fixed bug 1226816: Command line "leo xxx.leo" creates file xxx.leo.leo</vh></v>
<v t="ekr.20130926053913.16354"><vh>Fixed bug 1229896: nav_qt traceback when node deleted</vh></v>
<v t="ekr.20130926053913.16340"><vh>Fixed bug in at.putCodeLine</vh></v>
<v t="ekr.20130926053913.16320"><vh>Fixed bugs 1183855 &amp; 1212332 involving missing select hooks</vh></v>
<v t="ekr.20130926053913.16339"><vh>Fixed docs re bug 1159302: Correcting and improving the "Open with" documentation</vh></v>
<v t="ekr.20130926053913.16356"><vh>Investigated bug  971171: re .leo/.leoRecentFiles.txt</vh></v>
<v t="ekr.20130926053913.16333"><vh>Investigated bug 1178249: url: file relative path does not work same way</vh></v>
<v t="ekr.20130926053913.16317"><vh>Investigated bug 1182694: not display unique in leo and other editor</vh></v>
<v t="ekr.20130926053913.16327"><vh>Investigated bug 1190778: ScriptFile.py not generating correctly (ignores text after @others)</vh></v>
<v t="ekr.20130926053913.16342"><vh>Investigated spell crash (already fixed)</vh></v>
</v>
<v t="ekr.20130926053913.16364"><vh>New commands &amp; features</vh>
<v t="ekr.20130926053913.16349"><vh>created insert-node-before command &amp; p.insertBefore</vh></v>
<v t="ekr.20130926053913.16314"><vh>Added yes-to-all button when prompting for dangerous writes</vh></v>
<v t="ekr.20130926053913.16325"><vh>Added help text to the find panel</vh></v>
</v>
<v t="ekr.20130926053913.16366"><vh>New key binding</vh>
<v t="ekr.20130926053913.16326"><vh>Bound Alt-Ctrl-M for macro-call-last</vh></v>
</v>
<v t="ekr.20130926053913.16365"><vh>New scripts</vh>
<v t="ekr.20130926053913.16313"><vh>Added c.recursiveImport and ic.recursiveImportController</vh></v>
</v>
</v>
</v>
<v t="ekr.20131007143750.16111"><vh>To do</vh>
<v t="ekr.20131010160850.17454"><vh>* Insert index entries into the tutorial</vh></v>
<v t="ekr.20131019184243.16701"><vh>* Add more introductory words</vh>
<v t="ekr.20131019184243.16660"><vh>Python tutorial</vh></v>
<v t="ekr.20131019184243.16661"><vh>Emacs tutorial</vh></v>
</v>
<v t="ekr.20101025080245.5791"></v>
<v t="ekr.20130928065624.16019"><vh>Fix bug: 1168689 outdated documentation about ipython</vh>
<v t="ekr.20131019061259.16677"><vh>Notes</vh>
<v t="ekr.20130928065624.16021"><vh>code</vh>
<v t="ekr.20130928065624.16022"><vh>runMainLoop &amp; runWithIpythonKernel (qtGui)</vh></v>
</v>
<v t="ekr.20130928065624.16023"><vh>post 1</vh></v>
<v t="ekr.20130928065624.16024"><vh>post 2</vh></v>
<v t="ekr.20130928065624.16025"><vh>post 3</vh></v>
<v t="ekr.20130928065624.16026"><vh>EKR post re new code</vh></v>
<v t="ekr.20130928065624.16027"><vh>** EKR post 2: how to use the new code</vh></v>
<v t="ekr.20130928065624.16028"><vh>Windows installation</vh></v>
</v>
<v t="ekr.20131001100236.15925"><vh>Revise ipython bridge chapter</vh>
<v t="ekr.20131001100236.15926"><vh>ipython-new &amp; dependencies</vh></v>
<v t="ekr.20131001100236.15927"><vh>valuespace &amp; --ipython</vh></v>
<v t="ekr.20131001100236.15928"><vh>highlights (for release noes)</vh></v>
</v>
</v>
<v t="ekr.20131001100335.15942"><vh>Leo &amp; other programs</vh>
<v t="ekr.20131001100335.15943"><vh>Leo vs Emacs</vh></v>
<v t="ekr.20131001100335.15944"><vh>Leo vs Vim</vh></v>
<v t="ekr.20131001100335.15945"><vh>Leo vs IPython</vh></v>
</v>
<v t="ekr.20131008041326.16109"><vh>Add a Expansion section to the Reference chapter?</vh></v>
</v>
<v t="ekr.20131019061259.16683"><vh>Changed</vh>
<v t="ekr.20131007143750.16070"></v>
<v t="ekr.20070628083442.1"></v>
<v t="ekr.20131008041326.16203"></v>
<v t="ekr.20131008041326.16245"></v>
<v t="ekr.20040403171740"></v>
<v t="ekr.20131019061259.16684"><vh>From tutorial</vh>
<v t="ekr.20131002055813.15973"></v>
<v t="ekr.20131004064408.16020"></v>
<v t="ekr.20131003040744.18221"></v>
</v>
</v>
</vnodes>
<tnodes>
<t tx="EKR.20040524104904.100"></t>
<t tx="EKR.20040524104904.101">The ``new`` (Ctrl-N) command creates a new Leo main window. The
``open-outline`` (Ctrl-O) command opens an existing Leo file and shows it
in a main window. The ``close-window`` (Ctrl-F4) command closes the
selected Leo window, giving you an opportunity to save your work if you
haven't yet done so.

The ``save-file`` (Ctrl-S), ``save-file-as`` and ``save-file-to`` commands
save the Leo window to a file. The ``save-files-as`` command changes the
name of the outline being edited; the ``save-file-to`` command does not.
The ``save-file-as-zipped`` command is the same as the ``save-file-as``
command except that the resulting .leo file is compressed with Python's
zipfile module. Similarly, the ``save-file-as-unzipped`` command is the
same as the ``save-as`` command except that the resulting .leo file is not
compressed. The ``save-file``, ``save-file-as`` and ``save-file-to``
commands compress the file if it was originally compressed. **Note**: Leo
writes files with .leo extension, regardless of whether the file is zipped
or not. Zipped .leo files contain a single archive, whose name is the same
as the .leo file itself. Outside of Leo you can change the extension to
.leo.zip and use stuffit or other program to expand the .leo file contained
within. The ``revert`` command reloads a file, discarding any changes made
to the file since it was last saved.

The Recent Files menu shows a list of recently opened files. Choosing an
item in this submenu opens the selected file or brings it to the front. The
``clear-recent-files`` command deletes all entries in the Recent Files
submenu except the most recent file. The files themselves are not affected,
just the menu entries.

The following commands are located in the File:Read/Write menu...

The ``read-outline-only`` command reads an outline using only the .leo
file, not any files derived from @file nodes. This command is useful for
reverting a project to a previously saved state. The ``read-at-file-nodes``
command updates all @file nodes in an outline. This ensures that the state
of an outline matches all files derived from \@file nodes. The
``write-outline-only`` command saves an outline without writing any \@file
trees. Useful for inserting an @file node into an outline without modifying
a external file with the same name. The ``write-at-file-nodes`` command
forces an update of all @file trees. The ``write-dirty-at-file-nodes``
command writes all @file trees that have been changed.
</t>
<t tx="EKR.20040524104904.102">The ``open-with`` command allows you to communicate with external editor.
When you select this command Leo creates a temporary file and invokes an
external program. Leo periodically checks whether this temporary file has
changed; Leo changes the corresponding node in the outline if so. You must
create the entries using an \@openwith in myLeoSettings.leo. See the
documentation in leoSettings.leo.
</t>
<t tx="EKR.20040524104904.108">The ``import-file`` command imports a file in various ways depending on the
contents of the file. For plain files, the command creates an \@file node.
If the file looks like an external file written by Leo, the import command
will recreate the outline structure based on the sentinels in the file.
This command can also read files written in MORE outline format.
</t>
<t tx="EKR.20040524104904.109">The ``outline-to-cweb`` command creates a `CWEB`_ file from the selected
outline. The ``outline-to-noweb`` command creates a `noweb`_ file from the
selected outline. The ``flatten-outline`` command creates a text file in
MORE format from the selected outline. The ``remove-sentinels`` command
removes all sentinel lines from a file derived from an @file node. The
``weave`` command formats the selected text and writes it to a file.
</t>
<t tx="EKR.20040524104904.110">The ``exit-leo`` (Ctrl-Q or Alt-F4) command causes Leo to exit. You may
also exit Leo by closing the main window. You will be prompted to save any
file that has been altered but not saved.
</t>
<t tx="EKR.20040524104904.111"></t>
<t tx="EKR.20040524104904.112">Leo supports unlimited undo and redo with the ``undo`` (Ctrl-Z) and
``redo`` (Ctrl-Shift-Z) commands. Think of actions that may be undone or
redone as a string of beads. A "bead pointer" points to the present bead.
Performing an operation creates a new bead after the present bead and
removes all following beads. Undoing an operation moves the bead pointer
backwards; redoing an operation moves the bead pointer forwards. The ``undo``
command is disabled when the bead pointer moves in front of the first bead;
the ``redo`` command is disabled when the bead pointer points to the last bead.

The @string undo_granularity setting controls the granularity of undo.
There are four possible values:

node
    Starts a new undo unit when typing moves to a new node.

line (default)
    Starts a new undo unit when typing moves to new line.

word
    Starts a new undo unit when typing starts a new word.

char (not recommended)
    Starts a new undo unit for each character typed.
    This wastes lots of computer memory.
</t>
<t tx="EKR.20040524104904.113">Leo supports the standard editing commands: ``cut-text`` (Ctrl-X),
``copy-text`` (Ctrl-C) and ``paste-text`` (Ctrl-V), and ``select-all``
(Ctrl-A) commands. These commands work with either headline or body text.
</t>
<t tx="EKR.20040524104904.114">The ``indent-region`` (Ctrl-Tab) and ``unindent-region`` (Tab) commands
shift selected lines in the body text left or right one tab position. These
commands shift the entire line if any characters in that line are selected.
If no text is selected, the Tab character insert a hard or soft tab
depending on the value of the \@tabwidth directive in effect.
</t>
<t tx="EKR.20040524104904.115">The ``extract`` (Ctrl-Shift-D) command creates a new node whose headline is
the first line of selected body text and whose body is all other lines of
selected text. Previously selected text is deleted from the original body
text. The ``extract-names`` (Ctrl-Shift-Command) command creates one or
more child nodes, one for each section name in the selected body text. The
headline of each created node is the section name.
</t>
<t tx="EKR.20040524104904.116">The ``convert-tabs`` command converts leading tabs to blanks in a single
node. The ``convert-blanks`` command converts blanks to tabs in a single
node. The ``convert-all-tabs`` command converts leading tabs to blanks
throughout the selected tree. The ``convert-all-blanks`` command converts
leading blanks to tabs throughout the selected tree. All these commands
convert between tabs and blanks using the \@tabwidth setting presently in
effect.
</t>
<t tx="EKR.20040524104904.117">The ``execute-script`` (Ctrl-B) command executes body text as a Python
script. Leo execute the selected text, or the entire body text if no text
is selected. The Execute Script command pre-defines the values c, g and p
as follows:

- c is the commander of the outline containing the script.
- g is the leoGlobals modules.
- p is c.p, that is, c.currentPosition().

**Important**: Body text may contain Leo directives and section references.
You can use all of Leo's features to organize scripts that you execute
interactively. Section definitions must appear in the node containing the
script or in descendant nodes.

Leo preprocesses all scripts by simulating the writing of a external file
to a string. The ``execute-script`` command sets app.scriptDict["script1"]
to the value of the script before preprocessing, and sets
app.scriptDict["script2"] to the value of the script after preprocessing.
Scripts may examine and change app.scriptDict as they please.
</t>
<t tx="EKR.20040524104904.118"></t>
<t tx="EKR.20040524104904.134">The ``goto-global-line`` (Alt-G) command selects the locations in your
outlines corresponding to a line in a external file.
</t>
<t tx="EKR.20040524104904.136">The ``insert-body-time`` and ``insert-headline-time`` commands insert
formatted time and date into body or headline text. You must be editing a
headline to be able to insert the time/date into the headline. The
body_time_format_string and headline_time_format_string settings specify
the format of the inserted text. These settings are the format string
passed to time.strftime. For a complete list of the format options see
http://www.python.org/doc/current/lib/module-time.html The "%m/%d/%Y
%H:%M:%S" format is used by default, resulting in a time/date format like::

    1/30/2003 8:31:55
</t>
<t tx="EKR.20040524104904.137">The ``reformat-paragraph`` (Ctrl-Shift-P) command rearranges the words in a
text paragraph to fill each line as full as possible, up to the \@pagewidth
setting. A paragraph is delimited by blank lines, Leo directives, and (of
course) start and end of text in a node. The width of the line used by the
reformatting operation is governed by @pagewidth and the indentation that
would be applied to the node when Leo writes the file.

The command operates on the paragraph containing the insert cursor. If the
insert cursor is on a blank line or directive, nothing happens. If the
cursor is on a line containing text, then the paragraph containing that
text line is reformatted and the insert cursor is moved to the next
paragraph.

**Note**: Hanging indentation is preserved. This is most useful for
bulleted or numbered lists, such as::

  1. This is the first paragraph,
     and it has a hanging indentation.

  2. This is the second paragraph,
     and it too has a hanging indentation.
</t>
<t tx="EKR.20040524104904.139">The ``match-brackets`` command is enabled if the cursor is next to one of the
following characters in the body pane:

    ( ) [ ] { } &lt; &gt;

This command looks for the matching character, searching backwards through
the body text if the cursor is next to ``)`` ``]`` ``}`` or ``&gt;`` and
searching forward through the text otherwise. If the cursor is between two
brackets the search is made for the bracket matching the leftmost bracket.
If a match is found, the entire range of characters delimited by the
brackets is highlighted and the cursor is placed just to the left of the
matching characters. Thus, executing this command twice highlights the
range of matched characters without changing the cursor.
</t>
<t tx="EKR.20040524104904.140">Leo stores options in **@settings trees**, outlines whose headline is
@settings. When opening a .leo file, Leo looks for @settings trees not only
in the outline being opened but also in various leoSettings.leo files.
This scheme allows for the following kinds of settings:

- Per-installation or per-machine settings.
- Per-user settings.
- Per-folder settings.
- Per-file settings.

There are four kinds of settings files:

1. **Default settings files**, named **leoSettings.leo**.
   Although they can be used in other ways, they typically contain default settings.

2. **Personal settings files**, named **myLeoSettings.leo**. They provide a way
   of ensuring that your customized settings are not altered when updating Leo
   from bzr or while installing a new version of Leo. The myLeoSettings.leo acts
   much like Python's site-customize.py file. myLeoSettings.leo will never be
   part of any Leo distribution, and it will never exist in Leo's cvs
   repository. This solution is *much* better than trying to update
   leoSettings.leo with scripts.

3. **Machine settings files**, named **LeoSettings.leo** (note the capital 'L'),
   and appearing in a unique directory.

4. **Command-line settings files**, specified using Leo's -c command-line
   option. Any .leo file may be used, provided it has an @settings tree. These
   files typically provide a common set of settings for files scattered in
   various places on the file system.

The following sections describe the kinds of nodes in @settings trees.
</t>
<t tx="EKR.20040524104904.143"></t>
<t tx="EKR.20040524104904.144">The ``check-outline`` command checks the outline for consistency. Leo
automatically check the syntax of Python external files when Leo
writes the external file.

The ``pretty-print-python-code`` and ``pretty-print-all-python-code``
pretty print body text. You can customize this code by overriding the
following methods of class prettyPrinter in leoCommands.py::

    putOperator:      puts whitespace around operators.
    putNormalToken:   puts whitespace around everything else.
</t>
<t tx="EKR.20040524104904.148">The ``hoist`` command redraws the screen so presently selected tree becomes
the only visible part of the outline. You may hoist an outline as many
times as you wish. The ``dehoist`` command undoes the effect of the
previous ``hoist`` command.
</t>
<t tx="EKR.20040524104904.151">-   The Equal Sized Panes command adjusts the sizes of the outline and body
    panes so that they are the same height.
-   The Cascade command cleans up the screen by cascading all Leo windows.
-   The Minimize All command minimizes all Leo windows.
-   The Toggle Active Pane command toggles keyboard focus between the outline and body panes.
-   The Toggle Split Direction command switches between vertical and horizontal
    orientations of the Leo window. In the vertical orientation, the body pane
    appears below the pane containing the outline and log panes. In the horizontal
    orientation, the body pane appears to the left the pane containing the outline
    and log panes. By default, the ratio of pane outline pane to the body pane is
    0.5 in the vertical orientation and 0.3 in the horizontal orientation. These two
    ratios may be changed using settings.
-   The Open Compare Window command opens a dialog that allows you to compare
    two files, one containing sentinels and one not.
</t>
<t tx="EKR.20040524104904.157">-   The About Leo command puts up a dialog box showing the version of Leo.
-   The Online Home Page command opens Leo's home page at http://leoeditor.com.
-   The Open Online Tutorial command opens Joe Orr's excellent ScreenBook tutorial at
    http://www.evisa.com/e/sbooks/leo/sbframetoc_ie.htm.
-   The Open Offline Tutorial command opens the file sbooks.chm if it exists.
    Otherwise, you will be asked whether you want to download it from Leo's SourceForge web site.
    If you say yes, the page http://sourceforge.net/project/showfiles.php?group_id=3458 will open.
    You may then download sbooks.sbm to the folder containing leo.py.
-   The Open LeoDocs.leo command opens LeoDocs.leo.
-   The Open LeoPlugins.leo command opens LeoPlugins.leo.
-   The Open LeoSettings.leo command opens LeoSettings.leo.

</t>
<t tx="EKR.20040524104904.211"></t>
<t tx="EKR.20040524104904.224" str_atime="1376412038.0">Naively using plugins can expose you and your .leo files to malicious attacks.
The fundamental principles are::

    Scripts and plugins must never blindly execute code from untrusted sources.

and::

    .leo files obtained from other people may potentially contain hostile code.

Stephen Schaefer summarizes the danger this way::

    I foresee a future in which the majority of leo projects come from
    marginally trusted sources...a world of leo documents sent hither and yon -
    resumes, project proposals, textbooks, magazines, contracts - and as a race
    of Pandora's, we cannot resist wanting to see "What's in the box?" And are
    we going to fire up a text editor to make a detailed examination of the
    ASCII XML? Never! We're going to double click on the cute leo file icon, and
    leo will fire up in all its raging glory. Just like Word (and its macros) or
    Excel (and its macros).

In other words::

    When we share "our" .leo files we can NOT assume that
    we know what is in our "own" documents!

Not all environments are untrustworthy. Code in a commercial cvs repository is
probably trustworthy: employees might be terminated for posting malicious code.
Still, the potential for abuse exists anywhere.

In Python it is very easy to write a script that will blindly execute other scripts::

    # Warning: extremely dangerous code

    # Execute the body text of all nodes that start with `@script`.
    def onLoadFile():
        for p in c.all_positions():
            h = p.h.lower()
            if g.match_word(h,0,"@script"):
                s = p.b
                if s and len(s) &gt; 0:
                    try: # SECURITY BREACH: s may be malicious!
                        exec(s + '\n')
                    except:
                        es_exception()

Executing this kind of code is typically an intolerable security risk.
**Important**: rexec provides *no protection whatever*.
Leo is a repository of source code, so any text operation is potentially malicious.
For example, consider the following script, which is valid in rexec mode::

    badNode = c.p
    for p in c.all_positions():
        &lt;&lt; change `rexec` to `exec` in p's body &gt;&gt;
    &lt;&lt; delete badNode &gt;&gt;
    &lt;&lt; clear the undo stack &gt;&gt;

This script will introduce a security hole the .leo file without doing anything
prohibited by rexec, and without leaving any traces of the perpetrating script
behind. The damage will become permanent *outside* this script when the user
saves the .leo file.
</t>
<t tx="EKR.20040524104904.240" str_atime="1376411987.0">If a plugin has a function at the outer (module) level called unitTest,
Leo's unit tests will call that function.

So it would be good if writers of plugins would create such a unitTest
function. To indicate a failure the unitTest can just throw an exception.
Leo's plugins test suite takes care of the rest.
</t>
<t tx="EKR.20040524104904.247">In May of 1999 I began work on the Borland version of Leo for Windows.  The
Borland Delphi classes were a pleasure to use and free of bugs.  I redesigned
Leo's file format for the Windows version of Leo; the Yellow Box file format is
a binary format that requires the Yellow Box runtime.  Fortunately, I choose to
use XML for Leo's file format.  I have Marc-Antoine Parent to thank for this
decision; he urged me to use XML and patiently explained how to use XML
properly.  However, there are two significant problems with the Borland version
of Leo.  First, it works only on Windows.  Second, it can never be Open
software, because it uses Borland's Delphi classes and a commercial syntax
coloring component. 

In October of 2001 I began work on the leo.py, an Open Software version of
leo.py, a version of Leo written in Python and Tk.  At last I have found the
proper platform for Leo.  leo.py naturally supports scripting in Python.  The
combination of Python and Tk is incredibly powerful, very easy to use, and truly
cross platform.  I rewrote Leo in Python in about two months!  For the first
time in my career I no longer am anxious while programming; it simply isn't
possible to create bad bugs in Python.

Tk was officially retired in June 2011.
</t>
<t tx="EKR.20040524104904.248">The following sections give a pseudo-chronological list of the major Aha's
involved in creating Leo2. These Aha's form the real design and theory of
operation of Leo. See the "Diary", "Notes" and "Letters to Speed Ream" sections
in LeoDocs.leo for a more accurate and less tidy history of Leo2.

I am writing these notes for several reasons. First, the initial design and
coding of Leo2, spanning a period of about 8 weeks, was some of the most
creative and rewarding work I have ever done. The result is elegant and simple.
I'm proud of it. Second, much of the design work is not reflected in the code,
because improved design often eliminated code entirely. The final code is so
elegant that it obscures the hard work that created it. Third, you must
understand this design in order to understand the implementation of @file trees
and their external files. Someday someone else may take charge of Leo. That
person should know what really makes Leo2 work.
</t>
<t tx="EKR.20040524104904.249">In the summer of 2001 I began work on a project that for a long time I had
considered impossible. I had long considered that "private" file formats such as
.leo files were the only way to represent an outline properly and safely. I'm
not sure exactly what changed my mind, but I finally was willing to consider
that information embedded in external files might be useful. This meant accepting
the possibility that sentinel lines might be corrupted. This was a crucial first
step. If we can trust the user not to corrupt sentinel lines than we can embed
almost any kind of information into a external file.

There were several motivations for this work. I wanted to eliminate the need for
explicit Tangle and Untangle commands. I thought of this as "Untangle on
Read/Tangle on Write." If tangling and untangling could be made automatic it
would save the user a lot of work. I also wanted to make external files the
primary sources files. .leo files might be made much smaller external files
contained the primary source information. This hope turned out to be false.

The result of this design work was something I originally called Leo2, though I
now usually prefer to talk about @file trees. Initially most design issues were
unresolved or unknown. I resolved to attempt a robust error-recovery scheme, not
knowing in advance what that might involve. I also wanted to solve what I
thought of as the "cross-file clone" problem: clones that point from a .leo
outline into a external file. With Leo1 cross-file clones do not exist;
everything is in the same .leo file. It was clear that Leo2 would have to change
some aspects of clones, but all details were fuzzy.
</t>
<t tx="EKR.20040524104904.250">The next step was also crucial. I started to use Leo1 as a prototype to design
what the new body pane would look like to the user. In retrospect, using Leo1 as
a prototype for Leo2 was just as inspired as using MORE as a prototype for Leo1.
Both prototypes marked the true beginning of their respective projects. The Leo2
prototype was a mockup in Python of the code for reading and writing derived
files. The file LeoDocs.leo contain these first prototype nodes.

Writing the prototype got me thinking about improving noweb. With my experience
with Leo1, I was able to create a new markup language that took advantage of
outline structure. I called the new language "simplified noweb", though that
terminology is obsolete. I created @file nodes to distinguish between the old
and new ways of creating external files. In Leo1, the @code directive is simply
an abbreviation for a section definition line. Simplified noweb used @c as an
abbreviation for @code. More importantly, simplified noweb used @c to separate
doc parts from code parts without necessarily specifying a section name. It
quickly became apparent that most nodes could be unnamed. All I needed was the
@others directive to specify the location for all such unnamed nodes.

From the start, simplified noweb was a joy to use. Indeed, the @others directive
could replace all section definition lines. Furthermore, I could make @doc
directive optional if the body pane started in "code mode". But this meant that
plain body text could become a program! This was an amazing discovery. These
Aha's got me excited about Leo2. This was important, as it motivated me to do a
lot of difficult design work.
</t>
<t tx="EKR.20040524104904.251">In spite of this excitement, I was uneasy. After much "daydreaming" I realized
that I was afraid that reading and writing external files would be interrupted by
a long series of alerts. I saw that designing the "user interaction" during
reading and writing would be very important. The next Aha was that I could
replace a long series of alerts with messages to the log window, followed by a
single "summary" alert. Much later I saw how to eliminate alerts entirely.

At this time I thought there would be two kinds of "errors" while reading
external files. Warnings would alert the user that something non-serious had
happened. True errors would alert the user that data might have been lost.
Indeed, if Leo2 saves orphan and ignored nodes in a .leo file under an @file
node, then read errors could endanger such nodes. Much later I saw that a robust
error recovery scheme demands that @file nodes not contain orphan and @ignored
nodes. (More on this subject later.) But if orphan and @ignored nodes are moved
out of @file trees, there are no read errors that can cause data loss! So the
distinction between warnings and errors finally went away.
</t>
<t tx="EKR.20040524104904.252">I next turned my attention to writing @file nodes. A huge Aha: I realized that
sentinel lines must contain both a leading and a trailing newline. The general
principle is this: the write code must contain absolutely no "conditional"
logic, because otherwise the read code could not figure out whether the
condition should be true or false. So external files contain blank lines between
sentinel lines. These "extra" newlines are very useful, because the read
(untangle) code can now easily determine exactly where every blank, tab and
newline of the external file came from. It would be hard to overstate how
important this simplifying principle was in practice.

Much later, with urging from a customer, I realized that the write code could
safely remove "extra" newlines between sentinels with a caching scheme in the
low level atFile::os() routine. This scheme does not alter the body of the write
code in any way: in effect, sentinels still contain leading and trailing
"logical" newlines. The read code had to be modified to handle "missing" leading
newlines, but this can always be done assuming that sentinels still contain
logical leading and trailing newlines!

At about this time I designed a clever way of having the write code tell the
read code which newlines were inserted in doc parts. (The whole point of doc
parts is to have the write code format long comments by splitting long lines.)
To quote from my diary:

"We can use the following convention to determine where putDocPart has inserted
line breaks: A line in a doc part is followed by an inserted newline if and only
if the newline is preceded by whitespace. This is a really elegant convention,
and is essentially invisible to the user. Tangle outputs words until the line
would become too long, and then it inserts a newline. To preserve all
whitespace, tangle always includes the whitespace that terminates a word on the
same line as the word itself. Therefore, split lines always end in whitespace.
To make this convention work, tangle only has to delete the trailing whitespace
of all lines that are followed by a 'real' newline."
</t>
<t tx="EKR.20040524104904.253">After the write code was working I turned my attention to the read (untangle)
code. Leo's Untangle command is the most complex and difficult code I have ever
written. Imagine my surprise when I realized that the Leo2 read code is
essentially trivial! Indeed, the Leo2 untangle code is like an assembler. The
read code scans lines of a external files looking for "opcodes", that is,
sentinel lines, and executes some simple code for each separate opcode. The
heart of this code is the scanText routine in atFile.cpp.

The read code was written and debugged in less than two days! It is the most
elegant code I have ever written. While perfecting the read code I realized that
sentinel lines should show the complete nesting structure found in the outline,
even if this information seems redundant. For example, I was tempted to use a
single sentinel to represent an @other directive, but finally abandoned this
plan in favor of the @+other and @-other sentinels.

This redundancy greatly simplified the read code and made the structure of
external files absolutely clear. Moreover, it turned out that we need, in
general, all the information created by the present sentinel lines. In short,
sentinels are as simple as they can be, and no simpler.

The atFile::createNthChild method is a very important: it ensures that nodes
will be correctly inserted into the outline. createNthChild must be bullet-proof
if the Read code is to be robust. Note that the write code outputs @node
sentinels, that is, section definitions, in the order in which sections are
referenced in the outline, not the order in which sections appear in the
outline. So createNthChild must insert the n'th node of parent p properly even
if p contains fewer than n-1 children! The write code ensures that section
references are properly nested: @node sentinels are enclosed in @node sentinels
for all their ancestors in the @file tree. createNthChild creates dummy siblings
as needed, then replaces the dummy siblings later when their actual definitions,
that is, @node sentinels, are encountered.

At this point the fundamental read/write code was complete. I found three minor
bugs in the code over the next week or so, but it was clear that the read/write
code formed a rock-solid base from which to continue design and implementation.
This was an entirely unexpected surprise.
</t>
<t tx="EKR.20040524104904.254">At this point I could read and write external files "by hand", using temporary
Read and Write commands. The next step was to integrate the reading and writing
of external files with the loading and saving of .leo files. From time to time I
made minor changes to the drivers for the read/write code to accommodate the
Load and Save code, but at no time did I significantly alter the read or write
code itself.

The user interaction of the Load and Save commands drove the design and
implementation of the load/store code. The most important questions were: "what
do we tell the user?", and "what does the user do with the information?" It
turns out that the user can't make any complex decision during error recovery
because the user doesn't have nearly enough information to make an informed
choice. In turn, this means that certain kinds of error recovery schemes are out
of the question...
</t>
<t tx="EKR.20040524104904.255">I now turned my attention to "attributes" of nodes. Most attributes, like user
marks, are non-essential. However, clone information is essential; we must never
lose clone links. At this time I had a preliminary design for cross-file clones
that involved a two part "pointer" consisting of a full path name and an
immutable clone index within the external file. Eventually such pointers
completely disappeared, but the immutable clone indices remain.

My first thought was that it would be good to store all attributes in @node
sentinels in the external file, but experience showed that would be irritating.
Indeed, one wants Leo2 to rewrite external files only if something essential has
changed. For example, one doesn't want to rewrite the external file just because
a different node as been selected.

At this point I had another Aha: we can use the .leo file to store all
non-essential attributes. For example, this means that the .leo file, not the
external files, will change if we select a new node. In effect, the .leo file
mirrors the external file. The only reason to store nodes in the .leo file under
an @file node is to carry these attributes, so Leo2 wrote dummy nodes that do
not reference body text. Much later I saw that dummy nodes were dangerous and
that .leo files should contain all information found in external files.
</t>
<t tx="EKR.20040524104904.256">The concept of mirroring created a huge breakthrough with cross-file clones:
Here is an excerpt of an email i sent to my brother Speed:

"I realized this morning that since a .leo file contains dummy vnodes for all
nodes in a external file, those dummy nodes can carry clone info! I changed one
line to make sure that the write code always writes clone info in dummy vnodes
and voila! Cross-file clones worked!"

All of Leo1's clone code could be used completely unchanged. Everything "just
works".
</t>
<t tx="EKR.20040524104904.257">At first I thought we could make sure that the .leo file always correctly
mirrors all external file, but disastrous experience showed that is a completely
false hope. Indeed, backup .leo files will almost never mirror external file
correctly. So it became urgent to find a completely fool-proof error recovery
scheme.

I had known for quite a while that error recovery should work "as if" the
mirroring nodes were deleted, then recreated afresh. Several failed attempts at
an error recovery scheme convinced me that error recovery would actually have to
delete all dummy nodes and then do a complete reread. This is what Leo2 does.

But erasing dummy nodes would destroy any orphan and ignored nodes--by
definition such nodes appear nowhere in the external file. Therefore, I had to
enforce the rule that @file nodes should contain no such nodes. Here is an email
I wrote to my brother, Speed Ream discussing what turned out to be the
penultimate error recovery scheme:

"The error recovery saga continues. After much pondering and some trial coding I
have changed my mind about orphans and @ignored nodes. They simply should never
appear as descendants of @file nodes. Fortunately, this simplifies all aspects
of Leo2. Leo2 will issue a warning (not an error) if an orphan or @ignored node
appears as the descendant of an @file node when a .leo file is being saved. If
any warnings occur while writing the external file, Leo2 will write the
"offending" @file tree to the .leo file instead of the external file. This has
several advantages:

1. The user gets warned about orphan nodes. These are useful warnings! Orphan
nodes arise from missing @others directives or missing section references.

2. The user doesn't have to change anything immediately in order to save an
outline. This is very important. Besides warnings about orphans, Leo2 will also
warn about undefined or unreferenced sections. User's shouldn't have to fix
these warnings to do a Save!

3. No errors or alerts will occur during Reading or Writing, so the user's
anxiety level goes way down. At worst, some informational message will be sent
to the log. The user will never have to make important decisions during Loads or
Saves. [At last the dubious distinction between errors and warnings disappears.]

4. Error recovery can be bullet-proof. Simple code will guarantee that after any
read operation the structure of an @file node will match the structure of the
external file. Also, sentinels in external files will now account for all children
of an @file node. There are no more "missing nodes" that must be filled in using
the .leo file. Finally, error recovery will never change the @file tree in any
way: no more "recovered nodes" nodes.

5. The present read code can be used almost unchanged. The only addition is the
posting of a warning if the structure of the .leo file does not match the
structure of the external file. We need a warning because non-essential attribute
of nodes (like user marks) may be altered."

This ends the original history of Leo2. In fact, it took quite a while before
Leo recovered properly from all errors. I finally saw that .leo files should
duplicate all information in external files. This allows a .leo file to be used a
single backup file and allows maximal error recovery in all situations. It took
several months to stamp out several subtle bugs involving clones that caused
spurious read errors. Such errors undermine confidence in Leo and can cause
disastrous reversions. See my diary entries for January 2002 in leo.py for
details.
</t>
<t tx="EKR.20040524104904.268">Leo's grand strategy for handling text is as follows:

1. Internally, Leo uses unicode objects for all text.

2. When reading files or user input, Leo converts all plain (encoded)
   strings to unicode.

3. When reading or writing files, Leo converts unicode strings to encoded
   strings.
   
To make this strategy work, Leo must know the encoding used for external
files. This is why Leo supports the @encoding directive and various
encoding-related settings.

The g.toUnicode and g.toEncodedString functions convert to and from
unicode. These methods catch all unicode-related exceptions.

The g.u function should be used *only* to convert from the Qt string type
(a wrapper for a unicode string) to unicode. Do not use g.u instead of
g.toUnicode.
</t>
<t tx="EKR.20040524104904.354">Leo uses unicode internally for all strings.

1.  Leo converts headline and body text to unicode when reading .leo files and external files.
    Both .leo files and external files may specify their encoding.  The default is utf-8.
    If the encoding used in a external file is not "utf-8" it is represented in the @+leo sentinel line.
    For example::

        #@+leo-encoding=iso-8859-1.

    The utf-8 encoding is a "lossless" encoding (it can represent all unicode code points),
    so converting to and from utf-8 plain strings will never cause a problem.
    When reading or writing a character not in a "lossy" encoding,
    Leo converts such characters to '?' and issues a warning. 

2.  When writing .leo files and external files Leo uses the same encoding used to read the file,
    again with utf-8 used as a default.

3.  leoSettings.leo contains the following Unicode settings, with the defaults as shown::

        default_derived_file_encoding = UTF-8 
        new_leo_file_encoding = UTF-8 

    These control the default encodings used when writing external files and .leo files.
    Changing the new_leo_file_encoding setting is not recommended.
    See the comments in leoSettings.leo.
    You may set default_derived_file_encoding to anything that makes sense for you.

4.  The @encoding directive specifies the encoding used in a external file.
    You can't mix encodings in a single external file.
</t>
<t tx="EKR.20040524104904.357">Here are the XML elements that may appear in Leo files:

&lt;?xml&gt;
    Leo files start with the following line::

        &lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;?xml-stylesheet&gt;
    An xml-stylesheet line is option.  For example::

        &lt;?xml-stylesheet ekr_stylesheet?&gt;

&lt;leo_file&gt;
    The &lt;leo_file&gt; element opens an element that contains the entire file.
    &lt;/leo_file&gt; ends the file.

&lt;leo_header&gt; 
    The &lt;leo_header&gt; element specifies version information and other information
    that affects how Leo parses the file.  For example::

        &lt;leo_header file_format="2" tnodes="0" max_tnode_index="5725" clone_windows="0"/&gt;

    The file_format attribute gives the 'major' format number.
    It is '2' for all 4.x versions of Leo.
    The tnodes and clone_windows attributes are no longer used.
    The max_tnode_index	attribute is the largest tnode index.

&lt;globals&gt;
    The globals element specifies information relating to the entire file.
    For example::

        &lt;globals body_outline_ratio="0.50"&gt;
            &lt;global_window_position top="27" left="27" height="472" width="571"/&gt;
            &lt;global_log_window_position top="183" left="446" height="397" width="534"/&gt;
        &lt;/globals&gt;

    -   The body_outline_ratio attribute specifies the ratio of the height of the body pane to
        the total height of the Leo window.
        It initializes the position of the splitter separating the outline pane from the body pane.

    -   The global_window_position and global_log_window_position elements
        specify the position of the Leo window and Log window in global coordinates:

&lt;preferences&gt;
    This element is vestigial.
    Leo ignores the &lt;preferences&gt; element when reading.
    Leo writes an empty &lt;preferences&gt; element.

&lt;find_panel_settings&gt;
    This element is vestigial.
    Leo ignores the &lt;find_panel_settings&gt; element when reading.
    Leo writes an empty &lt;find_panel_settings&gt; element.

&lt;clone_windows&gt;
    This element is vestigial.
    Leo ignores the &lt;clone_windows&gt; element when reading.
    Leo no longer writes &lt;clone_windows&gt; elements.

&lt;vnodes&gt;
    A single &lt;vnodes&gt; element contains nested &lt;v&gt; elements.
    &lt;v&gt; elements correspond to vnodes.
    The nesting of &lt;v&gt; elements indicates outline structure in the obvious way.

&lt;v&gt;
    The &lt;v&gt; element represents a single vnode and has the following form::

        &lt;v...&gt;&lt;vh&gt;sss&lt;/vh&gt; (zero or more nested v elements) &lt;/v&gt;

    The &lt;vh&gt; element specifies the headline text.
    sss is the headline text encoded with the usual XML escapes.
    As shown above, a &lt;v&gt; element may contain nested &lt;v&gt; elements.
    This nesting indicates outline structure in the obvious way.
    Zero or more of the following attributes may appear in &lt;v&gt; elements::

        t=name.timestamp.n
        a="xxx"

    The t="Tnnn" attribute specifies the &lt;t&gt; element associated with a &lt;v&gt; element.
    The a="xxx" attribute specifies vnode attributes.
    The xxx denotes one or more upper-case letters whose meanings are as follows::

        C	The vnode is a clone. (Not used in 4.x)
        E	The vnode is expanded so its children are visible.
        M	The vnode is marked.
        T	The vnode is the top visible node.
        V	The vnode is the current vnode.

    For example, a="EM"  specifies that the vnode is expanded and is marked.

    **New in 4.0**:

    -   &lt;v&gt; elements corresponding to @file nodes now contain tnodeList attributes.
        The tnodeList attribute allows Leo to recreate the order in which nodes should appear in the outline.
        The tnodeList attribute is a list of gnx's: global node indices.
        See Format of external files (4.x) for the format of gnx's.

    -   Plugins and scripts may add attributes to &lt;v&gt; and &lt;t&gt; elements.
        See `Writing plugins`_ for details.

&lt;tnodes&gt;
    A single &lt;tnodes&gt; element contains a non-nested list of &lt;t&gt; elements.

&lt;t&gt;
    The &lt;t&gt; element represents the body text of the corresponding &lt;v&gt; element.
    It has this form::

        &lt;t tx="&lt;gnx&gt;"&gt;sss&lt;/t&gt;

    The tx attribute is required.
    The t attribute of &lt;v&gt; elements refer to this tx attribute.
    sss is the body text encoded with the usual XML escapes.

    **New in 4.0**: Plugins and scripts may add attributes to &lt;v&gt; and &lt;t&gt;
    elements. See `Writing plugins`_ for details.
</t>
<t tx="EKR.20040524104904.99"></t>
<t tx="TL.20080804095315.1"></t>
<t tx="TL.20080804095315.2">###########################
Using Vim Bindings with Leo
###########################

This chapter describes Leo's vim-like bindings, including how to install them.

.. contents::
    :depth: 3
</t>
<t tx="TL.20080804095315.4">Place a copy of the "@keys Vim bindings" node and its sub-nodes,
located in the leoSettings.leo file, under the "@settings" node
in the myLeoSettings.leo file

The same procedure is performed to update to a new version.

Note: Place any local customized key bindings in a separate
"@keys My Vi" node in the myLeoSettings.leo file to prevent
them from being overwritten when updating to a new version.
</t>
<t tx="TL.20080804095315.5">The following commands are always available.

State change commands::

    i           Change state to insert from command state
    Esc         Change state to command from insert state
    Ctrl-[      Same as ESC

Save/Exit/Quite commands::

    :e          Revert
    :w&lt;return&gt;  Save '.leo' file
    :wq&lt;return&gt; Save '.leo' file and quit Leo
    :q&lt;return&gt;  Quit Leo   (Leo will prompt if file not saved)
    ZZ          Save leo file and exit

Undo/Redo commands::

    u           Undo previous command
    Ctrl-r      Redo previous command


Search options::

    Ctrl-/      Prompt for option to change
                Options:
                    a   Search all nodes (also &lt;cr&gt; key)
                    h   Toggle headline search
                    b   Toggle body search
                    m   Toggle marking of nodes (specify sub-option)
                        f   Toggle marking of nodes with found text
                        c   Toggle marking of nodes with changed text
                            (only supported with 'Alt-/', 'Alt-p')
                    r   Toggle regex matches
                        ('/' key turns off regex. 'n' key uses regex if turned on)

    Note: Whether a search is limited to node's body or the node's sub-outline
          is determined by which pane has focus when search text specified.
          (See "Find text commands:" sub-sections in Outline/Body Pane sections)

Miscellaneous commands::

    Tab         Toggle focus between Outline and Body pane
    =           Simulate double-click on current node's icon box
    Alt-G       Go to specified line number (relative to external file)
    Ctrl-:      Enter Leo's command line
</t>
<t tx="TL.20080804095315.6">Move cursor commands::

    h           Go back 1 character
       LtArrow  Mapped to "h" for convenience
    j           Go down 1 line
       DnArrow  Mapped to "j" for convenience
    k           Go up 1 line
       UpArrow  Mapped to "k" for convenience
    l           Go forward 1 character
       RtArrow  Mapped to "l" for convenience

    w           Go to beginning of next word
       W        Mapped to "w" until "stop after blank characters" supported
    b           Go to beginning of current/previous word
       B        Mapped to "b" until "stop at blank character" supported
    e           Go to end of current/next word
       E        Mapped to "e" until "stop at blank character" supported

    Note: Move by word commands stop at non-alpha characters

    |           Goto beginning of current line
    ^           Go to 1st non-blank character on current line
    $           Goto end of current line

    %           Go to matching bracket

    (           Go to beginning of current sentence
    )           Go to beginning of next sentence
    {           Go to beginning of current paragraph
    }           Go to beginning of next paragraph

    gg          Go to the first line (Cursor at column 1)
    G           Go to the last line  (Cursor at column 1)

Mark commands::

    m&lt;label&gt;    Assign cursor location to a single character label
    `&lt;label&gt;    Go to location associated with label

      Note: Only character count is tracked. Any inserts or deletes will change mark.
          Mark's are not node specific; `&lt;label&gt; will go to location in current node.

Select commands::

    Ctrl-v      Toggle text select mode (Vim's "visual" mode)
       V        Mapped to 'Ctrl-v' for convenience (Should toggle line select)

Insert/substitute commands::

    a           Insert at cursor
    i           Mapped to "a" until "cursor on a character" supported
    A           Insert at end of line
    I           Insert at first non-space
    o           Open new line below current line
    O           Open new line above current line
    R           Overwrite text
    s           Substitute character (Delete character, enter insert state)
    S           Substitute line (Delete line, enter insert state)

Change commands::

    C           Change to end of line
    cc          Change all of current line
    cw          Change to end of word
    cb          Change to beginning of word
    c)          Delete to end of sentence
    c(          Delete to beginning of sentence
    c}          Delete to end of paragraph
    c{          Delete to beginning of paragraph
    c%          Change from current bracket type its matching bracket type
    ct&lt;char&gt;    Selects forward to &lt;char&gt; (follow with 'i' to change selection)
    cT&lt;char&gt;    Selects backward to &lt;char&gt; (follow with 'i' to change selection)
    c&lt;cr&gt;       Change selected text

Delete commands::

    x           Delete next character
    delete      Delete next character
    D           Delete to the end of the current line
    dd          Delete current line
    dw          Delete to end of word
    db          Delete to beginning of word
    d)          Delete to end of sentence
    d(          Delete to beginning of sentence
    d}          Delete to end of paragraph
    d{          Delete to start of paragraph
    d%          Delete from current bracket type to its apposing bracket
    dt&lt;ch&gt;      Delete to character (not limited to current line)
    d&lt;cr&gt;       Delete selected text

    J           Join next line to end of current line (deletes carriage return)

Yank text commands::

    Y           Yank to end of line
    yy          Yank line
    yw          Yank to beginning of next word
    yb          Yank to beginning of current word
    y)          Yank to end of sentence
    y(          Yank to beginning of sentence
    y}          Yank to end of paragraph
    y{          Yank to beginning of paragraph
    y%          Yank from current bracket type to its opposing bracket
    yt&lt;char&gt;    Select forward to &lt;char&gt;  (use 'y&lt;cr&gt;' to yank selection)
    yT&lt;char&gt;    Select backward to &lt;char&gt; (use 'y&lt;cr&gt;' to yank selection)
    y&lt;cr&gt;       Yank selected text (Vim uses 'y' in visual mode)

Find character commands::

    f           Find next occurrence of user specified character
    F           Find previous occurrence of user specified character

Find text commands::

    /           Search forward within current node's body text
    ?           Search backward within current node's body text
    n           Find next (same scope, same direction)
    N           Find next (same scope, other direction)

    Note: See "Search options" in General Commands section to change options.

Replace [and find next] commands::

    Commands using Paste buffer (clipboard)
    P           Paste text before cursor.
    p           Mapped to "P" until character based cursor supported.
    Ctrl-p      Paste then find next match
                Note: Use 'pn' instead of 'Ctrl-p' in headlines (Leo limitation)
                      Command will continue to paste when match no longer found.

    Commands prompting for replace string
    Note: Scope and direction taken from last use of '/','?' or 'Ctrl-/'(scope only)
    Alt-/       Prompt for search &amp; replace string
    Alt-p       Replace then search (use after Alt-/)
                Note: Works in headlines and body panes.
                      Doesn't paste unless last search found a match.

Indent/Unindent line commands::

    &gt;&gt;          Indent the current line
    &gt;)          Indent to the end of sentence
    &gt;(          Indent to the beginning of sentence
    &gt;}          Indent to the end of paragraph
    &gt;{          Indent to the beginning of paragraph
    &gt;g          Indent to the start of buffer
    &gt;G          Indent to the end of buffer

    &lt;&gt;          Unindent the current line
    &lt;)          Unindent to the end of sentence
    &lt;(          Unindent to the beginning of sentence
    &lt;}          Unindent to the end of paragraph
    &lt;{          Unindent to the beginning of paragraph
    &lt;g          Unindent to the start of buffer
    &lt;G          Unindent to the end of buffer

Format commands::

    gqap        Split long line into separate lines
    gwap        Split long line into separate lines
    gqq         Split long line into separate lines
    gww         Split long line into separate lines

    Note: 'gwap' and 'gww' should not move cursor but do.

Scroll commands::

    Ctrl-b      Scroll text up by pane's height
    Ctrl-f      Scroll text down by pane's height
       Ctrl-y   Mapped to Ctrl-b until scroll up one line is supported
       Ctrl-e   Mapped to Ctrl-f until scroll down one line is supported
       Ctrl-u   Mapped to Ctrl-b until scroll up half a pane height is supported
       Ctrl-d   Mapped to Ctrl-f until scroll down half a pane height is supported

Window commands::

    Ctrl-w s    Open another view into current node's body (Vim: Split window)
       Ctrl-w n Mapped to "Ctrl-w s" (Vim: New buffer in split window)
    Ctrl-w w    Switch to next view (Vim: Go to up/left window w/wrapping)
       Ctrl-w p Mapped to "Ctrl-w w" (Vim: Cycle through windows)
       Ctrl-w k Mapped to "Ctrl-w w" (Vim: Go to window above current window)
       Ctrl-w j Mapped to "Ctrl-w w" (Vim: Go to window below current window)
    Ctrl-w c    Close current view in body pane (Vim: Close current window)
       Ctrl-w q Mapped to "Ctrl-w c" (Vim: Quit current window)

Node commands::

    Go to another node while focus remains in the body pane.
    Ctrl-j      Go to next visible node
    Ctrl-k      Go to previous visible node
    Ctrl-h      Hide sub-nodes or, if hidden, go up 1 level
    Ctrl-l      Display sub-nodes or, if displayed, go down 1 level
       Ctrl-DnArrow    Mapped to "Ctrl-j" for convenience
       Ctrl-UpArrow    Mapped to "Ctrl-k" for convenience
       Ctrl-LtArrow    Mapped to "Ctrl-h" for convenience
       Ctrl-RtArrow    Mapped to "Ctrl-l" for convenience
</t>
<t tx="TL.20080804095315.7">The following commands are supported when in a headline's command mode.

State change commands::

    Ctrl-i      Change state to command from grayed state
    return      Change state to command from insert state
    Ctrl-]      Change state to grayed from command state

Cursor movement commands::

    h           Go to previous character
       LtArrow  Mapped to 'h' for convenience
    l           Go to next character
       RtArrow  Mapped to "l" for convenience

    Note: 'j' and 'k' will scroll the buffer contents up and down;
          leaving the focus in the outline pane.

    w           Go to beginning of next word
       W        Mapped to "w" until "stop after blank characters" supported
    b           Go to beginning of current/previous word
       B        Mapped to "b" until "stop at blank character" supported
    e           Go to end of current/next word
       E        Mapped to "e" until "stop at blank character" supported

    Note: Move by word commands stop at non-alpha characters

    |           Go to beginning of line
    ^           Go to beginning of line
    $           Go to end of line

    %           Go to matching bracket

Edit commands::

    x           Delete next character
    delete      Delete next character
    dd          kill-line

    s           Select current character

    v           Toggle text select mode (issue cursor movement commands)
    y&lt;return&gt;   Yank selected text

    C           Select to end of line (follow with 'i' to change text)
    cc          Delete line (follow with 'i' to change text)

    D           Select to end of line (follow with 'x' to delete text)
    dd          Delete line

    Y           Select to end of line (follow with 'y&lt;return&gt;' to yank text)
    yy          Select line (follow with 'y&lt;return&gt;' to yank text)

Find character commands::

    f           Find next occurrence of user specified character
    F           Find previous occurrence of user specified character

Find text commands::

    /           Search forward within current node and its subnodes
    n           Find next (same scope, same direction)
    N           Find next (same scope, other direction)

    Note: See "Search options" section above to change options using 'Ctrl-/'

Replace [and find next] commands::

    Commands that use Paste buffer (clipboard)
    Note: Paste-then-search command not possible in headlines (Use 'pn')
    P           Paste text before cursor.
    p           Mapped to "P" until character based cursor supported.

    Commands that prompt for the replace string
    Alt-/       Prompt for search &amp; replace string
    Alt-p       Replace then search (use after Alt-/)
                Note: Works in headlines and body panes.
                      Doesn't paste unless last search found a match.

Node edit commands::

    o           Insert node after current node

    Ctrl-x      Delete current node
    Ctrl-c      Yank current node
    Ctrl-v      Paste current node

Node goto commands::

    G           Go to the outline's last node
    gg          Go to the outline's first node

    Ctrl-j      Go to next visible node
    Ctrl-k      Go to previous visible node
    Ctrl-h      Hide sub-nodes or, if hidden, go up 1 level
    Ctrl-l      Display sub-nodes or, if displayed, go down 1 level

       DnArrow  Mapped to "Ctrl-j" for convenience
       UpArrow  Mapped to "Ctrl-k" for convenience

       Ctrl-DnArrow Mapped to "Ctrl-j" for convenience
       Ctrl-UpArrow Mapped to "Ctrl-k" for convenience
       Ctrl-LtArrow Mapped to "Ctrl-h" for convenience
       Ctrl-RtArrow Mapped to "Ctrl-l" for convenience

Node move commands::

    Ctrl-Shift-k    Move node down
    Ctrl-Shift-h    Move node left
    Ctrl-Shift-l    Move node right
    Ctrl-Shift-j    Move node up

       Ctrl-Shift-DnArrow    Mapped to "Ctrl-Shift-k" for convenience
       Ctrl-Shift-LtArrow    Mapped to "Ctrl-Shift-h" for convenience
       Ctrl-Shift-RtArrow    Mapped to "Ctrl-Shift-l" for convenience
       Ctrl-Shift-UpArrow    Mapped to "Ctrl-Shift-j" for convenience

Node mark commands::

    m           Toggle node mark
    Ctrl-m      Go to next marked node
    Alt-m       Clear all marked nodes

Node clone commands::

    t           Clone the current node (transclude)
    Ctrl-t      Go to next clone of current node

Outline scroll commands::

   Ctrl-y       Scroll outline up one line
   Ctrl-e       scroll outline down one line
   Ctrl-u       Scroll outline up one half page
   Ctrl-d       scroll outline down one half page
   Ctrl-b       Scroll outline up one page
   Ctrl-f       scroll outline down one page

</t>
<t tx="TL.20080804095315.8">Notable missing editing commands::

    t&lt;char&gt;     Move cursor to character before specified character
    r           Replace a single character with a single character
    0           Go to 1st column in current line (Use '|' instead)
    bksp        Move one character to the left
    ~           Toggle character's case
    .           Repeat last editing command
    ;           Repeat last cursor movement command
    &lt;n&gt;&lt;cmd&gt;    Perform command 'n' number of times
    &lt;cmd&gt;&lt;n&gt;&lt;object&gt;    Perform the command on the n'th or up to the n'th object

Notable missing body pane commands::

    &lt;num&gt;G      Go to specified line number
    z&lt;movement&gt; Slide buffer to put current line at top/middle/bottom of pane
    '&lt;command&gt;  Go to line of last edit, jump, ...
    `&lt;command&gt;  Go to character of last edit, jump, ...
</t>
<t tx="TL.20080804095315.9">If you use the open-with command to open a node text in Vim and your
Vim's "tag" file refers to external files then there is a risk that a
external file that is initially displayed via the "tag" command" in
Vim is accidentally edited and saved from the external Vim editor
while your Leo session still contains the external file's original
text that may later recreate the original external file during a Leo
save operation (overwriting the changes saved from the Vim editor).

To prevent this problem, modifications to external files can be avoided by using
Vim's "modeline" feature to disable editing of external files.

Vim's "modeline" feature scans each loaded buffer for text at the top or bottom
of the file containing " vim:" followed by a series of Vim options. The text is
usually embedded within a comment. The following example prevents modifications
to a buffer in a Python file::

    # vim:noma (A space is required between the '#' and "vim:noma")

If this line is placed in a separate Leo node at the top or bottom of the list
of nodes under a external file node (ex: @file) then any external file saved and
then later loaded into Vim will, by default, not be modifiable. If a derived
file does need to be edited then modifications can be re-enabled on a
file-by-file basis by issuing Vim's ":ma" command while viewing the derived
file.

The number of lines that Vim checks at the top and bottom of the buffer is
configurable. The following Vim command must be placed in the vimrc file to
allow for Leo's trailing sentinel lines::

    set modelines=8

Issue the ":help modeline" command within Vim for the more information about
modelines.
</t>
<t tx="ekr.20040403171740">@ @rst-options
.. A very cool option: doc parts will be rendered properly,
.. but will be ignored by the Execute script command.
..
show_doc_parts_as_paragraphs = True
@c

#########################
Scripting Leo with Python
#########################

.. _`Python Tutorial`: http://docs.python.org/2/tutorial/

This chapter tells how to write **Leo scripts**, Python scripts run from
any Leo node.

This chapter also discusses several topics related to scripting:
autocompletion, @button and @test.

This chapter is intended for those fairly comfortable with Python
scripting. If you are not, please study the excellent `Python Tutorial`_.

.. contents::
    :depth: 3
</t>
<t tx="ekr.20040403173920.18" rst_http_attribute="5d71002858460000003c6120636c6173733d22746172676574222069643d22687474702d6e6f64652d6d61726b65722d323722206e616d653d22687474702d6e6f64652d6d61726b65722d3237223e710158040000003c2f613e71025d710328582e0000003c64697620636c6173733d2273656374696f6e222069643d227570646174696e672d7468652d73637265656e223e710458060000003c2f6469763e71055d710628583f0000003c64697620636c6173733d22646f63756d656e74222069643d22636861707465722d372d736372697074696e672d6c656f2d776974682d707974686f6e223e710758060000003c2f6469763e71085d71092858060000003c626f64793e710a58070000003c2f626f64793e710b5d710c2858430000003c68746d6c20786d6c6e733d22687474703a2f2f7777772e77332e6f72672f313939392f7868746d6c2220786d6c3a6c616e673d22656e22206c616e673d22656e223e710d58070000003c2f68746d6c3e710e4e6565656558070000003c2f6469763e0a710f583a0000003c64697620636c6173733d2273656374696f6e222069643d22696e766f6b696e672d636f6d6d616e64732d66726f6d2d73637269707473223e0a711058760000003c68313e3c6120636c6173733d22746f632d6261636b7265662220687265663d22236964313422206e616d653d22696e766f6b696e672d636f6d6d616e64732d66726f6d2d73637269707473223e496e766f6b696e6720636f6d6d616e64732066726f6d20736372697074733c2f613e3c2f68313e0a7111652e">Leo dispatches commands using c.doCommand,
which calls the "command1" and "command2" hook routines for the given label.
c.doCommand catches all exceptions thrown by the command::

    c.doCommand(c.markHeadline,label="markheadline")

You can also call command handlers directly so that hooks will not be called::

    c.markHeadline()

You can invoke minibuffer commands by name.  For example::

    c.executeMinibufferCommand('open-outline')

c.keyHandler.funcReturn contains the value returned from the command.
In many cases, as above, this value is simply 'break'.
</t>
<t tx="ekr.20040403173920.19" rst_http_attribute="5d71002858460000003c6120636c6173733d22746172676574222069643d22687474702d6e6f64652d6d61726b65722d323922206e616d653d22687474702d6e6f64652d6d61726b65722d3239223e710158040000003c2f613e71025d71032858390000003c64697620636c6173733d2273656374696f6e222069643d22696e766f6b696e672d636f6d6d616e64732d66726f6d2d73637269707473223e710458060000003c2f6469763e71055d710628583f0000003c64697620636c6173733d22646f63756d656e74222069643d22636861707465722d372d736372697074696e672d6c656f2d776974682d707974686f6e223e710758060000003c2f6469763e71085d71092858060000003c626f64793e710a58070000003c2f626f64793e710b5d710c2858430000003c68746d6c20786d6c6e733d22687474703a2f2f7777772e77332e6f72672f313939392f7868746d6c2220786d6c3a6c616e673d22656e22206c616e673d22656e223e710d58070000003c2f68746d6c3e710e4e6565656558070000003c2f6469763e0a710f583b0000003c64697620636c6173733d2273656374696f6e222069643d2267657474696e672d616e642d73657474696e672d707265666572656e636573223e0a711058780000003c68313e3c6120636c6173733d22746f632d6261636b7265662220687265663d22236964313522206e616d653d2267657474696e672d616e642d73657474696e672d707265666572656e636573223e47657474696e6720616e642073657474696e6720707265666572656e6365733c2f613e3c2f68313e0a7111652e">Each commander sets ivars corresponding to settings.

Scripts can get the following ivars of the Commands class::

    ivars = (
        'output_doc_flag',
        'page_width',
        'page_width',
        'tab_width',
        'target_language',
        'use_header_flag',
    )
    print("Prefs ivars...\n",color="purple")
    for ivar in ivars:
        print(getattr(c,ivar))

If your script sets c.tab_width it should call f.setTabWidth to redraw the
screen::

    c.tab_width = -4    # Change this and see what happens.
    c.frame.setTabWidth(c.tab_width)
</t>
<t tx="ekr.20040403173920.24" rst_http_attribute="5d71002858460000003c6120636c6173733d22746172676574222069643d22687474702d6e6f64652d6d61726b65722d333722206e616d653d22687474702d6e6f64652d6d61726b65722d3337223e710158040000003c2f613e71025d71032858260000003c64697620636c6173733d2273656374696f6e222069643d22672d726566696e64616c6c223e710458060000003c2f6469763e71055d710628584f0000003c64697620636c6173733d2273656374696f6e222069643d2266756e6374696f6e732d666f722d66696e64696e672d616e642d6368616e67696e672d746578742d66726f6d2d73637269707473223e710758060000003c2f6469763e71085d710928583f0000003c64697620636c6173733d22646f63756d656e74222069643d22636861707465722d372d736372697074696e672d6c656f2d776974682d707974686f6e223e710a58060000003c2f6469763e710b5d710c2858060000003c626f64793e710d58070000003c2f626f64793e710e5d710f2858430000003c68746d6c20786d6c6e733d22687474703a2f2f7777772e77332e6f72672f313939392f7868746d6c2220786d6c3a6c616e673d22656e22206c616e673d22656e223e711058070000003c2f68746d6c3e71114e656565656558070000003c2f6469763e0a711258070000003c2f6469763e0a711358350000003c64697620636c6173733d2273656374696f6e222069643d2272756e6e696e672d6c656f2d696e2d62617463682d6d6f6465223e0a7114586c0000003c68313e3c6120636c6173733d22746f632d6261636b7265662220687265663d22236964313922206e616d653d2272756e6e696e672d6c656f2d696e2d62617463682d6d6f6465223e52756e6e696e67204c656f20696e206261746368206d6f64653c2f613e3c2f68313e0a7115652e">On startup, Leo looks for two arguments of the form::

    --script scriptFile

If found, Leo enters batch mode. In batch mode Leo does not show any windows.
Leo assumes the scriptFile contains a Python script and executes the contents of
that file using Leo's Execute Script command. By default, Leo sends all
output to the console window. Scripts in the scriptFile may disable or enable
this output by calling app.log.disable or app.log.enable

Scripts in the scriptFile may execute any of Leo's commands except the Edit Body
and Edit Headline commands. Those commands require interaction with the user.
For example, the following batch script reads a Leo file and prints all the
headlines in that file::

    path = g.os_path_finalize_join(g.app.loadDir,'..','test','test.leo')
    assert g.os_path_exists(path),path

    g.app.log.disable() # disable reading messages while opening the file
    c2 = g.openWithFileName(path)
    g.app.log.enable() # re-enable the log.

    for p in c2.all_positions():
        g.es(g.toEncodedString(p.h,"utf-8"))
</t>
<t tx="ekr.20040414161647" str_atime="1376411963.0">@pagewidth 70
@tabwidth -4

These are the sources for Leo's users guide.

They contain sphinx markup. See::

    http://sphinx.pocoo.org/
    http://docutils.sourceforge.net/docs/user/rst/quickstart.html
    
To generate these docs, see the next node: "Generating the Users Guide"
    
Important files:

- doc\html\conf.py contains settings, including the name of the master toctree
  document, leo_toc.html.txt.

- leo_toc.html.txt contains a list of all file to be included.
</t>
<t tx="ekr.20040414172218.4">Leo owes much of its visual design to MORE, possibly the most elegant
computer program ever written. Leo's clone nodes are inspired by MORE.

The following people have made generous donations to the Leo project:
Robert Low, Nic Cave-Lynch.

The following people reported bugs, answered questions, and made suggestions for
improving Leo:
Alex Abacus, Shakeeb Alireze, Steve Allen, Bruce Arnold,
Chris Barker, Dennis Benzinger, David Boddie, Jason Breti, Eric Brown, Terry Brown,
Darius Clarke, Martin Clifford, Jason Cunliffe,
Josef Dalcolmo, Gil Dev, Bill Drissel, Wenshan Du,
Allen Edwards, Chris Elliot, Dethe Elza, Mark Engleberg, Roger Erens, 
Stephen Ferg, Tom Fetherston, Tomaz Ficko, Niklas Frykholm,
Fred Gansevles, Jonathan M. Gilligan, Zak Greant, Thomas Guettler, Romain Guy,
Dave Hein, Tiago Castro Henriques, Gary Herron, Steve Holden, Klass Holwerda, Matthias Huening, Robert Hustead,
John Jacob, Paul Jaros, Christopher P. Jobling, Eric S. Johansson, Garold Johnson, 
James Kerwin,
Nicola Larosa, David LeBlanc, Chris Liechti, Steve Litt, Martin v. Löwis (Loewis), Robert Low, Fredrik Lundh,
Michael Manti, Alex Martelli, Marcus A. Martin, Gidion May, David McNab, Frank Merenda, Martin Montcrieffe, Will Munslow,
Chad Netzer, Derick van Niekerk, Jeff Nowland,
Naud Olivier, Joe Orr,
Marc-Antoine Parent, Paul Paterson, Sean Shaleh Perry, Tim Peters, David Priest, Gary Poster, Scott Powell,
Bruce Rafnel, Walter H. Rauser, Olivier Ravard, David Speed Ream, Rich Ries, Aharon Robbins, Guido van Rossum, David Rowe,
Davide Salomoni, Steven Schaefer,Johannes Schöön, Wolfram Schwenzer, Casey Wong Kam Shun,
Gil Shwartz, Jim Sizelove, Paul Snively, Jurjen Stellingwerff, Phil Straus, David Szent-Györgyi,
Kent Tenney, Jeffrey Thompson,
Gabriel Valiente, Jim Vickroy, Tony Vignaux, Tom van Vleck,
Kevin Walzer, Ying-Chao Wang, Cliff Wells, Dan Wharton, John Wiegley, Wim Wijnders, Dan Winkler, 
Vadim Zeitlin.

The following have contributed plugins to Leo:

Rodrigo Benenson, Pierre Bidon, Felix Breuer, Terry Brown,
Mike Crowe,
Josef Dalcolmo, Michael Dawson,
e, Roger Erens, 
Andrea Galimberti, Engelbert Gruber,
Timo Honkasalo,
Jaakko Kourula, Maxim Krikun,
Zhang Le, LeoUser,
Frédéric Momméja, Bernhard Mulder, 
Mark Ng,
Alexis Gendron Paquette, Paul Paterson,
Dan Rahmel,
Davide Salomoni,
Ed Taekema, Kent Tenney, Brian Theado,
Ville M. Vainio,
Steve Zatz.
</t>
<t tx="ekr.20040416080538">The following deserve special mention:
David Brock wrote TSyntaxMemo.
The late Bob Fitzwater kept me focused on design.
Donald Knuth invented the CWEB language.
Jonathan M. Gilligan showed how to put the Leo icon in Leo's windows.
Joe Orr created XSLT stylesheets for Leo; see http://www.jserv.com/jk_orr/xml/leo.htm.
Joe Orr also created an outstanding set of tutorials for Leo; see http://www.evisa.com/e/sb.htm.
LeoUser (B.H.) contributed numerous plugins and was the inspiration for Leo's minibuffer.
LeoUser also wrote jyLeo: Leo for Jython.
The late Bernhard Mulder proposed a new way of untangling external files.
John K. Ousterhout created tcl/Tk. Neal Norwitz wrote PyChecker.
Marc-Antoine Parent urged me to use XML for Leo's file format and helped improve it.
Paul Paterson suggested the plugin architecture,
suggested an approach to spell checking and has contributed many excellent plugins.
François Pinard wrote pymacs.
Norman Ramsey created noweb and gave permission to quote from the noweb web documentation.
Rich Ries has contributed a huge number of suggestions.
Steven P. Schaefer pointed out major security problems lurking in hooks.
Gil Shwartz helped with unicode support.
Phil Straus has been a great friend and constant support.
Guido van Rossum created Python, Tkinter and the Python License.
Dave Winer created MORE.
Ville M. Vainio created ILeo and has made many other valuable contributions to Leo.
Dan Winkler helped support Leo on the Mac.

Special thanks to my family.
My brother, David Speed Ream, tested Leo and made many useful suggestions.
Rebecca, James and Linda make it all worthwhile.
It was during a conversation with Rebecca that I realized that MORE could be used as a prototype for Leo.
That was a crucial first step.
</t>
<t tx="ekr.20050306090601">Leo's .leo file format is extensible.
The basis for extending .leo files are the v.unknownAttributes ivars of vnodes,
uA's for short.
Leo translates between uA's and xml attributes in the corresponding
&lt;v&gt; elements in .leo files.
Plugins may also use v.tempAttributes ivars to hold temporary information
that will *not* be written to the .leo file.
These two ivars are called **attribute ivars**.

Attribute ivars must be Python dictionaries, whose keys are names of plugins and
whose values are *other* dictionaries, called **inner dictionaries**, for
exclusive use of each plugin.

The v.u Python property allows plugins to get and set v.unknownAttributes easily::

    d = v.u # gets uA (the outer dict) for v
    v.u = d # sets uA (the outer dict) for v

For example::

    plugin_name = 'xyzzy'
    d = v.u # Get the outer dict.
    inner_d = d.get(plugin_name,{}) # Get the inner dict.
    inner_d ['duration']= 5
    inner_d ['notes'] "This is a note."
    d [plugin_name] = inner_d
    v.u = d

No corresponding Python properties exist for v.tempAttributes,
so the corresponding example would be::

    plugin_name = 'xyzzy'
    # Get the outer dict.
    if hasattr(p.v,'tempAttributes'): d = p.v.tempAttributes
    else: d = {}
    inner_d = d.get(plugin_name,{}) # Get the inner dict.
    inner_d ['duration'] = 5
    inner_d ['notes'] = "This is a note."
    d [plugin_name] = inner_d
    p.v.tempAttributes = d

**Important**: All members of inner dictionaries should be picklable: Leo
uses Python's Pickle module to encode all values in these dictionaries. Leo will
discard any attributes that can not be pickled. This should not be a major
problem to plugins. For example, instead of putting a tnode into these
dictionaries, a plugin could put the tnode's gnx (a string) in the dictionary.

**Note**: Leo does *not* pickle members of inner dictionaries whose name (key) starts with str\_.
The values of such members should be a Python string.
This convention allows strings to appear in .leo files in a more readable format.

Here is how Leo associates uA's with &lt;v&gt; elements in .leo files:

- **Native xml attributes** are the attributes of &lt;v&gt; elements that are
  known (treated specially) by Leo's read/write code. The native attributes of
  &lt;v&gt; elements are a, t, vtag, tnodeList, marks,
  expanded and descendentTnodeUnknownAttributes. All other attributes of
  &lt;v&gt; and &lt;t&gt; elements are **foreign xml attributes**.

- When reading a .leo file, Leo will create v.unknownAttributes ivars for
  any vnode whose corresponding &lt;v&gt; or &lt;t&gt; element contains a
  foreign xml attribute.

- When writing a file, Leo will write foreign xml attributes in &lt;v&gt; elements
  if the corresponding vnode contains an unknownAttributes ivar.

- Leo performs the usual xml escapes on these strings when reading or writing
  the unknownAttributes ivars.
</t>
<t tx="ekr.20050313102319">The ``add-comments`` (Ctrl-)) command puts comments around a block of code.
This command uses single-line comments if possible. The ``delete-comments``
(Ctrl-() command deletes the comments.
</t>
<t tx="ekr.20050407144342">



</t>
<t tx="ekr.20050407144342.1"></t>
<t tx="ekr.20050407144342.2"></t>
<t tx="ekr.20050407144342.3"></t>
<t tx="ekr.20050407144417"></t>
<t tx="ekr.20050417072710.1">Plugins and scripts should call u.beforeX and u.afterX methods ato
describe the operation that is being performed. **Note**: u is shorthand for
c.undoer. Most u.beforeX methods return undoData that the client
code merely passes to the corresponding u.afterX method. This data contains
the 'before' snapshot. The u.afterX methods then create a bead containing
both the 'before' and 'after' snapshots.

u.beforeChangeGroup and u.afterChangeGroup allow multiple calls to
u.beforeX and u.afterX methods to be treated as a single undoable entry.
See the code for the Replace All, Sort, Promote and Demote
commands for examples. The u.beforeChangeGroup and u.afterChangeGroup
methods substantially reduce the number of u.beforeX and afterX methods
needed.

Plugins and scripts may define their own u.beforeX and afterX methods. Indeed,
u.afterX merely needs to set the bunch.undoHelper and
bunch.redoHelper ivars to the methods used to undo and redo the operation.
See the code for the various u.beforeX and afterX methods for guidance.

p.setDirty and p.setAllAncestorAtFileNodesDirty now return a
dirtyVnodeList that all vnodes that became dirty as the result of an
operation. More than one list may be generated: client code is responsible for
merging lists using the pattern dirtyVnodeList.extend(dirtyVnodeList2)

See the section &lt;&lt; How Leo implements unlimited undo &gt;&gt; in leoUndo.py
for more details. In general, the best way to see how to implement undo is to
see how Leo's core calls the u.beforeX and afterX methods.
</t>
<t tx="ekr.20050812123002"></t>
<t tx="ekr.20050812123002.1"></t>
<t tx="ekr.20050812123002.2">Deletes p.v.rst2_http_attributename from all nodes after writing.

Deletes p.v.unknownAttributes if it then becomes empty.
</t>
<t tx="ekr.20050812123002.3"></t>
<t tx="ekr.20050812123002.4">@nocolor

If False, add_node_marker and http_support_main  do nothing.  Otherwise add_node_marker does the following:

1. add_node_marker writes a string using generate_node_marker.

Generates 'http-node-marker-'+str(number), where number is config.node_counter
(incremented each time add_node_marker is called.

2. Enables the following code in :
@color

    if config.tag == 'open2':
        http_map = self.http_map
    else:
        http_map = {}
        config.anchormap = {}
        # maps v nodes to markers.
        config.node_counter = 0
    # [snip] code to write the tree
    if config.rst2_http_server_support:
        self.http_map = http_map
</t>
<t tx="ekr.20050812123002.5"></t>
<t tx="ekr.20050812123002.6">True: call body_filter to massage text.

Removes @ignore, @nocolor, @wrap directives.
</t>
<t tx="ekr.20050812123002.7">Used differently.  See rst2_pure_document.
</t>
<t tx="ekr.20050812134441.1">.. Links used in this document.

.. |br| raw:: html

   &lt;br /&gt;

.. _`Leo's Directive Reference`: directives.html
.. _`Leo's cheat sheet`: cheatsheet.html
.. _`Python generators`:    https://wiki.python.org/moin/Generators
.. _`scripting portion`: cheatsheet.html#scripting
</t>
<t tx="ekr.20050818163826">########################################
Creating Documents with the rst3 Command
########################################

This chapter discusses Leo's rst3 command. The rst3 command creates HTML, PDF,
LaTeX and other kinds of documents from Leo outlines containing
`reStructuredText`_ (rST) or `Sphinx`_ markup.

**Note**: `docutils`_ is a document processing system using rST markup.
`Sphinx`_ extends docutils: Sphinx markup is a superset of rST markup. All of
Leo's documentation is written in Sphinx and processed with the rst3 command to
produce HTML files.

Leo and rst3 make writing rST/Sphinx documents a *lot* easier:

1. Leo outlines organize writing in all the usual ways. You always see the
   structure of your writing clearly no matter how large it is. You can
   reorganize chapters, sections and paragraphs effortlessly. View nodes can
   show you many different views of your writing simultaneously. These
   features, all by themselves, would make Leo an excellent choice for
   editing rST documents.

2. Furthermore, the rst3 command automatically creates rST sections from
   headlines. Without Leo, changing the level of a section is clumsy and
   error prone: you must carefully change the section's underlining
   character. Leo's rst3 command eliminates all this bother.

3. The rst3 command converts an \@rst tree to rST and then sends this text to
   docutils or Sphinx for further processing.

In addition to these basic features, the rst3 command provides *many* other
capabilities for power users. We'll discuss these features later.

.. contents::
    :depth: 4
</t>
<t tx="ekr.20050818163826.1">.. rST links used in this document...

.. _`Scripting`:            tutorial-scripting.html

.. External links...
.. _docutils:               http://docutils.sourceforge.net
.. _LaTeX:                  http://www.latex-project.org/
.. _reStructuredText:       http://docutils.sourceforge.net/rst.html
.. .. _SilverCity:             http://silvercity.sourceforge.net
.. _Sphinx:                 http://sphinx.pocoo.org/
.. _`Leo's Google Group`:   http://groups.google.com/group/leo-editor

.. Hard links to Leo's web site...
.. _ListManagerDocs.html: http://leoeditor.com/ListManagerDocs.html
.. _wxListManager.leo:    http://leoeditor.com/wxListManager.leo
</t>
<t tx="ekr.20050818163826.10">The rst3 command defines a code-block rST directive. The primary purpose of this
directive is to show formatted source code.

In rst mode you can insert the code-block directive like any other rST markup.

The rst3 command generates code-block directives automatically in code mode.

This directive takes one argument, a language name.  Like this::

    .. code-block:: Python

        import leo.core.leoPlugins as leoPlugins
        import leo.core.leoGlobals as g

The output looks like this::

    import leo.core.leoPlugins as leoPlugins
    import leo.core.leoGlobals as g

See `Scripting`_ for many examples of how to use code-blocks.
</t>
<t tx="ekr.20050818163826.11">HTML files generated by the rst3 command assume that three .css (cascading style
sheet) files exist in the same directory. For the HTML output to look good the
following .css files should exist:

- default.css is the default style sheet that docutils expects to exist.

- leo_rst.css contains some style improvements based on Gunnar Schwant's DocFactory.

.. - silver_city.css is the style sheet that controls the syntax highlighting generated by SilverCity.

The latter two style sheets are imported at the end of the default.css.

**Important:** You can use cascading style sheets to do things that otherwise
wouldn't be possible with "plain" rST. For instance, the background color of
this page was specified in a body style.
</t>
<t tx="ekr.20050818163826.13">The file `ListManagerDocs.html`_ is an impressive example of the kind of output
that can be generated relatively easily using the rst3 command.

The source for ListManagerDocs.html is `wxListManager.leo`_. **Important**:
wxListManager.leo was written for the old rst2 plugin; it could be greatly
simplified if adapted for the rst3 command.

This documentation was created using the rst3 command. The source code for this
documentation is in LeoDocs.leo. The source code for the rst3 command is in
leoRst.py in leoPy.leo.
</t>
<t tx="ekr.20050818163826.14">The code for the rst3 command is more complex than usual. Fortunately, the
overall organization is straightforward.

defaultOptionsDict
    This dictionary represents each rst3 option.
    To add another option, just add another entry to this dictionary.
    Keys are the option name, including the `rst3_` prefix.
    Values are the default value of the option.
    The hard-coded values in the dictionary may be changed as the result of @settings entries.

processTree
    processTree is the top-level code that handles one rst root node.
    It calls preprocessTree to create the **vnodeOptionDict** ivar.
    processTree then calls either writeNormalTree or writeSpecialTree
    depending on whether text will be sent to docutils for further processing.
    These two methods handle mundane details of opening and closing files.
    Both writeNormalTree and writeSpecialTree call **writeTree** to do the actual work.

vnodeOptionDict
    The entries in this dictionary represent the options that are set in one particular node.
    The keys of vnodeOptionDict are vnodes, the values are anonymous dictionaries.
    These anonymous inner dictionaries contain the options that are explicitly set at each vnode
    (and thus each position).
    Preprocessing the tree this way ensures that each node (headline and body text) is parsed exactly once.

writeTree
    writeTree first calls **scanAllOptions**, which has the effect of
    initializing all options. writeTree then calls **writeNode** for each node
    that will be processed by the rst3 command. Options may cause the rst3 command to
    skip a node or an entire subtree.

writeNode
    writeNode first calls **scanAllOptions** to compute the options that are in
    effect for that *single* node. Once options have been computed, processing the
    node is straightforward. writeNode calls writeBody and writeHeadline
    to do the real work. These methods generate or skip text based on various
    options.

scanAllOptions
    scanAllOptions recreates the optionsDict ivar to represent *all* the options
    in effect for *for the particular node being processed by writeNode*. Client
    code gets these options by calling the getOption method.

    scanAllOptions first inits all options from settings,
    then updates those options using the anonymous
    dictionaries contained in the vnodeOptionsDict.
    scanAllOptions works like g.scanAllDirectives, but the code is much simpler.
</t>
<t tx="ekr.20050818163826.16">Josef Dalcolmo wrote the initial rst plugin.
Timo Honkasalo, Bernhard Mulder, Paul Paterson, Kent Tenney and
Steve Zatz made contributions to the rst and rst2 plugins.
</t>
<t tx="ekr.20050818163826.4">The material covered so far in this chapter suffices to create most books
and documentation, including Leo's own documentation.

The rest of this chapter covers advanced topics. These can seem bewilderingly
complex. Alas, they are complex! However, they all arose from a single problem::

    How to generate documentation from computer source code in a Leo outline.

or equivalently::

    How to embed documentation in computer source code in a Leo outline.

This is an interesting problem, but it has little general interest. Please stop
reading now if this problem doesn't interest you!
</t>
<t tx="ekr.20050818163826.5">The following options are for the use of Bernhard Mulder's http plugin. The http
plugin creates an http server running on a local port, typically 8080. When the
http plugin is running you will see a purple message in the log window that
looks something like this::

    http serving enabled on port 8080, version 0.91

To use the http plugin, start a web browser and enter this url::

    http://localhost:8080/

You will see a a top level page containing one link for every open .leo file.
Clicking on a link will cause the http server to pass a new page to the browser.
You can use the browser's refresh button to update the top-level view in the
browser after you have opened or closed files.

**Important**: See the docstring for the http plugin for information on
configuring the plugin. Some of the following rst3 settings must match values of
settings for the http plugin.

Here are the rst3 options that support the http plugin:

.. glossary::

http_server_support (default: False)

    A master switch: none of the following options have any effect unless this
    option is True. If True, the rst3 command does the following:

    1. Writes **node markers** in the rst output for use by the http plugin.
       Node markers are rst named hyperlink targets. By default they look like::

            .. _http-node-marker-N

       where N is a unique node number.

    2. Adds additional information to all nodes of the tree being formatted using
       Leo's unknownAttributes mechanism.

http_attributename (default: 'rst_http_attribute')

    The name of the attribute name written to the unknownAttributes attribute of
    each outline node in the rst root tree. The default is
    'rst_http_attribute'; it should match the following setting of the http
    plugin::

        @string rst_http_attributename = 'rst_http_attribute'

clear_http_attributes (default: False)

    If True the rst3 command initially clears the fields specified by `http_attributename`.  

node_begin_marker (default: 'http-node-marker-')

    The string used for node markers.
</t>
<t tx="ekr.20050818163826.6">.. EKR: This kind of "flexibility" is a really bad idea.

The following options specify the 'spelling' of headline commands. The
option_prefix and option_prefixes command also define the spelling of special
doc parts.

You can change these to make them shorter or to avoid conflicts with headlines
in your Leo files. The list below merely gives the default value for each
setting.

`code_prefix`: '\@rst-code'

`ignore_headline_prefix`: '\@rst-no-head'

`ignore_headlines_prefix`: '\@rst-no-headlines'

`ignore_prefix_tree`: '\@rst-ignore'

`ignore_node_prefix`: '\@rst-ignore-node'

`ignore_tree_prefix`: '\@rst-ignore-tree'

`option_prefix`: '\@rst-option'

`options_prefix`: '\@rst-options'

`preformat_prefix`: '\@rst-preformat'

`rst_prefix`: '\@rst'

`show_headline_prefix`: '\@rst-head'
</t>
<t tx="ekr.20050818163826.7">Any headline that starts with @rst- controls the rst3 command.

.. glossary::
    :sorted:

..  @rst-code &lt;section&gt; 

    ..  Enter code mode. (Code mode is covered in the advanced topics sections)
    ..  Create a section if the show_headlines option is True.

@rst-ignore &lt;ignored-text&gt;

    Ignore the node and its descendants.

@rst-ignore-node &lt;ignored-text&gt;

    Ignore the node, but *not* its descendants.

@rst-ignore-tree &lt;ignored-text&gt;

    Same as \@rst-ignore.  Ignore the node and its descendants.

@rst-no-head &lt;ignored-text&gt;

    Ignore the headline but not the body text of this node.
    This has no effect on descendant nodes.

@rst-no-headlines &lt;ignored-text&gt;

    Ignore all headlines. (Set show_headlines=False)

@rst-option &lt;option&gt; = &lt;value&gt;

    Set a single option to the given value. The default value is True.

@rst-options &lt;ignored-text&gt;

    Set options from body text. The body text should contain nothing but
    lines of the form::

        &lt;option&gt;=&lt;value&gt;

@rst-preformat &lt;ignored-text&gt;

    Format the body text of the node as computer source code. In effect, this
    option adds a line containing '::' at the start of the body text. The option
    then indents all following lines.

    This option has no effect on descendant nodes.

..  @rst-rst

    ..  Enter rst mode. (Rst mode is the mode of operation discussed in the tutorial.)
    ..  Create a section if the show_headlines option is True.

</t>
<t tx="ekr.20050818163826.8">**Option doc parts** set rst3 options. Option doc parts start with \@
\@rst-options followed by lines of the form name=value. (Comment lines starting
with '..' are allowed.) For example::

    @ @rst-options
    .. This comment line is ignored.
    show_headlines=False
    show_leo_directives=False
    verbose=True
    @c

This is a real Leo doc part. Like all other doc parts an option doc part starts
with the \@ directive and continues until the end of body text or until the next
\@c directive.
</t>
<t tx="ekr.20050818163826.9">Settings in leoSettings.leo or myLeoSettings.leo specify the defaults
to be used for all rst3 options.  The form of these settings is::

    @bool rst3_&lt;option name&gt; = True/False
    @string rst3_&lt;option name&gt; = aString

That is, to create a default value for an rst3 setting, you must
prefix the option name with 'rst3\_'.  For example::

    @bool rst3_write_intermediate_file = True
</t>
<t tx="ekr.20050828160132">.. _front:                      index.html
.. _`Leo's tutorial`:           tutorial.html
.. _`Leo and reStructuredText`: rstplugin3.html
.. _`History of Leo`:           appendices.html#history-of-leo
.. was history.html
.. _`Using Chapters`:           outlines.html#using-chapters

.. For reasons unknown, images must appear in the _images folder on the web site.
.. .. |leoAtFileMainNode| image:: screen-shots/leo-qt-at-file-main-node.JPG
.. .. |leoAtFileFirstChild| image:: screen-shots/leo-qt-at-file-first-child.JPG
.. .. |leoAtFileNamedChild| image:: screen-shots/leo-qt-at-file-named-child.JPG
</t>
<t tx="ekr.20050830074815.1">"I am using Leo since a few weeks and I brim over with enthusiasm for it. I
think it is the most amazing software since the invention of the spreadsheet." -- Anon

"We who use Leo know that it is a breakthrough tool and a whole new way of
writing code." -- Joe Orr

"I am a huge fan of Leo. I think it's quite possibly the most revolutionary
programming tool I have ever used and it (along with the Python language) has
utterly changed my view of programming (indeed of writing) forever." -- Shakeeb
Alireza

"Thank you very much for Leo. I think my way of working with data will change
forever... I am certain [Leo] will be a revolution. The revolution is as
important as the change from sequential linear organization of a book into a
web-like hyperlinked pages. The main concept that impress me is that the source
listing isn't the main focus any more. You focus on the non-linear,
hierarchical, collapsible outline of the source code." -- Korakot Chaovavanich

"Leo is a quantum leap for me in terms of how many projects I can manage and how
much information I can find and organize and store in a useful way." -- Dan
Winkler

"Wow, wow, and wow...I finally understand how to use clones and I realized that
this is exactly how I want to organize my information. Multiple views on my
data, fully interlinkable just like my thoughts." -- Anon

"Edward... you've come up with perhaps the most powerful new concept in code
manipulation since VI and Emacs. -- David McNab

"Leo is...a revolutionary step in the right direction for programming." -- Brian
Takita
</t>
<t tx="ekr.20050830074815.10">"I am extremely impressed at how stable and useful Leo appears to be." -- Marcus
A. Martin

"Leo is amazingly stable. Docs are often weak with Open Source Software. Not so
Leo: Leo is unusually well documented." -- F. Geiger

"Leo is unimaginably useful and I always find new things it already knows(!) how
to do. Indeed I am amazed by the never-ending resources and patience Edward is
putting into it and its users community. Excellent." -- Gil Shwartz

I feel strongly that Ed Ream, our ever-patient, ever-productive Leo architect
deserves a nomination [for the ActiveState OpenSource Award.] Among other
reasons, for:

- Delivering the first usable visual literate programming tool.
- Adding a vast abundance of new features.
- Making possible a previously unimaginable amount of leverage in code editing.
- Eliminating vast amounts of menial programming labour.
- Tirelessly and patiently supporting users, and catering to a wide range of
  feature requests. -- David McNab

</t>
<t tx="ekr.20050830074815.11"></t>
<t tx="ekr.20050830074815.12">.. _`on slashdot`:http://slashdot.org/comments.pl?sid=38848&amp;cid=4171478

August 28, 2002 `on slashdot`_.

Hello, my full name is David Speed Ream. I am known as Speed to friends and
enemies alike, but I gladly answer to David or most any other handle. I am an
unabashed and biased fan of Leo, the fact that it was written by my brother
Edward only slightly coloring my already colored glasses. I have been testing
and using Leo in software production for over 4 years. My company currently has
over 50,000 lines of code in over 100 source files that are written using Leo.

My comments are from two points of view, the first being software project
manager for a complicated, multi-module software product, and the second being
as a production line coder. For me, Leo’s greatest and only real drawback is the
learning curve. This learning curve can be shallow is if all that is required is
that someone code using Leo. However, in our company we allocate 40 to 80 hours
*on top* of the normal coding load for someone to come up to speed on Leo. The
ROI (return on investment) is calculated by me to be on the order of 3 months.
So if I hire a consultant for less than 3 months, I don’t teach him Leo, even
though all source code in our company must reside in Leo files for the reasons I
won’t go into now.

I consider that my coders are 15 to 30 percent more efficient in their daily
operations than my competition’s people. This indefensible claim of mine is
based on the changes in my productivity as Leo grew from a test document
production tool to the primary production method for all our assembly, c and cpp
source code.

Personally, I hate to deal with documentation when I write code, except:

1) When I am first sitting down to solve a new problem.
   Then the documentation becomes quite long-winded and pontificatory,
   as if I were the only one on earth smart enough to solve the problem - or
2) When I come back to code I or someone else has written and find the documentation insufficient to
   understand the code without study (seems to be most of the time).

So I do not require my engineers or myself to do a great job of documentation,
nor do I use Leo for that purpose. Rather, it is Leo’s outlining and organizing
ability, and Leo’s ability to create source files from within the outline that
give me what I think is a tremendous competitive advantage. Each of my company’s
products run on all versions of windows from Win 3.1 to XP. In our flagship
software piece, there are ten main modules, and each module is maintained by one
single Leo file. In the CODEC module, one Leo file named compress.leo organizes
and creates seven .asm files, forty-four .c files, twenty .h files, two .def
files, four .mak files, etc. etc. etc. This one file can be checked out from
source code control and given to an engineer for the addition of a new feature.

In it are contained all the known issues for the CODEC, each issue arranged in
its own clone section. One clone section groups together every routine, variable
or type definition that must change between different versions of Windows. These
sections could be from six different c source files, two assembly files, and
eight .h files. Another clone section groups together those sections relating to
memory problems, which change according to the memory configuration and TSR
configuration (or lack thereof) on the target machine. Another clone section
groups sections that fail (or don’t fail) if the routine in question was
accidentally run during the dreaded ‘interrupt time’. Another clone section is a
section containing clones, each of which is named after the major bug that was
fixed when the engineer who fixed the bug grouped a bunch of routines,
definitions, etc. together to fix the bug.

None of the above clone sections was ‘designed’ into the document. Just the
opposite happens. When the codec was first written, there was just a single Leo
file with a bunch of sections for each c routine or assembly module. As the
product grew and was tested on various platforms, each failure of the module was
organized into clones each time a failure was fixed. This is what I call “SELF
DOCUMENTING CODE”. This has nothing to do with me sitting and documenting
anything. Its just that the STRUCTURE of a bug fix (or product enhancement)
lives on long after the coding is done, as long as no one is foolish enough to
delete the cloned sections that ‘DOCUMENT’ what happened.

In actual practice, this organizational ‘history’ is so powerful that I can’t
begin to describe it. A ‘REVERSE LEARNING CURVE’ happens when an engineer gets a
Leo file that already has the ‘interrupt time sensitive’ routines grouped
together by the last unfortunate soul who had to work on them. There may not be
any more written documentation, but the knowledge contained in the structure can
be breathtaking. It is certainly time saving. I find this particularly true in
my own case. Often I’ll look at some code that seems totally unfamiliar and
think ‘what idiot wrote this crap’. Then I’ll look at the version control
comments and realize that I wrote the crap. Then for sure I know the
documentation is non-existent, but the clones I used to develop it are still
there, and they always serve to refresh my memory in an indescribable way.

Enough of this commentary, I just looked at the clock. Best wishes to anyone
willing to try Leo for a week. I hope you will be glad you did.
</t>
<t tx="ekr.20050830074815.13">_circa 2005_

The Word outlines are very useful. But Leo makes Word look like a clunky toy.

#1 Reason would probably be clone nodes. One node can point to another. Another
way of putting this is is that a leaf can be on more than one tree. For
example, suppose you have a list of recipes. You simultaneously put a single
recipe under multiple categories or even multiple hierarchies. You could put "3
bean enchilada" simultaneously under Recipes-Mexican and Food-Gas. Another
example would be, if you are a biologist trying to decide under which genus to
put a new species, you could put the species under two simultaneously. In
effect, you can build a 3-D tree. For a further illustration see
http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htm
(domain shut down, perhaps try the `Web Archive`_)

#2 Reason would probably be that Leo outlines can be embedded in external text
files. So, a Leo outline is more than an outline, it is a meta-structure that
can be added to another text without changing that text, but rather providing
an external road map to the text. Microsoft Word has a text (xml) version with a
commenting convention, so Leo can even be used to add outlines into Word docs,
although it isn't set up to do that now. For example, see
http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htm In this case, the upper
window of Leo is the meta-structure, and the bottom window is the file to which
the meta-structure is being applied, viewed one node at a time.

I may not have made #2 very clear, but it is actually a very useful feature. It
takes some getting used to before one sees all of the possibilities tho. One
way to think of it is that Leo allows you to throw external documents into your
outline, and yet the external document remains independent and can still be
edited separately.

Some other cool things about Leo which Word doesn't feature:
1. Pure xml output that is easy to transform into other formats (next
version of Word will have true XML format, but not as easy to work with).
One consequence of this is that Leo files can be transformed pretty easily
to web pages with their outlining capability intact.
2. Easy to add features since is programmed in Python and open source. Maybe
your average user can't start hacking on it, but a surprising amount can be
tacked on...
.. by flipping through the Tk manual.
3. Free, opensource, multi-platform
4. Leo is scriptable with Python. It should be possible to build a Tickler
into Leo using Python scripting, for example.

.. _`Web Archive`:http://web.archive.org/web/http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htm
</t>
<t tx="ekr.20050830074815.14">First of all, kudos to you for the excellent progress you've been making with
Leo. I upgraded today after about three months of using and older version and I
was thrilled to see all the great improvements that have happened so fast. I
especially love the ability to go to next clone. I think you're really showing
what open source can do and your current trajectory puts you on track to kick
Emacs into the dustbin of computing history.

So today I copied all my data (personal information manager and project
management stuff) out of my old outliner (ThoughtManager, which syncs with and
runs on the Palm) and put it into Leo. It took me hours to do it and then to
rearrange it the way I really wanted it. But having the ability to make clones
and have different ways to view my data is, as you know, fabulous. In my case,
for personal information and project management things, I used the flexibility
of clones to allow me to see my data in several different views: 1) by project,
the logical hierarchical breakdown by topic, 2) by person, so whenever I'm
talking to someone I can easily see all the pending items related to them which
may be spread over multiple projects, 3) by priority, so I can see what needs to
get done sooner and what can wait for later and, 4) a special case of priority
called "Today" for the things I'm going to focus on in the coming hours.

Now here's why I don't miss the ability of my old outliner to synch the entire
outline with the Palm. It turns out the main thing I really want in the Palm is
the top category "Today" so all I have to do is have Leo flatten that one
heading into a text file (and it kindly remembers the name and directory of the
file I used last time) and then I'm done because I've told the Palm Hotsync
manager that that file should be sent to Palm memo pad every time I synch. The
Palm Hotsync manager does a nice job of sending a text file to the Palm memo pad
and even breaks the file up into multiple memo records if it's too big to fit in
just one. So that gives me enough to be able to browse (or full text search) the
small amount of data that I really want right inside my Palm (which is also my
cell phone). Quick and dirty but it works.

For times when I want my whole outline with me, Leo wins again because thanks to
its cross platform nature I can take my whole outline with me on my Mac iBook,
even though I usually edit it on a Windows PC (which is the only kind of machine
my old outliner would run on). Quite frankly, although my old outliner was able
to shoehorn the whole thing into my palm/cellphone, it was a pain to access it
on the small screen and slow processor. Now when I anticipate I'll need the
whole thing, for example when I'm going to a meeting, I can put it on my Mac
iBook (under X and Fink for now until Python can do it native under Aqua) and
have real, full access to it all.

I think now in addition to being great for programming Leo is also a great PIM.
Being able to flatten a strategically chosen portion of the outline into a known
file name that the Palm synch manager has been told to send to the Palm on every
synch does the trick for me. I wonder if you would consider something like an
@flatten directive so I can have that done automatically for me every time I
save my outline? For now it's up to me to flatten the node I want manually,
although once I've done that the transfer to the Palm is automatic.

You're my hero! Thank you so much.
</t>
<t tx="ekr.20050830074815.15">Another day, another breakthrough using Leo -- now I realize Leo is the 
best URL bookmark manager there is.  No more bookmarks menus or 
favorites lists inside the browser for me.  With the @url directive I 
can just double click on the URL to open it in my browser.  Leo lets me 
arrange the URLs in a hierarchy (or multiple hierarchies), attach notes 
to them, save clippings of things I read on the sites.  It's sooo much 
better than anything the browsers have built in and it lets me easily 
use different browsers on different platforms and different machines 
(try that with the browsers' built-in bookmark managers).  

When using Leo as a project manager and personal information manager as 
I do I can heavily annotate every task and project with helpful and 
relevant URLs.  And since URLs can be of the file:// form, they're not 
just for web pages or HTML documents;  I can link to any file on my disk 
of any type to be opened by any program.

Leo is a quantum leap for me in terms of how many projects I can manage 
and how much information I can find and organize and store in a useful 
way.  I'm a data-mining army of one now and the web is my playground. 
Every time I find a web page that has interesting links to others, 
those links get stored in my Leo outline too, right where I can find 
them and make practical use of them.  I can easily accept dozens of 
valuable links every day and integrate them into what I'm doing in a way 
that I'm confidant they won't get lost or forgotten.  Before I always 
used to get bogged down by the difficulty of managing bookmarks inside 
the browser.  But now I'm no longer the victim of information overload 
buried in the knowledge landslide of the Internet;  instead I'm the 
professional strip miner with the world's biggest bulldozer.  I eagerly 
plunge into mountains of data and emerge with all the valuable 
information nuggets neatly stored and organized.  And my storehouse of 
knowledge is a flexible thing where I can reorganize and prioritize and 
massage the data to my heart's content as I learn more about it and 
decide to use it in different ways for different purposes.  It's the 
difference between the pick axe and the steam shovel for me.
</t>
<t tx="ekr.20050830074815.16">This year my accountant is getting a beautiful printout generated by LaTeX and
Leo. I have a complicated tax situation this year, but I got it all laid out and
organized in Leo. Then I had each of the nodes that had something my accountant
needs to see write the data out to a file in the form a LaTeX table.

Sometimes a row of a table would have a result that was calculated by adding up
a list of numbers. For that I used the modern day equivalent of an adding
machine paper tape -- I stored a lisp s-expression in a Leo comment. I like
s-expressions for this because once I put the opening "(+" on one line and the
closing ")" on another line, I can fill in additional numbers just by typing
them and can even annotate them with comments. So in the middle of generating a
LaTeX file I might have something like this::

    @
    (+
    1165.26 1823.70 ; May 2002
    123.38 ; June 2002
    13.50 ; July 2002
    13.21 ; October 2002
    55.25 ; November 2002
    )
    @c

That's an annotated record of how I arrived at the number the accountant will
actually see. I can just paste it into any lisp or scheme interpreter and get
the total. Adding additional numbers is easy.

For next year, I think I might take this a step further. What I did this year is
good for adding up numbers to get a total for one row of a LaTeX table. But it
turns out I'd also like some more processing done on those tables (which I had
to do by hand this time) -- I'd like the rows sorted in reverse order by
magnitude (so that the big numbers jump out at you from the start of the tables)
and I'd like a total of all the rows in the table. So I think next year, instead
of having an s-expression that computes the total of one row for me, I think
I'll use s-expressions that generate whole tables, formatted for LaTex, from the
underlying data. So I'm thinking next year my s-expressions might look more like
this::

    @
    (table "Widget Related Expenses"
        ("widget insurance" (+
                        1165.26 1823.70 ; May 2002
                        123.38 ; June 2002
                        13.50 ; July 2002
                        13.21 ; October 2002
                        55.25 ; November 2002
                      ))
         ("widget shipping" (+
                        472.15 651.94 ; May 2002
                        54 ; June 2002
                       ))
         ("widget cleaning" (+
                        165.26 183.70 ; May 2002
                        123.38 ; June 2002
                        13.50 ; July 2002
                        13.21 ; October 2002
                        55.25 ; November 2002
                       ))
    )
    @c

The job of that "table" function would be to return the LaTeX code needed to
display a table with the category names and values, sorted descending by
magnitude, with the total displayed. It's sort of a poor man's way of doing a
spreadsheet inside Leo and then making it look great using LaTeX. The idea would
be as I wanted to add more data, I'd add it to the s-expression and then
reevaluate the whole thing by pasting it into a lisp interpreter and then
copying the result back into the same Leo node for LaTeX to process.

-- Dan
</t>
<t tx="ekr.20050830074815.2">"Thanks for a wonderful program – everybody should be using it! It blows the
socks off that Java Mind mapping software that won project of the month a while
back on sourceforge!" -- Derick van Niekerk.

"A few years back I would have said Zope was #1 Python showcase, but I agree
100% that Leo is tops now." -- Jason Cunliffe

"Leo is the most interesting Python project I know of...I see lots of stuff
posted on the Daily Python page, but I usually yawn and come over to this forum
to see what's cooking." -- Anon

..  "Leo is the best Tkinter application ever written. It convinces me that Tkinter
..  can really *do something*, and do [it] well." - Anon

"What an original synthesis of different ideas, why can't other Open Source
projects change the way I think?" -- Anon
</t>
<t tx="ekr.20050830074815.3">"When first I opened Leo, it was out of curiosity. But having used it...I'll
never go back. They'll have to pry Leo out of my cold, dead fingers! Seriously,
it should be renamed 'Crack Cocaine' because it's that addictive. I'm ready to
start a 12-Step group." -- Travers A. Hough

"I feel addicted to programming again...in fact [Leo] has resurrected a dead
project of mine :) The Outline has proven most liberating in terms of testing
ideas out." -- Anon

"I have been absolutely seduced by Leo over the past few days. I tell you, I can
not put it down. I feel like a kid with a shiny new bike...I'm already bursting
with new ways I'd like to use the tool in the future." -- Lyn Adams Headley

Thanks for the great work--I love Leo!!! -- Josef Dalcolmo

Leo has simplified updating and creating new scripts and .bats keeping similar
information in the same place. there is almost an addictive withdrawal effect
when I can complete an operation in so much less time with Leo &amp; python than I
had become used to. -- Anon
</t>
<t tx="ekr.20050830074815.4">"[Leo] should either replace or greatly augment the development tools that I
use." -- Zak Greant

"Leo is a marriage of outlining and programming. Pure genius. The main reason I
am impressed with this tool is that it doesn't affect your choice of tools. You
can use whatever IDE for whatever language and switch back and forth between Leo
and it." -- Austin King

"Leo is the best IDE that I have had the pleasure to use. I have been using it
now for about 2--3 months. It has totally changed not only the way that I
program, but also the way that I store and organize all of the information that
I need for the job that I do." -- Ian Mulvany

"I only have one week of Leo experience but I already know it will be my default
IDE/project manager...people complain about the lack of a project manager for
the free/standard Python IDE's like Idle. Leo clearly solves that problem and in
a way that commercial tools can't touch." -- Marshall Parsons

"I have been using Leo for about 3 weeks and I hardly use my other programming
editor anymore...I find it easy and enjoyable to use. I plan to adopt it as my
presentation tool for code reviews." -- Jim Vickroy

"I'm absolutely astounded by the power of such a simple idea! It works great and
I can immediately see the benefits of using Leo in place of the standard flat
file editor." -- Tom Lee

I think you're really showing what open source can do and your current
trajectory puts you on track to kick Emacs into the dustbin of computing
history. -- Dan Winkler
</t>
<t tx="ekr.20050830074815.5">"Word outlines are very useful. But Leo makes Word look like a clunky toy."
--Joe Orr

"Leo is an interactive editor for organizing text fragments hierarchically and
sequentially into one or more files and hierarchical folders, without arbitrary
limits on the number and size of text fragments and the depth of the
hierarchy...Leo is a tool for combining hierarchically and sequentially
organized text fragments into text files, hierarchically grouped into folders,
with hierarchical or sequential organization of text within the files, and
without arbitrary limits on the size and number of files and the depth of the
hierarchy of folders and text nesting within the files." -- Alex Abacus

"Leo reminds me a great deal of things I loved when I used Userland's Frontier
(an outlining cms with a native oodb) - but Frontier wasn't hackable enough for
me, and it wasn't oriented towards coding..., and you couldn't round-trip
rendered pages (big Leo win). This is really a super tool - in a matter of days
I've started to use it on all my projects and I still haven't figured out how I
lived without it." -- John Sequeira

"Leo is EXACTLY the kind of outliner I was looking for--fantastic job!"
-- Steve Allen

"If you are like me, you have a kind of knowledge base with infos gathered over
time. And you have projects, where you use some of those infos. Now, with
conventional outliners you begin to double these infos, because you want to have
the infos needed for the project with your project. With Leo you can do this
too, but if you change text in one place IT IS UPDATED IN THE OTHER PLACE TOO!
This is a feature I did not see with any other outliner (and I tried a few).
Amazing! Leo directly supports the way I work!" -- F. Geiger
</t>
<t tx="ekr.20050830074815.6">"Another day, another breakthrough using Leo--now I realize Leo is the best URL
bookmark manager there is. No more bookmarks menus or favorites lists inside the
browser for me. With the @url directive I can just double click on the URL to
open it in my browser. Leo lets me arrange the URLs in a hierarchy (or multiple
hierarchies), attach notes to them, save clippings of things I read on the
sites. It's sooo much better than anything the browsers have built in and it
lets me easily use different browsers on different platforms and different
machines (try that with the browsers' built-in bookmark managers)." -- Dan
Winkler

"I am an amateur photographer. I use plain old 35mm. film for my pictures. Over
the weekend, I used Leo to organize my lists of pictures. It is quite helpful--I
can have separate nodes for pictures I have enlarged, as well as pictures I have
submitted to our local camera club. Thanks!" -- Rich Reis

"Cloning is pure genius!... Leo's cloning facility, allows me to create several
views on the CFA course material. My main view follows the prescribed study
guide. Another view is organized like the textbooks. Yet another gives me a
glossary of terms. And when I'm done, I'll have some nice libraries...I can
re-use later in other projects." -- Michael Manti
</t>
<t tx="ekr.20050830074815.8">"I've written documentation in WordPerfert, Ventura, Word, PageMaker, and
FrameMaker and even though they create wonderfully looking and useful documents,
they've never been able to do what I've been looking for. HTML, compiled help
files, and later PDF came closer, but still not there...I think I've found it in
LEO, a way to make a "living" document. A document built out of discrete parts
that can be re-organized on the fly to meet the needs of a varying
audience...I've already started converting the IT Procedures manual from Open
Office to LEO because I know it's going to be much more useful to me and anyone
else...just the possibility of keeping system maintenance scripts in the IT
manual is mind boggling." -- David Nichols

"With the help of the rst2 plugin, [Leo is] the best outliner I have yet
encountered for writing the early stages of academic papers."

"A Leo file is an ideal documentation tool, collecting the assorted readme.txt
files, the comments from the source files...as well as the config files
themselves." -- Kent Tenney
</t>
<t tx="ekr.20050830074815.9">"Just as structured programming reveals and disciplines the flow control of a
program, [Leo] allows the designer to reveal and discipline structure at many
layers simultaneously: data structures, object structure, entity-relationship
structure, client-server structure, design pattern structure, temporal
structure, project management structure, and any other structure relevant to the
system." -- Steven P. Schaefer

"A funny observation with Leo is that when I 'Leo-ise' other people's code, Leo
makes the code's structure so transparent that design faults become very quickly
apparent. For example, maintenance pain caused by lack of factorization." --
David McNab

"Leo is a powerful tool for organizing text into tree structures, and for just
generally attacking a number of problems from a tree-based perspective." -- Joe
Orr

"I found this blog entry by someone (a talented former coworker of mine
actually) complaining about some poorly written code she had to maintain:
http://snippy.ceejbot.com/wiki/show/start/2003/01/29/001 She said: 'You'd need a
bulldozer to start refactoring it.' That was my cue to write a long message
explaining that there is indeed such a bulldozer and it's called Leo. (You can
see my message there as a reply to her original posting.) I gave her my recipe
for how to get someone else's messy, scary code into Leo and how to break it
down into manageable chunks." -- Dan Winkler

"Ed, you continue to push the envelope. The amazing thing is that the footprint
isn't doubling every few months like it would be in another designer's hands.
Adding features by removing constraints, hot refactoring while adding unit
tests. Forget the book. I would pay to see the movie."
</t>
<t tx="ekr.20050830115714">####
FAQ
####

This is Leo's Frequently Asked Questions document.

.. index:: FAQ

.. contents::
    :depth: 3
</t>
<t tx="ekr.20050830115714.1"></t>
<t tx="ekr.20050830115714.10">The encoding used in the file being imported doesn't match the encoding in effect for Leo.
You have two options:

- Use the @encoding directive_ in an ancestor of the node_ selected when
  doing the Import command_ to specify the encoding of file to be imported.
</t>
<t tx="ekr.20050830115714.113">**Question**:
It would be nice if Leo could open empty files. I tend to be "document oriented"
rather than "application oriented" in my thinking and prefer "create empty file
at location -&gt; open it with program" to "start program -&gt; create new file -&gt;
save it at location".

**Answer** by Paul Paterson:
If you are on Windows 98/2000/XP then the procedure is as follows...

1. Start Leo
2. Click New
3. Click Save as...
4. Save the file as "c:\\windows\\shellnew\\leofile.leo" (or c:\\winnt for 2000/XP)
5. Open regedit "start...run...regedit"
6. Open HKEY_CLASSES_ROOT and find the ".leo" extension type
7. Go New ... Key from the context menu 
8. Call the new key ShellNew 
9. Select the new key, right-click, choose New...String Value from the context menu
10. Call it FileName 
11. Double-click on the string, and modify it to be the filename of the leofile.leo file you created,
    including the extension
12. Exit the registry editor and restart Windows Explorer (you may need to reboot on Windows 98)

Now you should have a New:Leo File option in Explorer. This creates a duplicate
of the file you saved. This can be useful because you could make a template Leo
file containing some standard nodes_ that you always have and then save this.
</t>
<t tx="ekr.20050830115714.115" str_atime="1376412852.0">For the most part, docutils_ does a good job of reporting errors. docutils_ prints
a message to the console and inserts an unmistakable error message in the
generated .html file.
**Important**: On Windows it is helpful to `run Leo in a console window`_.

However, in some cases, docutils_ crashes instead of properly reporting the
problem. There are several workarounds:

1.  The crashes I have seen arise from the following bug in docutils.
    **Hyperlinks in image:: markup must be lower case**.  This will work::

        .. .. |back| image:: arrow_lt.gif
            :target: faq_

    This will **crash**::

        .. .. |back| image:: arrow_lt.gif
            :target: FAQ_

    So avoid this crash by making sure to use lower case targets in ':target:' markup.

2.  You can change the docutils_ source slightly so that it prints a traceback when it
    crashes. (The rst3 plugin should be able to do this, but I haven't figured
    out how yet.) It's easy enough to do this:

    - Find the file core.py in top-level docutils folder.
      Typically this folder will be in Python's site-packages folder.

    - Open core.py in some editor other than Leo.

    - Find the method called report_Exceptions.

    - Insert the following lines at the very start of this method::

        print 'EKR: added traceback'
        import traceback ; traceback.print_exc()

    This will cause a traceback whenever docutils_ crashes. I have found that
    such tracebacks are generally enough to locate the general area of the
    problem. **Note**: These tracebacks go to the console window, so you should
    `run Leo in a console window`_.

3.  As a last resort, you can isolate syntax errors by reducing your input files
    until they work again, then adding sections until you get a crash. This is
    easy enough to do (when using the rst3 plugin) by change a headline 'x' to
    @rst-ignore-tree x.
</t>
<t tx="ekr.20050830115714.116">From: http://sourceforge.net/forum/message.php?msg_id=3240374
Using Leo's File-Export-Flatten Outline commands creates a MORE style outline which places
all Leo body sections on the left margin.
The headlines_ are indented with tabs which Excel will read as a tab delimited format.
Once inside Excel there are benefits.

1.  The most obvious benefit inside Excel is that the body sections (Excel first
    column) can be selected easily and highlighted with a different font color.
    This makes the MORE format very readable. Save a copy of your sheet as HTML
    and now you have a web page with the body sections highlighted.

2.  It is possible to hide columns in Excel.
    Hiding the first column leaves just the headlines showing.

3.  Formulas based on searching for a string can do calculations in Excel.
    For example if a heading "Current Assets" appears on level 4 then the body formula::

        =INDEX(A:A,MATCH("Current Assets",D:D,0)+1)

    will retrieve it. The +1 after match looks down one row below the matched
    headline. The trick is to place all your headlines in quotes because Excel
    will see + "Current Assets" from the MORE outline. When Excel tries
    without the quotes it thinks it is a range name and displays a #N/A
    error instead of the headline. Also you must place a child node_ below to
    get the + sign instead of a - sign which would give a MORE headline of
    -"Current assets" , also is an error.

I think there is some interesting possibility here because of the enforcement of
Leo body text being always in the first column. The Leo outline provides
additional reference to organizing the problem not typical of spreadsheet
models. Beyond scripting in Python, Excel is good at doing interrelated
calculations and detecting problems like circular references. In Excel
Tools-Options-General is a setting for r1c1 format which then shows numbers
instead of letters for column references. Using this would allow entries like
this in the leo body::

    1000
    3500
    =R[-1]C+R[-2]C

In Excel you would see 4500 below those two numbers. This is completely
independent of where the block of three cells exists on the sheet.
</t>
<t tx="ekr.20050830115714.117">Python's decorator_ syntax is ill-conceived.
This syntax file hack works well enough anyway to work with Leo '@' markup::

    syn region leoComment start="^@\\s*" end="^@c\\s*$"
    syn match   pythonDecorator	"@\\S\\S+" display nextgroup=pythonFunction skipwhite
</t>
<t tx="ekr.20050830115714.118"></t>
<t tx="ekr.20050830115714.119">By Rich Ries.
I often rework C code that's already been "Leo-ized"--the first pass was quick
and dirty to get it going. When I do subsequent passes, I wind up with subnodes
that are out of order with the sequence found in the main node_. It's not a big
deal, but I like 'em ordered. With just one editor pane, clicking on the node_ to
move would switch focus to that node_. I'd then need to re-focus on the main
node_. A minor nuisance, but it does slow you down.

My solution is to open a second editor with its focus on the main node_. Switch
to the other editor, and, referring to the first editor pane, move the nodes as
you like. The second editor's pane will change focus to the node_ you're moving,
but the first editor will stay focused on the main node_. It's a lot easier to
do than to describe!
</t>
<t tx="ekr.20050830115714.12">Using @file trees can eliminate most problems with using Leo in cooperative
(SCCS) environments:

- Developers should use @file trees to create external files in any kind of
  cooperative environment.

- If sentinels are frowned upon in your development community, use @auto or
  @shadow instead of @file.

- The repository contains **reference** .leo files. These reference files should
  contain nothing but @file nodes. Reference files should change only when
  new external files get added to the project. Leo's `bzr repository`_ and Leo
  distributions contain the following reference files: LeoPyRef.leo,
  LeoPluginsRef.leo and leoGuiPluginsRef.leo. Developers should use
  local copies of reference files for their own work. For example, instead of
  using LeoPyRef.leo directly, I use a copy called LeoPy.leo.
</t>
<t tx="ekr.20050830115714.120">One way is to link directly to the media file from a Leo node_ (with @url) and
write a script button to wrap all URL-nodes under the current node_ in a single
HTML page. Then, you can view your media in two ways:

-   Individually. You can directly click on the @url link to display the media
    in the browser (assuming you have your MIME/filetype associations set up
    correctly for your browser).

-   In a group. You can click on a script button (you have to code this yourself,
    very simple) which should collect all @url nodes_ under the current node_
    and dynamically generate a HTML page displaying either links to or embedded
    versions of the media (using the HTML trick described above to invoke the
    browser). This way, you can create collections of @url nodes under a
    single node_ (like a bookmark folder), and press a single button to view the
    @url collection as a single entity in the browser (with all browser
    capabilities like displaying the media).

You could probably generalize this idea of "collect all @url nodes under current
node_ and display as HTML in browser" into a general-purpose plugin. However,
the plugin would have to be somewhat smart in mapping a link to its corresponding
HTML code (e.g. an image link gets mapped to an &lt;img&gt; HTML tag, a link to a
Flash file gets mapped to an &lt;embed&gt; tag, etc).
</t>
<t tx="ekr.20050830115714.13"></t>
<t tx="ekr.20050830115714.14">You have two options, depending on whether you want to be able to use sections
or not.

-   Use @nosent trees.
    Files derived from @nosent trees contain no sentinels_.
    However, Leo create the external file just as in @file trees.
    In particular, Leo expands section references and understands the @others directive.

-   Use @asis trees.
    Files derived from @asis trees contain no sentinels_.
    Moreover, Leo does not expand section references in asis trees.
    In other words, Leo creates the `external file` simply by writing all body text in outline order.
    Leo can't update the outline unless the external file contains sentinels,
    so Leo does not update @nosent trees or @asis trees automatically when
    you change the external file in an external editor.
</t>
<t tx="ekr.20050830115714.16">Use @asis trees. Files derived from @asis trees contain no sentinels. Leo
creates the external file simply by writing all body text in outline order. Leo
can't update the outline unless the external file contains sentinels, so Leo
does not update @asis trees automatically when you change the external file in
an external editor.
</t>
<t tx="ekr.20050830115714.17">The import commands insert @ignore directives_ in the top-level node_.
Leo does this so that you won't accidentally overwrite your files after importing them.
Change the filename following @file (or @file) as desired,
then remove the @ignore directive_.
Saving the outline will then create the external file.
</t>
<t tx="ekr.20050830115714.18">**Question**: I'm writing a Windows Script Component, which is an XML file with
a CData section containing javascript. I can get the XML as I want it by using
\@language html, but how can I get the tangling comments inside the CData
section to be java-style comments rather than html ones?

**Answer**: In @file trees you use the @delims directive to change comment delimiters.
For example::

    @delims /* */ 
    Javascript stuff 
    @delims &lt;-- --&gt; 
    HTML stuff

**Important**: Leo can not revert to previous delimiters automatically;
you must change back to previous delimiters using another @delims directive_.
</t>
<t tx="ekr.20050830115714.19">By Zvi Boshernitzan: I was having trouble disabling '&lt;?php' with comments (and
couldn't override the comment character for the start of the page). Finally, I
found a solution that worked, using php's heredoc string syntax::

    @first &lt;?php
    @first $comment = &lt;&lt;&lt;EOD
    EOD;

    // php code goes here.
    echo "boogie";

    $comment2 = &lt;&lt;&lt;EOD
    @last EOD;
    @last ?&gt;

or::

    @first &lt;?php
    @first /*
    */

    echo "hi";

    @delims /* */
    @last ?&gt;
</t>
<t tx="ekr.20050830115714.2">First, read the tutorial_. This will be enough to get you started if you just
want to use Leo as an outliner_. If you intend to use Leo for programming, read
the `tutorial about programming`_, then look at Leo's source code in the file LeoPy.leo.
Spend 5 or 10 minutes browsing through the outline. Don't worry about details;
just look for the following common usage patterns:

-   The (Projects) tree shows how to use clones to represent tasks.

-   Study @file leoNodes.py.
    It shows how to define more than one class in single file.

-   Most other files show how to use a single @others directive to define one class.

-   Most methods are defined using @others, *not* section definition nodes.
</t>
<t tx="ekr.20050830115714.20">Here is a posting which might be helpful:
http://sourceforge.net/forum/message.php?msg_id=2300457 The @first
directive_ is the key to output usable code in unsupported languages. For
example, to use Leo with the Basic language, use the following::

    @first $IFDEF LEOHEADER
    @delims '
    @c
    $ENDIF

So this would enable a basic compiler to "jump" over the "true" LEO-header-lines.
Like this::

    $IFDEF LEOHEADER &lt;-conditional compilation directive 
    #@+leo-ver=4 &lt;-these lines not compiled
    #@+node:@file QParser005.INC
    #@@first
    #@delims ' 
    '@@c
    $ENDIF &lt;-... Until here!
    &lt;rest of derived code file ... &gt;

This changes the comment symbol the apostrophe,
making comments parseable by a BASIC (or other language.)
</t>
<t tx="ekr.20050830115714.21">Use the @first directive_ in @file trees or @nosent trees.

The @first directive puts lines at the very start of files derived from @file.
For example, the body text of @file spam.py might be::

    @first #! /usr/bin/env python

The body text of @file foo.pl might be::

    @first #/usr/bin/perl

Leo recognizes the @first directive_ only at the start of the body text of @file nodes.
No text may precede @first directives_.
More than one @first directive may exist, like this::

    @first #! /usr/bin/env python
    @first # more comments.
</t>
<t tx="ekr.20050830115714.24">No. Everything in an @file trees must be part of the external file: orphan and
\@ignore nodes are invalid in @file trees. This restriction should not be
troublesome. For example, you can organize your outline like this::

    + myClass
    ..+ ignored stuff
    ..+ @file myClass

(As usual, + denotes a headline.) So you simply create a new node_, called
myClass, that holds your @file trees and stuff you don't want in the @file
trees.
</t>
<t tx="ekr.20050830115714.25">By Rich Ries.
Some older C compilers don't understand the "//" comment symbol, so using @language C won't work.
Moreover, the following does not always work either::

    @comment /* */

This generates the following sentinel line::

    /*@@comment /* */*/

in the output file, and not all C compilers allow nested comments, so the last \*\/ generates an error.
The solution is to use::

    #if 0
    @comment /* */
    #endif

Leo is happy: it recognizes the @comment directive_.
The C compiler is happy: the C preprocessor strips out the offending line before the C
compiler gets it.
</t>
<t tx="ekr.20050830115714.26" str_atime="1376412984.0"></t>
<t tx="ekr.20050830115714.29">See the instructions are in LeoPy.leo in::

    Notes:How To:How to add support for a new language section.

This section contains clones of all relevant parts of Leo that you will change.
Coming in Leo 4.4: Leo will use JEdit's language description files to drive the
syntax colorer. To add support for a new language, just add another such
description file.
</t>
<t tx="ekr.20050830115714.30" str_atime="1376412828.0">You have two options: 

-   Get cvs write access, and add the @file file to the plugins directory.

-   Just send the @file file to me at edreamleo@gmail.com.
    That's all you need to do.  In particular that there is no need to change leoPlugins.leo.
</t>
<t tx="ekr.20050830115714.4">You will lose much of Leo's power if you don't use clones.
See `Clones`_ and `Views`_ for full details.
</t>
<t tx="ekr.20050830115714.7">Use methods for any code that is used (called or referenced) more than once.

Sections_ are convenient in the following circumstances:

-   When you want to refer to snippets of code the can not be turned into methods.
    For example, many plugins start with the code like this::

    &lt;&lt; docstring &gt;&gt;
    &lt;&lt; imports &gt;&gt;
    &lt;&lt; version history &gt;&gt;
    &lt;&lt; globals &gt;&gt;

    None of these sections could be replaced by methods.

-   When you want to refer to a snippet of code that shares local variables with the enclosing code.
    This is surprisingly easy and safe to do, *provided* the section is used only in one place.
    `Section names`_ in such contexts can be clearer than method names.  For example::

    &lt;&lt; init ivars for writing &gt;&gt;

In short, I create sections when convenient,
and convert them to functions or methods if they need to be used in several places.
</t>
<t tx="ekr.20050830115714.74">The Import Files dialog allows you to select multiple files provided you are running Python 2.3 or above.
There is also an importFiles script in LeoPy.leo.  You can use that script as follows::

    import leo.core.leoImport as leoImport
    leoImport.importFiles(aDirectory, ".py")

This will import all .py files from aDirectory, which should be a full path to a particular directory.
You could use ".c" to import all .c files, etc.
</t>
<t tx="ekr.20050830115714.76" str_atime="1376412985.0"></t>
<t tx="ekr.20050830115714.77">Just `run Leo in a console window`_. At the point you want to drop into the
debugger, execute this line::

    g.pdb()

All output from pdb goes to stdout, which is the console window. It would be
good to create a subclass of pdb.Pdb that uses Leo's log pane rather than a
console window, but I haven't done that. It could be done easily enough in a
plugin...

**Important**: I recommend using g.trace instead of pdb.  For example::

    g.trace(x)

prints the name of the function or method containing the trace, and the value of
x. g.callers is often useful in combination with g.trace. g.callers(5)
returns the last 5 entries of the call stack. For example::

    g.trace(x,g.callers(5))

Used this way, g.trace shows you patterns that will be invisible using pdb.
</t>
<t tx="ekr.20050830115714.9">Internally, Leo represents all strings as unicode. Leo translates from a
particular encoding to Unicode_ when reading .leo files or external files. Leo
translates from Unicode_ to a particular encoding when writing external files.
You may see strange looking characters if your text editor is expecting a
different encoding. The encoding used in any external file is shown in the
#@+leo sentinel line like this::

    #@+leo-encoding=iso-8859-1.

**Exception**: the encoding is UTF-8 if no -encoding= field exists.
You can also use the @encoding directive_ to set the encoding for individual external files.
If no @encoding directive_ is in effect,
Leo uses the following settings_ to translate to and from unicode:

default_derived_file_encoding
    The encoding used for external files if no @encoding directive_ is in effect.
    This setting also controls the encoding of files that Leo writes.
    The default is UTF-8 (case not important).

new_leo_file_encoding
    The encoding specified in the following line of new .leo files::

        &lt;?xml version="1.0" encoding="UTF-8"&gt;

    The default is UTF-8 (upper case for compatibility for old versions of Leo).
</t>
<t tx="ekr.20050830120007">.. Links used in this document...

.. ----- External links.

.. _decorator:          http://www.python.org/peps/pep-0318.html
.. _docutils:           http://docutils.sourceforge.net/
.. _unicode:            http://www.unicode.org/
.. _`bzr repository`:   https//code.launchpad.net/leo-editor/

.. ----- Relative links into Leo's documentation.

.. _`Associating Leo with .leo Files`:  installing.html#creating-windows-file-associations
.. _`How to install Leo on Windows`:    installing.html#installing-leo-on-windows

.. _`Clones`:       tutorial-pim.html#clones
.. _`Views`:        tutorial-pim.html#views
.. _`CWEB mode`:    directives.html#cweb-mode
.. _command:        commands.html
.. _commands:       commands.html
.. _`tutorial about programming`:               tutorial-programming.html
.. _tutorial:                                   tutorial.html
.. _`Leo 4.0: Eliminating error 'recovery'`:    appendices.html#leo-4-0-eliminating-error-recovery
.. was: history.html#leo-4-0-eliminating-error-recovery
.. _`History of Leo`:                           appendices.html#history-of-leo
.. was: history.html
.. _`run Leo in a console window`:              running.html#running-leo-from-a-console-window
.. _`console window`:                           running.html#running-leo-from-a-console-window

.. ----- References to the glossary: the glossary now contains references to the tutorial.
.. _`@asis`:                glossary.html#asis-trees
.. _`@auto`:                glossary.html#auto-trees
.. _`@file`:                glossary.html#file-trees
.. _`@others directive`:    glossary.html#others
.. _`@nosent`:              glossary.html#nosent
.. _`@shadow`:              glossary.html#shadow-trees
.. _`@thin`:                glossary.html#thin-trees
.. _`@unit`:                glossary.html#unit
.. _`body text`:            glossary.html#body-text
.. _cweb:                   glossary.html#cweb
.. _directive:              glossary.html#directive
.. _directives:             glossary.html#directives
.. _`external file`:        glossary.html#external-file
.. _`external files`:       glossary.html#external-files
.. _headline:               glossary.html#headline
.. _headlines:              glossary.html#headlines
.. _node:                   glossary.html#node
.. _nodes:                  glossary.html#nodes
.. _outliner:               glossary.html#outliner
.. _sections:               glossary.html#sections
.. _`section name`:         glossary.html#section-name
.. _`section names`:        glossary.html#section-names
.. _sentinels:              glossary.html#sentinels
.. _`sentinel line`:        glossary.html#sentinel
.. _`sentinel lines`:       glossary.html#sentinel
.. _setting:                glossary.html#setting
.. _settings:               glossary.html#settings
</t>
<t tx="ekr.20050830120844" str_atime="1376412842.0">c.frame.menu.createMenuItemsFromTable will append items to the end of an existing menu.
For example, the following script will add a new item at the end of the 'File' menu::

    def callback(*args,**keys):
        g.trace()

    table = (("Test1",None,callback),)

    c.frame.menu.createMenuItemsFromTable('File',table)

Plugins can do anything with menus using c.frame.menu.getMenu. For example, here
is a script that adds a Test menu item after the 'Open With' menu item in the
File menu::

    def callback(*args,**keys):
        g.trace()

    fileMenu = c.frame.menu.getMenu('File')

    # 3 is the position in the menu.  Other kinds of indices are possible.
    fileMenu.insert(3,'command',label='Test2',command=callback)
</t>
<t tx="ekr.20050830120857">The trick is to create a workflow that separates editing from testing. Putting
test code in LeoPy.leo would waste a lot of time. To run tests you would
have to exit Leo and reload LeoPy.leo. A much quicker way is to put all test
code in a test.leo file. So to change and test code, do the following:

1. Save LeoPy.leo but do **not** exit Leo. 

2. Quit the copy of Leo running test.leo, then reload test.leo.

3. Run test scripts from test.leo.

That's all. Python will recompile any changed .py files in the new copy of Leo.
**Note**: I create a batch file called t.bat that runs test.leo, so to the
"edit-reload-test" cycle is just:

1. Control-S (in LeoPy.leo: saves the .leo file)
2. t         (in a console window: runs test.leo, compiling all changed .py files as a side effect)
3. Control-E (in test.leo: runs the test script)

The benefits of the new workflow:

- test.leo loads  _much_ more quickly than LeoPy.leo does.
  This new approach can increase the speed of the edit-reload-test cycle by more than a factor of 10.
  Hitting Control-S, t, Control-E takes about 5 seconds.

- LeoPy.leo runs with the *old* code,
  so it is much easier to fix syntax errors or exceptions in the *new* code:
  just fix the problem and save LeoPy.leo *without* closing LeoPy.leo,
  then restart test.leo.
  You run your tests on the new code, but you edit the new code with the old, stable code.

- test.leo is the perfect place to develop test.
  I can create and organize those tests and when I am done, ''test.leo'' is a log of my work.
</t>
<t tx="ekr.20050831184021.1"></t>
<t tx="ekr.20050831184021.4"></t>
<t tx="ekr.20050831184021.5"></t>
<t tx="ekr.20050831195331.1"></t>
<t tx="ekr.20050831195449">For instruction about installing Leo see:
http://leoeditor.com/installing.html

For everything a beginner needs to know about Leo see:
http://leoeditor.com/tutorial.html

For help, please ask questions at:
http://groups.google.com/group/leo-editor</t>
<t tx="ekr.20050831232205">.. Relative links.
.. _`Writing plugins`:   writingPlugins.html

.. References to the glossary.
.. _`sentinel lines`:   glossary.html#sentinel-lines
</t>
<t tx="ekr.20050901084134">I wrote this soon after discovering Python in 2001. The conclusions are
still valid today.
    
I've known for a while that Python was interesting; I attended a Python
conference last year and added Python support to Leo. But last week I got that
Python is something truly remarkable. I wanted to convert Leo from wxWindows to
wxPython, so I began work on c2py, a Python script that would help convert from
C++ syntax to Python. While doing so, I had an Aha experience. Python is more
than an incremental improvement over Smalltalk or C++ or objective-C; it is
"something completely different". The rest of this post tries to explain this
difference.


</t>
<t tx="ekr.20050901092232.2">What struck me first as I converted C++ code to Python is how much less blah,
blah, blah there is in Python. No braces, no stupid semicolons and most
importantly, *no declarations*. No more pointless distinctions between
const, char \*, char const \*, char \* and wxString.
No more wondering whether a variable should be signed, unsigned, short or long.

Declarations add clutter, declarations are never obviously right and
declarations don't prevent memory allocation tragedies. Declarations also hinder
prototyping. In C++, if I change the type of something I must change all related
declarations; this can be a huge and dangerous task. With Python, I can change
the type of an object without changing the code at all! It's no accident that
Leo's new log pane was created first in Python.

Functions returning tuples are a "minor" feature with a huge impact on code
clarity. No more passing pointers to data, no more defining (and allocating and
deallocating) temporary structs to hold multiple values.

.. _`pylint`: http://www.logilab.org/857

Python can't check declarations because there aren't any. However, there is a
really nifty tool called `pylint`_ that does many of the checks typically done
by compilers.
</t>
<t tx="ekr.20050901092232.3">Python is much more powerful than C++, not because Python has more features, but
because Python needs *less* features. Some examples:

-   Python does everything that the C++ Standard Template Library (STL) does,
    without any of the blah, blah, blah needed by STL.
    No fuss, no muss, no code bloat.

-   Python's slicing mechanism is very powerful and applies to any sequence (string, list or tuple).
    Python's string library does more with far less functions because slices replace many functions
    typically found in other string libraries.

-   Writing dict = {} creates a dictionary (hash table).
    Hash tables can contain anything, including lists and other hash tables.

-   Python's special functions,  __init__, __del__, __repr__, __cmp__, etc.
    are an elegant way to handle any special need that might arise.
</t>
<t tx="ekr.20050901092232.4">Before using Python I never fully realized how difficult and dangerous memory allocation is in C++.
Try doing::

        aList[i:j] = list(aString)

in C.  You will write about 20 lines of C code.
Any error in this code will create a memory allocation crash or leak.

Python is fundamentally safe. C++ is fundamentally unsafe. When I am using
Python I am free from worry and anxiety. When I am using C++ I must be
constantly "on guard." A momentary lapse can create a hard-to-find pointer bug.
With Python, almost nothing serious can ever go wrong, so I can work late at
night, or after a beer. The Python debugger is always available. If an exception
occurs, the debugger/interpreter tells me just what went wrong. I don't have to
plan a debugging strategy! Finally, Python recovers from exceptions, so Leo can
keep right on going even after a crash!
</t>
<t tx="ekr.20050901092232.5">Python has almost all the speed of C. Other interpretive environments such as
icon and Smalltalk have clarity, power and safety similar to Python. What makes
Python unique is its seamless way of making C code look like Python code.
Python executes at essentially the speed of C code because most Python modules
are written in C. The overhead in calling such modules is negligible. Moreover,
if code is too slow, one can always create a C module to do the job.

In fact, Python encourages optimization by moving to higher levels of
expression. For example, Leo's Open command reads an XML file. If this command
is too slow I can use Python's XML parser module. This will speed up Leo while
at the same time raising the level of the code.
</t>
<t tx="ekr.20050901092232.6">Little of Python is completely new. What stands out is the superb engineering
judgment evident in Python's design. Python is extremely powerful, yet small,
simple and elegant. Python allows me to express my intentions clearly and at the
highest possible level.

The only hope of making Leo all it can be is to use the best possible tools. I
believe Python will allow me to add, at long last, the new features that Leo
should have.

Edward K. Ream, October 25, 2001.  P.S., September, 2005:

Four years of experience have only added to my admiration for Python. Leo could
not possibly be what it is today without Python.
</t>
<t tx="ekr.20050901101608.2">########################
Leo's Commands Reference
########################

This chapter discusses the basics of using Leo, including all of Leo's
commands. It starts with a discussion of the Emacs-like minibuffer,
then continues with a discussion of commands in each of Leo's menus.

.. contents::
    :depth: 3

</t>
<t tx="ekr.20050901101608.4">################
Customizing Leo
################

This chapter discusses how to customize Leo using the plugins and other means.
See `Specifying settings`_ for a description of how to change Leo's settings.

.. contents::
    :depth: 3
</t>
<t tx="ekr.20050901101852">.. External links...
.. _CWEB:       http://www-cs-faculty.stanford.edu/~knuth/cweb.html
.. _noweb:      http://www.eecs.harvard.edu/~nr/noweb/

.. Relative links...
.. _`Writing Programs in Leo`:          directives.html
.. _`Customizing Leo`:                  customizing.html
.. _`Clones`:                           tutorial-pim.html#clones
.. _`A Tutorial Introduction to Leo`:   tutorial.html
</t>
<t tx="ekr.20050901102055">.. _`Scripting Leo with Python`:    tutorial-scripting.html
.. _`History of Leo`:               appendices.html#history-of-leo
.. was: history.html
.. _`rst3 plugin`:                  glossary.html#rst3-plugin
.. _`Specifying settings`:          commands.html#specifying-settings
</t>
<t tx="ekr.20050901102147">.. Relative links...
.. _`Scripting Leo with Python`:        tutorial-scripting.html
.. _`Customizing Leo`:                  customizing.html
.. _`Theory of Operation`:              theory.html
.. _`Controlling Syntax Coloring`:      coloring.html
.. _`Debugging with Leo`:               debuggers.html
.. _`Using ZODB with Leo`:              zodb.html
.. _`Leo and Emacs`:                    emacs.html
.. _`Embedding Leo with the leoBridge Module`: leoBridge.html
.. _`Unit testing with Leo`:            unitTesting.html
.. _`ILeo - the IPython bridge`:        IPythonBridge.html
.. _`the IPython bridge`:               IPythonBridge.html
.. _`Using @shadow`:                    atShadow.html
.. _`What's New`:                       what-is-new.html

.. Absolute links..
.. _OPML:   http://en.wikipedia.org/wiki/OPML
</t>
<t tx="ekr.20050902100834">This following information may be of interest to historians. It is not of
general enough interest to put in Leo's Users Guide on the web. I am including
this mass of detail here to indicate the complexities that were involved in
designing Leo's simple-looking mechanisms.
</t>
<t tx="ekr.20050902105852">Leo grew out of my efforts to use Donald Knuth's "CWEB system of Structured
documentation." I had known of literate programming since the mid 1980's, but I
never understood how to make it work for me. In November 1995 I started thinking
about programming in earnest. Over the holidays I mused about making programs
more understandable. In January 1996 the fog of confusion suddenly cleared. I
summarized my thinking with the phrase, **web are outlines in disguise**. I
suspected that outline views were the key to programming, but many details
remained obscure.
</t>
<t tx="ekr.20050902105852.1">March 5, 1996, is the most important date in Leo's history. While returning from
a day of skiing, I discussed my thoughts with Rebecca. During that conversation
I realized that I could use the MORE outliner as a prototype for a "programming
outliner." I immediately started work on my first outlined program. It quickly
became apparent that outlines work: all my old problems with programming
vanished. The @others directive dates from this day. I realized that MORE's
outlines could form the basis for Leo's screen design. Rather than opening body
text within the outline, as MORE does, I decided to use a separate body pane.

I hacked a translator called M2C which allowed me to use MORE to write
real code. I would write code in MORE, copy the text to the clipboard in
MORE format, then run M2C, which would convert the outline into C code.
This process was useful, if clumsy. I called the language used in the outline
SWEB, for simplified CWEB. Much later Leo started supporting the noweb
language.
</t>
<t tx="ekr.20050902105852.10">Leo first used gnx's (global node indices) as a foolproof way of associating
nodes in .leo files with nodes in external files. At the time, there was
still intense discussions about protecting the logical consistency of
outlines. \@thin was later to solve all those problems, but nobody knew
that then.
</t>
<t tx="ekr.20050902105852.11">Leo 4.2 Final went out the door September 20, 2004.
This surely is one of the most significant dates in Leo's history:

-   This marked the end worries about consistency of outlines and external files:
    Leo recreates all essential information from thin external files,
    so *there is nothing left in the .leo file to get out of synch*.

- Thin external files use gnx's extensively. This simplifies the file format and
    makes thin external files more cvs friendly.

-   A sensational scripting plugin showed how to create script buttons.
    This has lead to improvements in the Execute Script command and
    other significant improvements in Unit testing.

-   As if this were not enough, 4.2 marked the 'great divide' in Leo's internal
    data structures. Before 4.2, Leo every node in the outline had its own
    vnode. This was a big performance problem: clone operations had to
    traverse the entire outline! 4.2 represents clones by sharing subtrees.
    Changing Leo's fundamental data structures while retaining compatibility
    with old scripts was engineering work of which the entire Leo community can
    be proud. `Scripting Leo with Python`_ tells how the position
    class makes this happen.
    This was a cooperative effort. Kent Tenney and Bernhard Mulder made
    absolutely crucial contributions. Kent pointed out that it is a tnode,
    not a vnode that must form the root of the shared data. Bernhard showed
    that iterators are the way to avoid creating huge numbers of positions.

Leo 4.2 marked so many significant changes. I often find it hard to remember
what life with Leo was like before it.
</t>
<t tx="ekr.20050902105852.12">Leo 4.3 corrected many problems with leoConfig.txt. Instead, Leo gets
settings from one or more leoSettings.leo files. This version also
introduced a way to changed settings using a settings dialog.  However,
the settings dialog proved not to be useful (worse, it inhibited design) and
the settings dialog was retired in Leo 4.4.
</t>
<t tx="ekr.20050902105852.2">Throughout 1996 I created a version of Leo on the Macintosh in plain C and the
native Mac Toolbox. This was a poor choice; I wasted a huge amount of time
programming with these primitive tools. However, this effort convinced me that
Leo was a great way to program.

Late in 1997 I wrote a Print command to typeset an outline. Printing (Weaving)
is supposedly a key feature of literate programming. Imagine my surprise when I
realized that such a "beautiful" program listing was almost unintelligible; all
the structure inherent in the outline was lost! I saw clearly that typesetting,
no matter how well done, is no substitute for explicit structure.

In 1998 I created a version of Leo using Apple's YellowBox environment. Alas,
Apple broke its promises to Apple developers. I had to start again.
</t>
<t tx="ekr.20050902105852.3">I rewrote Leo for Borland C++ starting in May 1999. Borland C++ was much better
than CodeWarrior C, but it was still C++. This version of Leo was the first
version to use xml as the format of .leo files. The last version of Borland Leo,
3.12 Final went out the door July 17, 2003.
</t>
<t tx="ekr.20050902105852.4">I attended the Python conference in early 2001. In May of 2000 I began work on
an wxWindows version of Leo. This did not work out, but something good did come
from this effort. I spent a lot of time adding Python scripting to the wxWindows
code and I became familiar with Python and its internals.

I really started to 'get' Python in September 2001. I wrote the white papers at
about this time. Python solved *all* my programming problems. I rewrote Leo in
Python in about two months! For the first time in my career I was no longer
anxious while programming; it simply isn't possible to create bad bugs in
Python. The Python version of Leo was the first officially OpenSoftware version of
Leo. The first functional version of Leo in Python was 0.05 alpha, December 17,
2001.
</t>
<t tx="ekr.20050902105852.5">I registered the Leo project on SourceForge on March 10, 2003. It is certainly
no accident that Leo started a new life shortly thereafter. Prior to SourceForge
my interest in Leo had been waning.
</t>
<t tx="ekr.20050902105852.6">In the summer of 2001 I began to consider using sentinel lines in external files.
Previously I had thought that outline structure must be 'protected' by remaining
inside .leo files. Accepting the possibility that sentinels might be corrupted
opened vast new design possibilities. In retrospect, problems with sentinel
almost never happen, but that wasn't obvious at the time! The result of this
design was known at first as Leo2. That terminology is extinct. I think of
this version as the first version to support @file and automatic tangling
and untangling.
</t>
<t tx="ekr.20050902105852.7">The biggest surprise in Leo's history was the realization it is **much** easier
to untangle files derived from @file. Indeed, the old tangle code created all
sorts of problems that just disappear when using @file. The new Python version
of Leo became fully operational in early 2002. It was probably about this time
that I chose noweb as Leo's preferred markup language. My decision not to
support noweb's escape sequences made Leo's read code much more robust.
</t>
<t tx="ekr.20050902105852.8">I spent 2002 taking advantages of Python's tremendous power and safety.
Many improvements were at last easy enough to do:

- Nested @others directives appeared in 3.2.
- Unicode support started in 3.3.
- @first and @last appeared in 3.7
- @asis and @nosent appeared in 3.8.
- Incremental syntax coloring and incremental undo appeared in 3.9.
- Paul Paterson created Leo's plugin architecture sometime during this period.
  Plugins have been a driving force in Leo's development because people can
  change how Leo works without altering Leo's core.
- 3.12 fixed a huge memory leak.
- 3.12 Final, the last 3.x version, appeared July 17, 2003.
</t>
<t tx="ekr.20050902105852.9">In late 2002 and throughout 2003 I worked on an entirely new file format.
4.0 final went out the door October 17, 2003 after almost a year intense
design work trying to improve error recovery scheme used while reading
external files. In the summer of 2003 I realized that orphan and @ignore'd
nodes must be prohibited in @file trees. With this restriction, Leo
could finally recreate @file trees in outlines using **only** the
information in external files. This made the read code much more robust, and
eliminated all the previous unworkable error recovery schemes. At last Leo
was on a completely firm foundation.
</t>
<t tx="ekr.20050903074833">Plugins and other scripts can register event handlers (also known as hooks)::

    leoPlugins.registerHandler("after-create-leo-frame",onCreate)
    leoPlugins.registerHandler("idle", on_idle) 
    leoPlugins.registerHandler(("start2","open2","command2"), create_open_with_menu) 

As shown above, a plugin may register one or more event handlers with a single call to
leoPlugins.registerHandler. Once a hook is registered, Leo will call the
registered function' at the named **hook time**. For example::

    leoPlugins.registerHandler("idle", on_idle)

causes Leo to call on_idle at "idle" time.

Event handlers must have the following signature::

    def myHook (tag, keywords):
        whatever

-   tag is the name of the hook (a string).
-   keywords is a Python dictionary containing additional information.
    The following section describes the contents of the keywords dictionary in detail.

**Important**: hooks should get the proper commander this way::

    c = keywords.get('c')
</t>
<t tx="ekr.20050903074833.1">The following table tells about each event handler: its name, when it is called,
and the additional arguments passed to the hook in the keywords dictionary.
For some kind of hooks, Leo will skip its own normal processing if the hook
returns anything *other* than None. The table indicates such hooks with 'yes' in
the 'Stop?' column.

**Important**: Ever since Leo 4.2, the v, old_v and new_v keys in
the keyword dictionary contain *positions*, not vnodes. These keys are
deprecated. The new_c key is also deprecated. Plugins should use the c key instead.

============================= ======== =================================== =============================
Event name (tag argument)     Stop?    When called                         Keys in keywords dict
============================= ======== =================================== =============================
'after-auto'                           after each @auto file loaded        c,p (note 13)
'after-create-leo-frame'               after creating any frame            c
'after-redraw-outline'                 end of tree.redraw                  c (note 6)
'before-create-leo-frame'              before frame.finishCreate           c
'bodyclick1'                   yes     before normal click in body         c,p,v,event
'bodyclick2'                           after normal click in body          c,p,v,event
'bodydclick1'                  yes     before double click in body         c,p,v,event
'bodydclick2'                          after  double click in body         c,p,v,event
'bodykey1'                     yes     before body keystrokes              c,p,v,ch,oldSel,undoType
'bodykey2'                             after  body keystrokes              c,p,v,ch,oldSel,undoType
'bodyrclick1'                  yes     before right click in body          c,p,v,event
'bodyrclick2'                          after  right click in body          c,p,v,event
'boxclick1'                    yes     before click in +- box              c,p,v,event
'boxclick2'                            after  click in +- box              c,p,v,event
'clear-all-marks'                      after clear-all-marks command       c,p,v
'clear-mark'                           when mark is set                    c,p,v
'close-frame'                          in app.closeLeoWindow               c
'color-optional-markup'        yes *   (note 7)                            colorer,p,v,s,i,j,colortag (note 7)
'command1'                     yes     before each command                 c,p,v,label (note 2)
'command2'                             after  each command                 c,p,v,label (note 2)
'create-optional-menus'                (note 8)                            c (note 8)
'create-popup-menu-items'              in tree.OnPopup                     c,p,v,event (new)
'draw-outline-box'             yes     when drawing +- box                 tree,p,v,x,y
'draw-outline-icon'            yes     when drawing icon                   tree,p,v,x,y
'draw-outline-node'            yes     when drawing node                   tree,p,v,x,y
'draw-outline-text-box'        yes     when drawing headline               tree,p,v,x,y
'drag1'                        yes     before start of drag                c,p,v,event
'drag2'                                after  start of drag                c,p,v,event
'dragging1'                    yes     before continuing to drag           c,p,v,event
'dragging2'                            after  continuing to drag           c,p,v,event
'enable-popup-menu-items'              in tree.OnPopup                     c,p,v,event
'end1'                                 start of app.quit()                 None
'enddrag1'                     yes     before end of drag                  c,p,v,event
'enddrag2'                             after  end of drag                  c,p,v,event
'headclick1'                   yes     before normal click in headline     c,p,v,event
'headclick2'                           after  normal click in headline     c,p,v,event
'headrclick1'                  yes     before right click in headline      c,p,v,event
'headrclick2'                          after  right click in headline      c,p,v,event
'headkey1'                     yes     before headline keystrokes          c,p,v,ch (note 12)
'headkey2'                             after  headline keystrokes          c,p,v,ch (note 12)
'hoist-changed'                        whenever the hoist stack changes    c
'hypercclick1'                 yes     before control click in hyperlink   c,p,v,event
'hypercclick2'                         after  control click in hyperlink   c,p,v,event
'hyperenter1'                  yes     before entering hyperlink           c,p,v,event
'hyperenter2'                          after  entering hyperlink           c,p,v,event
'hyperleave1'                  yes     before leaving  hyperlink           c,p,v,event
'hyperleave2'                          after  leaving  hyperlink           c,p,v,event
'iconclick1'                   yes     before single click in icon box     c,p,v,event
'iconclick2'                           after  single click in icon box     c,p,v,event
'iconrclick1'                  yes     before right click in icon box      c,p,v,event
'iconrclick2'                          after  right click in icon box      c,p,v,event
'icondclick1'                  yes     before double click in icon box     c,p,v,event
'icondclick2'                          after  double click in icon box     c,p,v,event
'idle'                                 periodically (at idle time)         c
'init-color-markup'                    (note 7)                            colorer,p,v (note 7)
'menu1'                        yes     before creating menus               c,p,v (note 3)
'menu2'                        yes     during creating menus               c,p,v (note 3)
'menu-update'                  yes     before updating menus               c,p,v
'new'                                  start of New command                c,old_c,new_c (note 9)
'open1'                        yes     before opening any file             c,old_c,new_c,fileName (note 4)
'open2'                                after  opening any file             c,old_c,new_c,fileName (note 4)
'openwith1'                    yes     before Open With command            c,p,v,d (note 14)
'openwith2'                            after  Open With command            c,p,v,(note 14)
'recentfiles1'                 yes     before Recent Files command         c,p,v,fileName,closeFlag
'recentfiles2'                         after  Recent Files command         c,p,v,fileName,closeFlag
'redraw-entire-outline'        yes     start of tree.redraw                c (note 6)
'save1'                        yes     before any Save command             c,p,v,fileName
'save2'                                after  any Save command             c,p,v,fileName
'scan-directives'                      in scanDirectives                   c,p,v,s,old_dict,dict,pluginsList (note 10)
'select1'                      yes     before selecting a position         c,new_p,old_p,new_v,new_v
'select2'                              after  selecting a position         c,new_p,old_p,new_v,old_v
'select3'                              after  selecting a position         c,new_p,old_p,new_v,old_v
'set-mark'                             when a mark is set                  c,p,v
'show-popup-menu'                      in tree.OnPopup                     c,p,v,event
'start1'                               after app.finishCreate()            None
'start2'                               after opening first Leo window      c,p,v,fileName
'unselect1'                    yes     before unselecting a vnode          c,new_p,old_p,new_v,old_v
'unselect2'                            after  unselecting a vnode          c,new_p,old_p,old_v,old_v
'\@url1'                        yes     before double-click @url node       c,p,v,url (note 5)
'\@url2'                                after  double-click @url node       c,p,v(note 5)
============================= ======== =================================== =============================

**Notes**:

1.  'activate' and 'deactivate' hooks have been removed because they do not work as expected.

2.  'commands' hooks: The label entry in the keywords dict contains the
    'canonicalized' form of the command, that is, the lowercase name of the command
    with all non-alphabetic characters removed.
    Commands hooks now set the label for undo and redo commands 'undo' and 'redo'
    rather than 'cantundo' and 'cantredo'.

3.  'menu1' hook: Setting g.app.realMenuNameDict in this hook is an easy way of
    translating menu names to other languages. **Note**: the 'new' names created this
    way affect only the actual spelling of the menu items, they do *not* affect how
    you specify shortcuts settings, nor do they affect the 'official'
    command names passed in g.app.commandName. For example::

        app().realMenuNameDict['Open...'] = 'Ouvre'.

4.  'open1' and 'open2' hooks: These are called with a keywords dict containing the following entries:

    - c:          The commander of the newly opened window.
    - old_c:      The commander of the previously open window.
    - new_c:      (deprecated: use 'c' instead) The commander of the newly opened window.
    - fileName:   The name of the file being opened.

    You can use old_c.p and c.p to get the current position in the old and new windows.
    Leo calls the 'open1' and 'open2' hooks only if the file is not already open. Leo
    will also call the 'open1' and 'open2' hooks if: a) a file is opened using the
    Recent Files menu and b) the file is not already open.

5.  '\@url1' and '\@url2' hooks are only executed if the 'icondclick1' hook returns None.

6.  These hooks are useful for testing.

7.  These hooks allow plugins to parse and handle markup within doc parts,
    comments and Python ''' strings. Note that these hooks are *not* called in
    Python ''' strings. See the color_markup plugin for a complete example of how to
    use these hooks.

8.  Leo calls the 'create-optional-menus' hook when creating menus. This hook need
    only create new menus in the correct order, without worrying about the placement
    of the menus in the menu bar. See the plugins_menu and scripts_menu plugins for
    examples of how to use this hook.

9.  The New command calls 'new'.
    The 'new_c' key is deprecated.  Use the 'c' key instead.

10. g.scanDirectives calls 'scan-directives' hook.
    g.scanDirectives returns a dictionary, say d.
    d.get('pluginsList') is an a list of tuples (d,v,s,k) where:

    - d is the spelling of the @directive, without the leading @.
    - v is the vnode containing the directive, _not_ the original vnode.
    - s[k:] is a string containing whatever follows the @directive.
      k has already been moved past any whitespace that follows the @directive.

    See the add_directives plugins directive for a complete example of how to use
    the 'scan-directives' hook.

11. g.app.closeLeoWindow calls the 'close-frame' hook just before
    removing the window from g.app.windowList. The hook code may remove the window
    from app.windowList to prevent g.app.closeLeoWindow from destroying the window.

12. Leo calls the 'headkey1' and 'headkey2' when the headline *might* have changed.

13. p is the new node (position) containing '@auto filename.ext'

14. New in Leo 4.10: the d argument to the open-with event handlers is a python
    dictionary whose keys are all the tags specified by the user in the body of the
    @openwith node.
</t>
<t tx="ekr.20050903161843">\@button nodes create **script buttons** in Leo's icon area.

Each @button node also creates a corresponding minibuffer command.

Pressing the script button (or executing the command from the minibuffer)
applies the script in the @button node to the presently selected outline
node.

Script buttons **bring scripts to outlines** a powerful pattern. Creating
an @button script should be your first thought whenever you want to
automate any task.

- The mod_scripting.py plugins must be enabled to create @button nodes.

- Script buttons execute the **present** body text of the @button node. |br|
  You can modify a script button's script at any time.

- You can bind keys to the commands created by script buttons::

    @button my-button @key=Alt-8

- Right-clicking a script button deletes it.
</t>
<t tx="ekr.20050906090012">Leo (and other programs) often send more detailed error messages to stderr,
the output stream that goes to the console window. In Linux and MacOS
environments, python programs normally execute with the console window visible.
On Windows, can run Leo with the console window visible by associating .leo
files with python.exe *not* pythonw.exe.
</t>
<t tx="ekr.20050907094633">Settings may be different for each commander.

The c.config class has the following getters.

- c.config.getBool(settingName,default=None)
- c.config.getColor(settingName)
- c.config.getDirectory(settingName)
- c.config.getFloat(settingName)
- c.config.getInt(settingName)
- c.config.getLanguage(settingName)
- c.config.getRatio(settingName)
- c.config.getShortcut(settingName)
- c.config.getString(settingName)

These methods return None if no setting exists.

The getBool 'default' argument to getBool specifies the value to be
returned if the setting does not exist.
</t>
<t tx="ekr.20050912125144" str_atime="1376413890.0"></t>
<t tx="ekr.20050912125144.1" str_atime="1376413508.0">#######
Plugins
#######

.. _`Using @button nodes`:  tutorial-scripting#using-button-nodes
.. _`Writing Plugins`:  writingPlugins.html

This chapter discusses the plugins contained in leoPlugins.leo.
These plugins are part of Leo's official distribution.
The next chapter, `Writing Plugins`_, tells how to write plugins.

The scripting plugin (mod_scripting.py) deserves special mention. This
plugin lets you create **script buttons** in a matter of seconds. See
`Using @button nodes`_. Script buttons are extraordinarily useful.

.. contents::
    :depth: 5
    
</t>
<t tx="ekr.20050912125735">.. External links...
.. _docutils:             http://docutils.sourceforge.net
.. _LaTeX:                http://www.latex-project.org/
.. _reStructuredText:     http://docutils.sourceforge.net/rst.html
.. .. _SilverCity:           http://silvercity.sourceforge.net

.. Relative links...
.. _`Specifying settings`:      customizing.html#specifying-settings
.. _`Customizing Leo`:          customizing.html
.. .. _`Writing Plugins`:          writingPlugins.html
</t>
<t tx="ekr.20050912125735.363">The dyna_menu plugin is a remarkable body of work by 'e'.
This plugin creates a dyna_menu menu from which you can execute commands.
You may download the latest version at: http://rclick.netfirms.com/dyna_menu.py.html
</t>
<t tx="ekr.20051202072010"></t>
<t tx="ekr.20060105214753">Leo now allows you to specify input modes. You enter mode x with the
enter-x-mode command. The purpose of a mode is to create different bindings
for keys within a mode. Often plain keys are useful in input modes.

You can specify modes with @mode nodes in leoSettings.leo. @mode nodes work
just like @shortcuts nodes, but in addition they have the side effect of
creating the enter-&lt;mode name&gt;-mode command.

Notes:

- You can exit any mode using the keyboard-quit (Control-g) command. This is the
  **only** binding that is automatically created in each mode. All other bindings
  must be specified in the @mode node. In particular, the bindings specified in
  @shortcuts nodes are **not** in effect in mode (again, except for the
  keyboard-quit binding).

- Leo supports something akin to tab completion within modes: if you type a key
  that isn't bound in a mode a 'Mode' tab will appear in the log pane. This tab
  shows all the keys that you can type and the commands to which they are bound.
  The mode-help command does the same thing.

- @shortcuts nodes specify the bindings for what might be called the 'top-level'
  mode. These are the bindings in effect when no internal state is present, for
  example, just after executing the keyboard-quit command.

- The top_level_unbound_key_action setting determines what happens to
  unbound keys in the top-level mode. Leo ignores unbound keys in all other modes.
  The possibilities are 'insert', 'replace' and 'ignore'.

- The set-insert-mode, set-overwrite-mode and set-ignore-mode
  commands alter what happens to unbound keys in the top-level mode.
  
- If the @mode headline contains ::, everything following
  the :: is the mode prompt. For example::
    
    @mode abc :: xyz
    
Creates the enter-abc-mode command, but the prompt for the command is xyz.

With all these options it should be possible to emulate the keyboard behavior of any other editor.
</t>
<t tx="ekr.20060111192108">A **dangerous** delete is a deletion of a node so that all the data in the node
is deleted *everywhere* in an outline. The data is gone, to be retrieved only
via undo or via backups. It may not be obvious which deletes are dangerous in an
outline containing clones. Happily, there is a very simple rule of thumb::

    Deleting a non-cloned node is *always* dangerous.
    Deleting a cloned node is *never* dangerous.

We could also consider a delete to be dangerous **if it results in a node being
omitted from an external file.** This can happen as follows. Suppose we have the
following outline (As usual, A' indicates that A is marked with a clone mark)::

    - @file spam.py
        - A'
            - B
    - Projects
        - A'
            - B

Now suppose we clone B, and move the clone so the tree looks like this::

    - @file spam.py
        - A'
            - B'
    - Projects
        - A'
            - B'
        - B'

If (maybe much later), we eliminate B' as a child of A will get::

    - @file spam.py
        - A'
    - Projects
        - A'
        - B

B has not been destroyed, but B is gone from @file spam.py! So in this sense deleting a clone node can also be called dangerous.
</t>
<t tx="ekr.20060329101442">Missing modules can cause installation problems.
If the installer doesn't work (or puts up a dialog containing no text), you may install Leo from the .zip file
as described at `How to install Leo on Windows`_.
However you are installing Leo,
be sure to `run Leo in a console window`_.
because as a last resort Leo prints error messages to the console.
</t>
<t tx="ekr.20060430220749">The jEdit_ editor drives its syntax colorer using xml **language description files.**
Rather than using the xml language description files directly, Leo uses
Python **colorer control files**, created automatically from the xml files by a
script called jEdit2Py.  All these files reside in the leo/modes directory.

These Python files contain all the information in the jEdit's xml files, so we
can (loosely) speak of modes, rulesets, rules, properties and attributes in the
Python colorer control files. Later sections of this documentation will make
this loose correspondence exact.

`jEdit's documentation`_ contain a complete description of these xml files.
Each xml file describes one **colorizing mode**.
A mode consists of one or more **rulesets**, and each ruleset consists of a list of **colorizing rules**.
In addition, modes, rulesets and rules may have associated **properties** and **attributes**.
Various rules may specify that the colorizer uses another ruleset (either in the same mode or another mode).

**Important**: jEdit's xml language description files contain no explicit &lt;RULE&gt; elements
Rules are simply sub-elements of an enclosing &lt;RULES&gt; element.
The element indicates the kind of rule that is specified,
for example, &lt;SPAN&gt;, &lt;SEQ&gt;, etc.
By the term **rule element** we shall mean any sub-element of the &lt;RULES&gt; element.

**Important**: throughout this documentation,
**x.py** will refer to the Python colorer for language x,
and **x.xml** will refer to the corresponding xml language-description file.

Using Python colorer control files has the following advantages:

- Running jEdit2Py need only be done when x.xml changes,
  and the speed of the xml parser in jEdit2Py does not affect the speed of Leo's colorizer in any way.
  Moreover, the jEdit2Py script can contain debugging traces and checks.

- Colorer control files are valid .py files, so all of Python's import optimizations work as usual.
  In particular, all the data in colorer control files is immediately accessible to Leo's colorer.

- Colorer control files are easier for humans to understand and modify than the equivalent xml file.
  Furthermore, it is easy to insert debugging information into Python colorer control files.

- It is easy to modify the Python colorer control files 'by hand' without changing the corresponding xml file.
  In particular, it would be easy to define entirely new kinds of pattern-matching rules in Python merely
  by creating functions in a colorer control file.
</t>
<t tx="ekr.20060430221745"></t>
<t tx="ekr.20060430221745.1">###########################
Controlling Syntax Coloring
###########################

This chapter discusses the settings to control Leo's syntax colorer. This
chapter also discusses how to extend Leo's colorizer by creating xml language
descriptions files and corresponding Python files. **Important**: this material
is for those who want to support Leo's colorizing code. To use Leo's colorizers
you only need to know about syntax-coloring settings.

.. contents::
    :depth: 3
</t>
<t tx="ekr.20060430222753">.. External links...
.. _jEdit:                      http://www.jedit.org/
.. _`jEdit's documentation`:    http://www.jedit.org/42docs/users-guide/writing-modes-part.html

.. Relative links...
.. _`Ruleset name`:      `Ruleset names`_
.. _`Customizing Leo`:           customizing.html
</t>
<t tx="ekr.20060502084233">When Leo's syntax colorer sees the '@language x' directive,
it will import x.py from Leo's modes folder.
The colorer can then access any module-level object obj in x.py as x.obj.

Colorizer control files contain **rules functions** corresponding to rule elements in x.xml.
The colorizer can call these functions as if they were members of the colorizer class by
passing 'self' as the first argument of these functions.
I call these rules *functions* to distinguish them from the corresponding
**rules methods** which are actual methods of the colorizer class.
Rules *functions* merely call corresponding rules *methods*.
Indeed, rules functions are simply a way of binding values to keyword arguments of rules methods.
These keywords arguments correspond to the xml attributes of rule elements in x.xml.

The colorizer calls rules functions until one matches, at which point a range of text gets colored and the process repeats.
The inner loop of the colorizer is this code::

    for f in self.rulesDict.get(s[i],[]):
        n = f(self,s,i)
        if n &gt; 0:
            i += n ; break
        else: i += 1

- rulesDict is a dictionary whose keys are rulesets and whose values are ruleset dictionaries.
  Ruleset dictionaries have keys that are single characters and whose values are
  the list of rules that can start with that character. 

- s is the full text to be colorized.

- i is the position within s is to be colorized.

Rules methods (and functions) return n &gt; 0 if they match, and n == 0 if they fail.
</t>
<t tx="ekr.20060502084233.1">The following sections describe the top-level data in x.py.
</t>
<t tx="ekr.20060502090516">**x.properties** is a Python dictionary corresponding to the &lt;PROPS&gt; element in x.xml.
Keys are property names; values are strings, namely the contents of &lt;PROPERTY&gt; elements in x.xml.
x.properties contains properties for the entire mode.
That is, only modes have &lt;PROPS&gt; elements.
For example, here is x.properties in php.py::

    # properties for mode php.xml
    properties = {
        "commentEnd": "--&gt;",
        "commentStart": "&lt;!--",
        "indentCloseBrackets": "}",
        "indentOpenBrackets": "{",
        "lineUpClosingBracket": "true",
    }
</t>
<t tx="ekr.20060502090516.1">x.py contains a **keyword dictionary** for each ruleset in x.xml.
x.py contains an empty keywords dictionary if a ruleset contains no &lt;KEYWORDS&gt; element.

Keys are strings representing keywords of the language describe by the mode.
Values are strings representing syntactic categories,
i.e. a TYPE attribute valid in x.xml, namely:
COMMENT1, COMMENT2, COMMENT3, COMMENT4,
FUNCTION,
KEYWORD1, KEYWORD2, KEYWORD3, KEYWORD4,
LABEL, LITERAL1, LITERAL2, LITERAL3, LITERAL4,
MARKUP, NULL and OPERATOR.

For example, here (parts of) some keyword dictionaries in php.py::

    # Keywords dict for mode php::PHP
    php_PHP_keywords_dict = {
        "COM_invoke": "keyword2",
        "COM_load": "keyword2",
        "__CLASS__": "keyword3",
        ...
        "abs": "keyword2",
        "abstract": "keyword1",
        "accept_connect": "keyword2",
        ...
    }

    # Keywords dict for mode php::JAVASCRIPT_PHP
    php_JAVASCRIPT_PHP_keywords_dict = {}

    # Keywords dict for mode php::PHPDOC
    php_PHPDOC_keywords_dict = {
        "@abstract": "label",
        "@access": "label",
        "@author": "label",
        ...
        "@var": "label",
        "@version": "label",
    }

x.py also contains **x.keywordsDictDict**.
Keys are ruleset names, values are keywords dictionaries.
Here is keywordsDictDict for php.py::

    # Dictionary of keywords dictionaries for php mode.
    keywordsDictDict = {
        "php_javascript": php_javascript_keywords_dict,
        "php_javascript_php": php_javascript_php_keywords_dict,
        "php_main": php_main_keywords_dict,
        "php_php": php_php_keywords_dict,
        "php_php_literal": php_php_literal_keywords_dict,
        "php_phpdoc": php_phpdoc_keywords_dict,
        "php_tags": php_tags_keywords_dict,
        "php_tags_literal": php_tags_literal_keywords_dict,
    }

The colorizer can get the keywords dictionary for a ruleset as follows::

    keywordsDict = x.keywordsDictDict(rulesetName)

**Note**:
The jEdit2Py script creates 'friendly' names for keyword dictionaries *solely* as an aid for people reading the code.
Leo's colorer uses only the name x.keywordsDictDict;
Leo's colorer never uses the actual names of keywords dictionaries such as php_PHPDOC_keywords_dict.
</t>
<t tx="ekr.20060502090516.2">x.py contains one **rule function** for every rule in every ruleset (&lt;RULES&gt; element) in x.xml.
These rules have names rule1 through  ruleN,
where N is the total number of rules in all rulesets in x.xml.

Each rules *function* merely calls a rules *method* in Leo's colorizer.
Which method gets called depends on the corresponding element in `x.xml`.
For example, the first rule in php.xml is::

    &lt;SPAN TYPE="MARKUP" DELEGATE="PHP"&gt;
		&lt;BEGIN&gt;&amp;lt;?php&lt;/BEGIN&gt;
		&lt;END&gt;?&amp;gt;&lt;/END&gt;
	&lt;/SPAN&gt;

and the corresponding rule function is::

    def php_rule0(colorer, s, i):
        return colorer.match_span(s, i, kind="markup", begin="&lt;?php", end="?&gt;",
            at_line_start=False, at_whitespace_end=False, at_word_start=False,
            delegate="PHP",exclude_match=False,
            no_escape=False, no_line_break=False, no_word_break=False)


php_rule0 calls colorer.match_span because the corresponding xml rule is a &lt;SPAN&gt; element.

For each ruleset, x.py also contains a **rules dictionary**,
a Python dictionary whose keys are characters and whose values are all lists
of rules functions that that can match the key.
For example::

    # Rules dict for phpdoc ruleset.
    rulesDict8 = {
        "*": [rule64,],
        "0": [rule70,],
        "1": [rule70,],
        "2": [rule70,],
        "3": [rule70,],
        "4": [rule70,],
        "5": [rule70,],
        "6": [rule70,],
        "7": [rule70,],
        "8": [rule70,],
        "9": [rule70,],
        "&lt;": [rule65,rule66,rule67,rule68,rule69,],
        "@": [rule70,],
        "A": [rule70,],
        "B": [rule70,],
        ...
        "X": [rule70,],
        "Y": [rule70,],
        "Z": [rule70,],
        "_": [rule70,],
        "a": [rule70,],
        "b": [rule70,],
       ...
        "x": [rule70,],
        "y": [rule70,],
        "z": [rule70,],
        "{": [rule63,],
    }

**Note**: The order of rules in each rules list is important;
it should be the same as rules element in x.xml.

Finally, x.py contains **x.rulesDictDict**.
Keys are ruleset names, values are rules dictionaries.
The colorer can get the rules list for character ch as follows::

    self.rulesDict = x.rulesDictDict.get(rulesetName) # When a mode is inited.
    ...
    rules = self.rulesDict.get(ch,[]) # In the main loop.

For example, here is the rules dictionary for php.py::

    # x.rulesDictDict for php mode.
    rulesDictDict = {
        "php_javascript": rulesDict6,
        "php_javascript_php": rulesDict7,
        "php_main": rulesDict1,
        "php_php": rulesDict4,
        "php_php_literal": rulesDict5,
        "php_phpdoc": rulesDict8,
        "php_tags": rulesDict2,
        "php_tags_literal": rulesDict3,
    }

**Note**:
The jEdit2Py script creates 'friendly' names for rules lists *solely* as an aid for people reading the code.
Leo's colorer uses only the name x.rulesDictDict;
Leo's colorer never uses the actual names of rules lists such as rulesDict8,
and Leo's colorer never uses the actual names of rules functions such as rule64.
</t>
<t tx="ekr.20060502100550">A **ruleset name** is a Python string having the form 'x_setname',
where setname is the value of the SET attribute of the &lt;RULES&gt; element in x.xml.
For example, the ruleset name of the ruleset whose SET attribute is JAVASCRIPT in php.xml is
'php_JAVASCRIPT'.
**Important**: by convention, the ruleset name of the default &lt;RULES&gt; element is 'x_main';
note that default &lt;RULES&gt; element have no SET attributes.

The colorizer uses ruleset names to gain access to all data structures in x.py.
To anticipate a bit, ruleset names are keys into two standard dictionaries,
x.rulesDict and x.keywordsDictDict,
from which the colorizer can get all other information in x.py::

    # The rules list for the 'JAVASCRIPT' ruleset in php.xml.
    rules = x.rulesDict('php_JAVASCRIPT')

    # The keywords dict for the 'JAVASCRIPT' ruleset in php.xml.
    keywordsDict = x.keywordsDictDict('php_JAVASCRIPT')

In fact, ruleset names (and x.rulesDict and x.keywordsDictDict)
are the **only** names that the colorizer needs to know in order to access all information in x.py.
</t>
<t tx="ekr.20060502122950">This section describes each rules method in Leo's new colorizer.
Rules methods are called by rules functions in colorizer control file;
they correspond directly to rules elements in jEdit's language description files.
In fact, this documentation is a 'refactoring' of `jEdit's documentation`_.

All rule methods attempt to match a pattern at a particular spot in a string.
These methods all return True if the match succeeds.
</t>
<t tx="ekr.20060502122950.10">::

    def match_eol_span_regexp (self,s,i,kind,regex,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = '',
        exclude_match = False):

match_eol_span_exp succeeds if:

1. The regular expression regex matches at s[i:], and

2. The at_line_start, at_whitespace_end and at_word_start conditions are all satisfied.

If successful, match_eol_span_regexp  highlights from i to the end of the line.
If the exclude_match argument is True, only the text before the matched text will be colored.
The delegate argument, if present, specifies the ruleset to color the colored text.
</t>
<t tx="ekr.20060502122950.13">::

    def match_keywords (self,s,i):

match_keywords succeeds if s[i:] starts with an identifier contained in the mode's keywords dictionary d.

If successful, match_keywords colors the keyword.
match_keywords does not take a kind keyword argument.
Instead, the keyword is colored as specified by d.get(theKeyword).
</t>
<t tx="ekr.20060502122950.14">::

    def match_mark_following (self,s,i,kind,pattern,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False):

match_mark_following succeeds if s[i:].startswith(pattern), and
the at_line_start, at_whitespace_end and at_word_start conditions are all satisfied.

If successful, match_mark_following colors from i to the start of the next token
with the color specified by kind.
If the exclude_match argument is True, only the text after the matched text will be colored.
</t>
<t tx="ekr.20060502122950.40">::

    def match_seq (self,s,i,kind,seq,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = ''):

match_seq succeeds if s[i:].startswith(seq) and
the at_line_start, at_whitespace_end and at_word_start conditions are all satisfied.

If successful, match_seq highlights from i to the end of the sequence
with the color specified by kind.
The delegate argument, if present, specifies the ruleset to color the colored text.
</t>
<t tx="ekr.20060502122950.41">::

    def match_seq_regexp (self,s,i,kind,regex,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = ''):

match_seq succeeds if:

1. The regular expression regex matches at s[i:], and

2. The at_line_start, at_whitespace_end and at_word_start conditions are all satisfied.

If successful, match_seq_regexp highlights from i to the end of the sequence
with the color specified by kind.
The delegate argument, if present, specifies the ruleset to color the colored text.
</t>
<t tx="ekr.20060502122950.42">::

    def match_span (self,s,i,kind,begin,end,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False,
        delegate = ''
        no_escape = False,
        no_line_break = False,
        no_word_break = False):

match_span succeeds if there is an index j &gt; i such that
s[:i].startswith(begin) and s[i:j].endswith(end) and the
at_line_start, at_whitespace_end, at_word_start,
no_escape, no_line_break and no_word_break conditions are all satisfied.

If successful, match_span highlights from s[i:j
with the color specified by kind;
but if the exclude_match argument is True, the begin and end text are not colored.
The delegate argument, if present, specifies the ruleset to color the colored text.
</t>
<t tx="ekr.20060502122950.47">::

    def match_span (self,s,i,kind,regex,end,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False,
        delegate = ''
        no_escape = False,
        no_line_break = False,
        no_word_break = False):

match_span_regex succeeds if:

1. The regular expression regex matches at s[i:],

2. There is an index j &gt; i such that s[i:j].endswith(end),

3. The at_line_start, at_whitespace_end, at_word_start,
   no_escape, no_line_break and no_word_break conditions are all satisfied.

If successful, match_span colors s[i:j],
with the color specified by kind;
but if the exclude_match argument is True, the begin and end text are not colored.
The delegate argument, if present, specifies the ruleset to color the colored text.
</t>
<t tx="ekr.20060502122950.48">::

    def match_terminate (self,s,i,kind,at_char):

match_terminate succeeds if s[i:] contains at least at_char more characters.

If successful, match_terminate colors at_char characters
with the color specified by kind.
</t>
<t tx="ekr.20060502122950.7">::

    def match_eol_span (self,s,i,kind,begin,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = '',
        exclude_match = False):

match_eol_span succeeds if s[i:].startswith(begin) and
the at_line_start, at_whitespace_end and at_word_start conditions are all satisfied.

If successful, match_eol_span highlights from i to the end of the line
with the color specified by kind.
If the exclude_match argument is True, only the text before the matched text will be colored.
The delegate argument, if present, specifies the ruleset to color the colored text.
</t>
<t tx="ekr.20060502125223">::

    def match_mark_previous (self,s,i,kind,pattern,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False):

match_mark_previous succeeds if s[i:].startswith(pattern),and
the at_line_start, at_whitespace_end and at_word_start conditions are all satisfied.

If successful, match_mark_previous colors from the end of the previous token to i
with the color specified by kind.
If the exclude_match argument is True, only the text before the matched text will be colored.
</t>
<t tx="ekr.20060503064515">All rule methods take three required arguments and zero or more optional keyword arguments.

Here is a list of the required arguments and their meaning:

- **self**: An instance of Leo's colorizer.

- **s**: The string in which matches may be found.

- **i**: The location within the string at which the rule method looks for a match.

Here is a list of all optional keyword arguments and their meaning:

- **at_line_start**:
  If True, a match will succeed only if i is at the start of a line.

- **at_whitespace_end**:
  If True, the match will succeed only if i is at the first non-whitespace text in a line.

- **at_word_start**:
  If True, the match will succeed only if i is at the beginning of a word.

- **delegate**:
  If non-empty, the value of this argument is a `ruleset name`_.
  If the match succeeds, the matched text will be colored recursively with the indicate ruleset.

- **exclude_match**:
  If True, the actual text that matched will not be colored.
  The meaning of this argument varies slightly depending on whether one or two sequences are matched.
  See the individual rule methods for details.

- **kind**: A string representing a class of tokens, i.e., one of:
  'comment1', 'comment2', 'comment3', 'comment4', 'function',
  'keyword1', 'keyword2', 'keyword3', 'keyword4',
  'label', 'literal1', 'literal2', 'literal3', 'literal4',
  'markup', 'null' and 'operator'.

- **no_escape**:
  If True, the ruleset's escape character will have no effect before the end argument to match_span.
  Otherwise, the presence of the escape character will cause that occurrence of the end string to be ignored.

- **no_line_break**:
  If True, the match will not succeed across line breaks.

- **no_word_break**:
  If True, the match will not cross word breaks.

New in Leo 4.4.1 final: the regular expression rule matchers no longer get a hash_char argument
because such matchers are called only if the present search pattern starts with hash_char.
</t>
<t tx="ekr.20060503072213">x.importDict is a Python dictionary.
Keys are ruleset names; values are a list of ruleset names.
For example::

    # Import dict for php mode.
    importDict = {
        "php_javascript_php": ["javascript::main"],
    }

For any ruleset R whose ruleset name is N, x.importDict.get(N)
is the list of rulesets names whose rulesets appear in
a DELEGATE attribute of an &lt;IMPORT&gt; rule element in R's ruleset.
Such **imported** ruleset are copied to the end of the R's rules list.
Leo's colorizer does this copying only once, when loading ruleset R for the first time.

**Note 1**: Loading imported rulesets must be done at 'run time'.
It should definitely not be done by jEdit2Py at 'compile time';
that would require running jEdit2Py on *all* .xml files whenever any such file changed.

**Note 2**:  Multiple &lt;IMPORT&gt; rule elements in a single ruleset are allowed:
delegated rules are copied to the end of N's rules list in the order they appear in the ruleset.

**Note 3**: The DELEGATE attribute of &lt;IMPORT&gt; elements is, in fact,
completely separate from the DELEGATE attributes of other rules as
discussed in `Arguments to rule methods`_.
Indeed, the DELEGATE attribute of &lt;IMPORT&gt; elements creates entries in
x.importDict, which in turn causes the colorizer to append the rules of the imported ruleset
to the end of the present rules list.
In contrast, the DELEGATE attributes of other rules sets the delegate argument to rules methods,
which in tern causes the colorizer to recursively color the matched text with the **delegated** ruleset.
In short:

- The rules of **imported** rulesets are appended to the end of another rules list;
  the rules of **delegated** rulesets never are.

- **Imported** ruleset names appear as the values of items in x.importDict;
  **delegated** ruleset names appear as delegate arguments to rule methods.
</t>
<t tx="ekr.20060510085547">x.py contains a **attribute dictionary** for each ruleset in x.xml.
Keys are attribute names, values strings representing the values of the attributes.
This dictionary is empty if a ruleset contains no attributes.
The valid keys are:

- 'default': the default token type.  'null' is the default.

- 'digit_re': a regular expression.
  Words matching this regular expression are colored with the digit token type.

- 'ignore_case': 'true' or 'false'.  Default is 'true'.

- 'highlight_digits': 'true' or 'false'.  Default is 'true'.

- 'no_word_sep': A list of characters treated as 'alphabetic' characters when matching keywords.

For example, here is one attribute dictionary in php.py::

    # Attributes dict for php_javascript ruleset.
    php_javascript_attributes_dict = {
        "default": "MARKUP",
        "digit_re": "",
        "highlight_digits": "true",
        "ignore_case": "true",
        "no_word_sep": "",
    }

x.py also contains **x.attributesDictDict**.
Keys are ruleset names, values are attribute dictionaries.
Here is attributesDictDict for php.py::

    # Dictionary of attributes dictionaries for php mode.
    attributesDictDict = {
        "php_javascript": php_javascript_attributes_dict,
        "php_javascript_php": php_javascript_php_attributes_dict,
        "php_main": php_main_attributes_dict,
        "php_php": php_php_attributes_dict,
        "php_php_literal": php_php_literal_attributes_dict,
        "php_phpdoc": php_phpdoc_attributes_dict,
        "php_tags": php_tags_attributes_dict,
        "php_tags_literal": php_tags_literal_attributes_dict,
    }

**Note**:
The jEdit2Py script creates 'friendly' names for attribute dictionaries *solely* as an aid for people reading the code.
Leo's colorer uses only the name x.attributeDictDict;
Leo's colorer never uses the actual names of attribute dictionaries.
</t>
<t tx="ekr.20060527103630">A new method has been added to make it more easily to write rST code from scripts::

    c.rstCommands.writeNodeToString(p)

writeNodeToString scans p's tree (p defaults to presently selected node) looking for @rst nodes.
When the first @rst node is found, writeNodeToString processes the node as usual, with the following changes:

- @rst need not be followed by a filename; any filename and its extension are *ignored*.

- Only the ext argument to writeNodeToString determines the type of output produced.
  The valid values for the ext argument are None (for rst output), '.html', '.pdf', and '.tex'.

- Instead of writing the result to a file, writeNodeToString returns the tuple (p,s),
  where p is the node whose tree produced the output, and s is the output itself.

- writeNodeToString returns after processing at most one @rst node.

Scripts can easily use writeNodeToString to convert @rst trees into various kinds of output.
For example::

    p,s = c.rstCommands.writeNodeToString(p,ext='html')

Notes:

- This script scans the presently selected tree for @rst nodes.
  In particular, if the presently selected tree does not contain an @rst node the search continues in parent trees.
  When an @rst node is found, it converts the node (and descendants) to html and returns p,
  the found @rst node and s, the html itself.

- Valid values for the ext argument are ".html", ".tex" or None (specifies rst output)

- There is some support for ext=".pdf", but this is experimental code.  Expect crashes.
</t>
<t tx="ekr.20060527105211" str_atime="1376414159.0"></t>
<t tx="ekr.20060527105617">##################
Debugging with Leo
##################

This chapter discusses debugging Python scripts with Leo.
Be aware of the distinction between **Leo-specific** scripts and **general** scripts.
Leo-specific scripts access data in the Leo outline in which they are contained;
general scripts do not.

.. contents::
    :depth: 3
</t>
<t tx="ekr.20060527105804">.. External links...
.. _Idle:                       http://www.python.org/idle/
.. _pdb:                        http://docs.python.org/lib/module-pdb.html
.. _winpdb:                     http://www.digitalpeers.com/pythondebugger/
.. _`the FAQ`:                  http://leoeditor.com/FAQ.html#how-can-i-use-python-s-pdb-debugger-with-leo
.. _`embedded winpdb`:          http://www.digitalpeers.com/pythondebugger/embedded.htm
.. _`Leo's forums`:             http://sourceforge.net/forum/?group_id=3458
.. _`work flow`:                http://leoeditor.com/FAQ.html#how-can-i-use-leo-to-develop-leo-itself

.. .. _`running Leo in a console`: http://leoeditor.com/FAQ.html#how-can-i-run-leo-from-a-console-window
.. _`running Leo from a console window`:    installing.html#running-leo-from-a-console-window
.. _`run Leo in a console window`:          installing.html#running-leo-from-a-console-window
.. _`console window`:                       installing.html#running-leo-from-a-console-window
</t>
<t tx="ekr.20060527112801">The following settings in leoSettings.leo control debugger operation.
The settings shown here will be assumed to be in effect throughout this chapter::

    @string debugger_kind = winpdb

This setting controls what debugger the 'Debug Script' script button uses.
Eventually this setting will control what debugger the debug command uses::
At present the only valid value is 'winpdb'

    @bool write_script_file = True

True: The execute script command writes the script to be executed to a file,
then executes the script using Python's execFile function. The script_file_path
setting specifies the path to this file. False (legacy): The execute script
command uses Python's exec command to execute the script.

@string script_file_path = ../test/scriptFile.py

The path to the file to be written by the execute-script command. Notes:

- This setting has effect only if the write_script_file setting is True.
- Use / as the path delimiter, regardless of platform.
- The default path is ../test/scriptFile.py if no path is given.
- The path starts at g.app.loadDir, so for example ../test/scriptFile.py is equivalent to leo/test/scriptFile.py.
- The filename should end in .py.

@string debugger_path = None

</t>
<t tx="ekr.20060529053407">@ignore can only be used in the root node of @file trees.  It tells Leo to ignore the tree.

The @ignore directive can not be used elsewhere in @file trees because of the way Leo recreates 
outlines from external files. This is an absolutely crucial restriction and will never go away.
For a few more details, see `Leo 4.0: Eliminating error 'recovery'`_ in `History of Leo`_.

There are several workaround, as shown in LeoPy.leo:

- keep notes in the outline outside of any external file.

- Use @all to gather notes in a external file, as in done in @file leoProjects.txt.
</t>
<t tx="ekr.20060612102055" str_atime="1376414161.0">.. Most of this has nothing to do with *writing* plugins.</t>
<t tx="ekr.20060612103240" str_atime="1376414163.0">###############
Writing Plugins
###############

Plugins modify how Leo works. With plugins you can give Leo new commands,
modify how existing commands work, or change any other aspect of Leo's look
and feel.

leoPlugins.leo contains all of Leo's official plugins. Studying this file is
a good way to learn how to write plugins.

Writing plugins is like writing any other Leo script.  See
`Scripting Leo with Python`_. In particular:

1. Plugins can use any of Leo's source code simply by importing any module
   defined in leoPy.leo.

2. Plugins can register event handlers just like any other Leo script. For full
   details, see the section called `Handling Events`_ later in this chapter.

The rest of this chapters discusses topics related specifically to plugins.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20060612103824">.. External links...
.. _docutils:             http://docutils.sourceforge.net
.. _LaTeX:                http://www.latex-project.org/
.. _reStructuredText:     http://docutils.sourceforge.net/rst.html

.. Relative links...
.. _`Scripting Leo with Python`:    tutorial-scripting.html
.. _`Customizing Leo`:              customizing.html
</t>
<t tx="ekr.20060620094033"></t>
<t tx="ekr.20060620094033.1">The main features of Leo 4.4.1 are:

- Multiple editors in Leo's body pane and
- A new colorizer plugin controlled by jEdit language description files.
- Search commands now support regex replace patterns: \1, \2, etc.
- Support for external debuggers: see http://leoeditor.com/debuggers.html
- The scripting plugin now creates a Debug Script button.
- Several new commands including run-unit-test, python-help and toggle-invisibles.
- The help-for-command commands now contains information for almost all commands.
- A new shortcut_button plugin.
</t>
<t tx="ekr.20060620094033.2">The main features of Leo 4.4 are:

- An Emacs-like mini-buffer: you can now execute any command by typing its long
  name, with tab completion.

- Many new commands, including cursor and screen movement, basic character, word
  and paragraph manipulation, and commands to manipulate buffers, the kill ring,
  regions and rectangles. You can use Leo without using a mouse.

- Flexible key bindings and input modes. You can emulate the operation of Emacs,
  Vim, or any other editor.

- A tabbed log pane. The Find and Spell Check commands now use tabs instead of
  dialogs, making those commands much easier to use. Plugins or scripts can easily
  create new tabs. The Completion tab shows possible typing completions.

- Autocompletion and calltips.  Autocompletion works much like tab completion.
  To enable autocompletion, bind a key to the auto-complete command.

.. .. contents::
</t>
<t tx="ekr.20060620095655">- The print-bindings command now properly sorts bindings.
- The help-for-command command now works for almost all commands.
- Improved filename completion.
- Better listings for print-commands and print-bindings &amp;amp; mode-help commands.
- Allow shortcuts to be overridden outside of leoSettings.leo.
- Finished Cmds menu.
- Improved show-fonts command.
- Strip quotes from color, font settings.
- Warn about invalid Enter and Leave key bindings.
</t>
<t tx="ekr.20060620095949.15">- Removed warning about changed node.
- Added scroll-outline-left/right commands.
- Leo outputs decorators correctly, assuming the decorator does not conflict with a Leo directive.
- Wrote script to convert g.es to g.et where appropriate.
  The first step in translating all Leo messages.
- Leo highlights (flashes) matching brackets when typing typing (, ), [, ], { or }.
- Fixed long-standing problem reporting indentation errors.
- Fixed long-standing bug in Remove Sentinels command.
- Fixed long-standing bugs in import commands.
- The scroll-up/down commands now scroll the outline if focus is in outline pane.
  However, his can be done better using per-pane bindings as in the default leoSettings.leo.
- Incremental searches are (properly) confined to a single body text.
- Backspace now handled properly in incremental searches.
- The add-editor command adds a new editor in the body pane.
  The delete-editor command deletes the presently selected editor,
  and the cycle-editor-focus command cycles focus between editors in the body text.
- The standard \1, \2, etc. replacements can now be performed in regular expression searches.
- The standard escapes \n and \t are now valid in plain searches.
- The shortcut for the replace-string command now changes from the find command
  to the replace command.
</t>
<t tx="ekr.20060620095949.25">::

    @bool autoindent_in_nocolor_mode
    @bool flash_matching_brackets
    @bool idle_redraw
    @bool trace_bind_key_exceptions
    @bool warn_about_redefined_shortcuts
    @color flash_brackets_background_color
    @color flash_brackets_foreground_color
    @int flash-brackets-delay
    @int flash_brackets_count
    @string close_flash_brackets
    @string open_flash_brackets
    @string editor_orientation
</t>
<t tx="ekr.20060620130636">::

    cycle-focus
    debug
    find-character
    find-word
    hide-invisibles 
    isearch-with-present-options
    open-users-guide
    python-help
    run-unit-test
    toggle-autocompleter
    toggle-calltips
    toggle-invisibles
</t>
<t tx="ekr.20060620130943">- The slideshow plugin
- The mod_scripting plugin now creates a press-x-button command for every button 'x'.
  You can specify settings for such commands using @shortcuts nodes.
- The shortcut_button plugin plugin creates a 'Shortcut' button in the icon area.
  Pressing the Shortcut button creates *another* button which when pressed
  will select the presently selected node at the time the button was created.
- Added Debug button to scripting plugin.
</t>
<t tx="ekr.20060620133820.16">- Added script to update new copies of leoSetttings.leo from previous copies.
- Made all edit command undoable.
- Improved registerCommand.
- Suppressed autocompletion after numbers.
- Added colorizing support for Lua language.
- Added run-unit-test command.
- Autocompletion and calltips.
- Leo remembers the previous open directory.
- Fixed problem with view plugin.
- Installed cleo patch.
- User input modes.
- Installed many standard bindings to leoSettings.leo.
- Added Check Bindings script in leoSettings.leo.
- Scripts now maintain original focus.
- Improved cursor move/extend commands.
- Added support for @mode nodes.
- keyboard-quit restores default input mode.
- Created ut.leo, ut.py and ut.bat.
- Added modes/\*.xml to distribution.
- Revised cursor movement commands and added selection-extension commands.
- Added classic key bindings in leoSettings.leo.
- Allow multiple key bindings to the same command.
- Settings command now opens leoSettings.leo.
- Moved all scripts into scripts.leo.
- Improved how the New Tab and Rename Tab commands work in the log pane.
- Improved the appearance of the Spell tab.
- Added Clone-find checkbox to the Find tab.
- Improved find tab.
- Improved formatting of shortcuts in print-commands and print-bindings.
- Added settings for vim plugin.
- Put up a dialog if can't import Pmw.
- Bound &lt;Return&gt; to end-edit-headline.
- Leo now ignores key bindings in menu tables.
- Created scripts.leo and unitTest.leo.
- c.executeMinibufferCommand executes a minibuffer command by name.
- Improved perl entries in language dicts. 
- The tabbed log.
- The Find tab replaces the old Find panel; the old Find panel is deprecated.
</t>
<t tx="ekr.20060620140130">- Changed path to stylesheet in the rst3 plugin.
- Fixed crasher in Word (and other) plugins.
- Fixed problem with labels plugin.
- Added the following commands for the groupoperations plugin::

    group-operations-clear-marked
    group-operations-mark-for-copy
    group-operations-mark-for-move
    group-operations-mark-for-clone
    group-operations-mark-target
    group-operations-operate-on-marked
    group-operations-transfer

- Installed cleo patch.
- The scripting plugin now supports shortcuts in @button nodes::

    @button name @key=shortcut

- The scripting plugin now supports @command nodes::

    @command name @key=shortcut
</t>
<t tx="ekr.20060620140228">Added new settings::

    @bool allow_idle_time_hook
    @bool autocomplete-brackets.
    @bool gc_before_redraw
    @bool minibufferSearchesShowFindTab
    @bool show_only_find_tab_options
    @bool show_tree_stats
    @bool trace_autocompleter
    @bool trace_bindings
    @bool trace_doCommand
    @bool trace_f.set_focus
    @bool trace_focus
    @bool trace_g.app.gui.set_focus
    @bool trace_gc
    @bool trace_gc_calls
    @bool trace_gc_verbose
    @bool trace_key_event
    @bool trace_masterClickHandler
    @bool trace_masterCommand
    @bool trace_masterFocusHandler
    @bool trace_masterKeyHandler
    @bool trace_minibuffer
    @bool trace_modes
    @bool trace_redraw_now
    @bool trace_select
    @bool trace_status_line
    @bool trace_tree
    @bool trace_tree_alloc
    @bool trace_tree_edit
    @bool useCmdMenu
    @bool useMinibuffer
    @bool use_syntax_coloring
    @color body_text_selection_background_color
    @color body_text_selection_foreground_color.
    @color log_pane_Find_tab_background_color
    @color log_pane_Spell_tab_background_color, etc.
    @int max_undo_stack_size,
    @string trace_bindings_filter
    @string trace_bindings_pane_filter

- Added @shortcuts nodes.
- Leo now supports per-pane bindings of the form::

    command-name ! pane = shortcut

- The spelling settings replace the settings in spellpyx.ini.
</t>
<t tx="ekr.20060629083935">Leo 4.4 was a year-long effort to incorporate an Emacs-style minibuffer and
related commands into Leo. Thinking in terms of minibuffer commands frees my
thinking. Leo 4.4 also featured many improvements in how keys are bound to
commands, including per-pane bindings and user-defined key-binding modes.

Development on long-delayed projects accelerated after 4.4 final went out the door.
Recent projects include:

- Controlling syntax coloring with jEdit's xml language-description files.
- Support for debugging scripts using external debuggers.
- Modifying Leo's vnodes and tnodes so that Leo's data can be used with ZODB.
- Using pymacs to write Leo scripts within Emacs.
- Using the leoBridge module to embed Leo support in other programs.
- Using Leo to run unit tests.

</t>
<t tx="ekr.20060805094325">You can 'revert' to old key bindings as follows:

1. Open leoSettings.leo.

2. Find the node 'Keyboard shortcuts'.

3. Disable the old bindings by moving the node
   '@keys EKR bindings: Emacs keys + modes'
   so that it is a child of the node:
   '@ignore Unused key bindings'.

4. Notice that there are two child nodes of the node
   '@ignore Unused key bindings'
   that refer to legacy key bindings:

   - '@keys Legacy Leo shortcuts with important Emacs bindings'

   - '@keys Legacy Leo bindings'.

5. Move **one** of these two legacy nodes up one level so that it is a child of the node
   'Keyboard shortcuts'.
   It should **not** be a child of the node
   '@ignore Unused key bindings'.
</t>
<t tx="ekr.20060822111759">By Rich Ries

There is no direct way to make script buttons available in multiple Leo files.
Sure, you could copy and paste the @button nodes, but there is a slightly
easier way using the "New Buttons" plugin.

1) Create and test and debug your desired Script Button.

2) With the Script Button node selected, run Plugins --&gt; New buttons --&gt; Make Template From

Open a new Leo file.

3) Assuming you have only the one New Button Template defined, left-click the
   New button, and a new node will be added to your outline. (Otherwise, you'll
   need to select the Template you want.)

4) Press [Script Button] to create the new script button.

It's easier to *do* this than to *explain* it!
</t>
<t tx="ekr.20060830142929">This section discusses only those settings that affect syntax coloring.
See `Customizing Leo`_ for a general discussion of Leo's settings.

Both the old colorizer (in Leo's core) and the new colorizer (the
threading_colorizer and qtGui plugins) now support \@color and \@font settings for colorizing
options. The settings for the old colorizer are::

    comment_font, cweb_section_name_font, directive_font,
    doc_part_font, keyword_font, leo_keyword_font, section_name_font,
    section_name_brackets_font, string_font, undefined_section_name_font,
    latexBackground_font, and latex_background_font.

The settings for the new colorizer are all of the above (except keyword_font) plus the following::

    comment1_font, comment2_font, comment3_font, comment4_font, function_font,
    keyword1_font, keyword2_font, keyword3_font, keyword4_font, label_font,
    literal1_font, literal2_font, literal3_font, literal4_font, markup_font,
    null_font, and operator_font.
    
To specify a color, say for comment1, for *all* languages, create an @color node::

    @color comment1_color = blue
    
To specify a color for a **particular** language, say Python, prepend the setting name
with the language name.  For example::

    @color python_comment1_color = pink

To specify a font, say for keyword_font, to be used as the default font for **all** languages,
put the following in the body text of an @font node in leoSettings.leo::

    # keyword_font_family = None
    keyword_font_size = 16
    keyword_font_slant = roman
        # roman, italic
    keyword_font_weight = bold
        # normal, bold

Comments are allowed and undefined settings are set to reasonable defaults. 
At present, comments can not follow a setting: comments must start a line.

You can specify per-language settings by preceding the settings names by a prefix x.
Such settings affect only colorizing for language x (i.e., all the modes in modes/x.py when using the new colorizer).
For example, to specify a font for php (only), put the following in the body text of an @font node in leoSettings.leo::

    # php_keyword_font_family = None
    php_keyword_font_size = 16
    php_keyword_font_slant = roman
        # roman, italic
    php_keyword_font_weight = bold
        # normal, bold
</t>
<t tx="ekr.20060913164304"></t>
<t tx="ekr.20060913164304.1">###################
Using ZODB with Leo
###################

This chapter discusses how to write Leo scripts that store and retrieve data using ZODB_.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20060913164311">.. External links...
.. _ZODB:               http://www.zope.org/Wikis/ZODB/guide/zodb.html
.. _`Installing ZODB`:  http://www.zope.org/Wikis/ZODB/guide/node3.html#SECTION000310000000000000000
</t>
<t tx="ekr.20060913165542.1"></t>
<t tx="ekr.20060913165542.2">This function inits the zodb.
pathToZodbStorage is the full path to the zodb storage file.
You can call g.init_zodb as many times as you like.
Only the first call for any path actually does anything:
subsequent calls for a previously opened path simply return the same value as the first call.
</t>
<t tx="ekr.20060913165542.3">This vnode method returns v2, a copy of v that is completely detached from the
outline. v2.fileIndex is unrelated to v.fileIndex initially, but it may be
convenient to copy this field::

    v2 = v.detach()
    v2.fileIndex = v.fileIndex
</t>
<t tx="ekr.20060913170145">To enable zodb scripting within Leo, you must set use_zodb = True in the root node of leoNodes.py.
You must also install ZODB itself.  See `Installing ZODB`_ for details.

When ZODB is installed and use_zodb is True,
Leo's vnode class becomes a subclass of ZODB.Persistence.Persistent.
This is all that is needed to save/retrieve vnodes or tnodes to/from the ZODB.

**Important notes**:

- Scripts **should not** store or retrieve positions using the ZODB!
  Doing so makes sense neither from Leo's point of view nor from ZODB's point of view.

- The examples below show how to store or retrieve Leo data by accessing the
  so-called root of a ZODB connection. However, these are only examples. Scripts
  are free to do with Leo's vnodes *anything* that can be done with
  ZODB.Persistence.Persistent objects.
</t>
<t tx="ekr.20060913170403">Scripts should call g.init_zodb to open a ZODB.Storage file.
g.init_zodb returns an instance of ZODB.DB.  For example::

    db = g.init_zodb (zodbStorageFileName)

You can call g.init_zodb as many times as you like.
Only the first call for any path actually does anything:
subsequent calls for a previously opened path simply return the same value as the first call.
</t>
<t tx="ekr.20060913170403.1">The following script writes v, a tree of vnodes, to zodb::

    db = g.init_zodb (zodbStorageFileName)
    connection = db.open()
    try:
        root = connection.root()
        root[aKey] = v # See next section for how to define aKey.
    finally:
        get_transaction().commit()
        connection.close()

Notes:

- v must be a vnode.
  Scripts should *not* attempt to store Leo positions in the zodb.
  v can be the root of an entire outline or a subtree.
  For example, either of the following would be reasonable::

    root[aKey] = c.rootPosition().v
    root[aKey] = c.p.v

- To write a single vnode without writing any of its children you can use v.detach.
  For example::

    root[aKey] = v.detach()

- **Important**: It is simplest if only one zodb connection is open at any one time,
  so scripts would typically close the zodb connection immediately after processing the data.
  The correct way to do this is in a finally statement, as shown above.

- The script above does not define aKey.
  The following section discusses how to define reasonable zodb keys.
</t>
<t tx="ekr.20060913170403.2">The following script reads a tree of vnodes from zodb and sets p as the root position of the tree::

    try:
        connection = db.open()
        root = connection.root()
        v = root.get(aKey)
        p = leoNodes.position(v)
    finally:
        get_transaction().commit()
        connection.close()
</t>
<t tx="ekr.20060913175437">The keys used to store and retrieve data in connection.root() can be any string that uniquely identifies the data.
The following are only suggestions; you are free to use any string you like.

1. When saving a file, you would probably use a key that is similar to a real file path.
   For example::

        aKey = c.fileName()

2. When saving a single vnode or tree of vnodes, say v,
   a good choice would be to use v's gnx, namely::

        aKey = g.app.nodeIndices.toString(v.fileIndex)

   Note that v.detach() does not automatically copy v.fileIndex to the detached node,
   so when writing a detached node you would typically do the following::

       v2 = v.detach()
       v2.fileIndex = v.fileIndex
       aKey = g.app.nodeIndices.toString(v2.fileIndex)
</t>
<t tx="ekr.20060913175437.1">The scripts shown above close the zodb connection after processing the data.
This is by far the simplest strategy.
I recommend it for typical scripts.

**Important**: you must **leave the connection open** if your script modifies persistent data in any way.
(Actually, this statement is not really true,
but you must define zodb transaction managers if you intend to use multiple connections simultaneously.
This complication is beyond the scope of this documentation.)
For example, it would be possible to create a new Leo outline from the data just read,
but the script must leave the connection open.
I do not recommend this tactic, but for the adventurous here is some sample code::

    connection = self.db.open()
    root = connection.root()
    v = root.get(fileName)
    if v:
        c2 = c.new()
        c2.openDirectory = c.openDirectory # A hack.
        c2.mFileName = fileName # Another hack.
        c2.beginUpdate()
        try:
            c2.setRootVnode(v)
            c2Root = c2.rootPosition()
            c2.atFileCommands.readAll(c2Root)
            g.es_print('zodb read: %s' % (fileName))
        finally:
            c2.endUpdate()
        # Do *not* close the connection while the new Leo window is open!
    else:
        g.es_print('zodb read: not found: %s' % (fileName))


This will work **provided** that no other zodb connection is ever opened while this connection is opened.
Unless special zodb precautions are taken (like defining zodb transaction managers)
calling get_transaction().commit() will affect **all** open connections.
You have been warned.
</t>
<t tx="ekr.20060915112109">Find the @file leoApp.py node in leoPy.leo.
In the ctor for the LeoApp class set self.use_psyco to True or False.
You will find this ctor in the node::

    Code--&gt;Core classes...--&gt;@file leoApp.py--&gt;app.__init__

Note that this ivar can not be set using settings in leoSettings.leo because
Leo uses g.app.use_psyco before processing configuration settings.
</t>
<t tx="ekr.20060917130130">Add the following to the start of your scripts::

    @first # -*- coding: utf-8 -*-

Without this line, constructs such as::

    u = u'a-(2 unicode characters here)-z'
    u = 'a-(2 unicode characters here)-z'

will not work when executed with Leo's execute script command.
Indeed, the Execute Script command creates the script by writing the tree
containing the script to a string. This is done using Leo's write logic, and
this logic converts the unicode input to a utf-8 encoded string. So *all
non-ascii characters* get converted to their equivalent in the utf-8 encoding. 
Call these encoding &lt;e1&gt; and &lt;e2&gt;. In effect the script becomes::

    u = u'a-&lt;e1&gt;-&lt;e2&gt;-z'
    u = 'a-&lt;e2&gt;-&lt;e&gt;-z'

which is certainly *not* what the script writer intended!
Rather than defining strings using actual characters, Instead, one should use
the equivalent escape sequences. For example::

    u = u'a-\\u0233-\\u8ce2-z'
    u = 'a-\\u0233-\\u8ce2-z'
</t>
<t tx="ekr.20060921064744.1">This section describe the format of external files. Leo's `sentinel lines`_ are
comments, and this section describes those comments.

Files derived from @file use gnx's in \@+node sentinels. Such gnx's permanently
and uniquely identify nodes. Gnx's have the form::

    id.yyyymmddhhmmss
    id.yyyymmddhhmmss.n

The second form is used if two gnx's would otherwise be identical.

- id is a string unique to a developer, e.g., a cvs id.

- yyyymmddhhmmss is the node's creation date.

- n is an integer.

Here are the sentinels used by Leo, in alphabetical order.
Unless otherwise noted, the documentation applies to all versions of Leo.
In the following discussion, gnx denotes a gnx as described above.

\@&lt;&lt;
    A sentinel of the form @&lt;&lt;section_name&gt;&gt; represents a section reference.

    If the reference does not end the line,
    the sentinel line ending the expansion is followed by the remainder of the reference line.
    This allows the Read code to recreate the reference line exactly.

\@@
    The \@@ sentinel represents any line starting with @ in body text
    except \@*whitespace*, @doc and @others.
    Examples::

      @@nocolor
      @@pagewidth 80
      @@tabwidth 4
      @@code

\@afterref
    Marks non-whitespace text appearing after a section references.

\@+all
    Marks the start of text generated by the \@all directive.

\@-all
    Marks the end of text generated by the \@all directive.

\@at and \@doc

    The \@+doc \@+at sentinels indicate the start of a doc parts.

    We use the following **trailing whitespace convention** to
    determine where putDocPart has inserted line breaks::

        A line in a doc part is followed by an inserted newline
        if and only if the newline if preceded by whitespace.

    To make this convention work, Leo's write code deletes the trailing
    whitespace of all lines that are followed by a "real" newline.

\@+body **(Leo 3.x only)**
    Marks the start of body text.

\@-body **(Leo 3.x only)**
    Marks the end of body text.

\@delims
    The \@delims directive inserts \@@delims sentinels into the external file.
    The new delimiter strings continue in effect until the next \@@delims sentinel
    *in the external file* or until the end of the external file.
    Adding, deleting or changing \@@delim *sentinels* will destroy Leo's ability to read the external file.
    Mistakes in using the \@delims *directives* have no effect on Leo,
    though such mistakes will thoroughly mess up a external file as far as compilers,
    HTML renderers, etc. are concerned. 

\@+leo
    Marks the start of any external file. This sentinel has the form::

        &lt;opening_delim&gt;@leo&lt;closing_delim&gt;

    The read code uses single-line comments if &lt;closing_delim&gt; is empty.
    The write code generates single-line comments if possible.

    The \@+leo sentinel contains other information. For example::

        &lt;opening_delim&gt;@leo-ver=4-thin&lt;closing_delim&gt;

\@-leo
    Marks the end of the Leo file.
    Nothing but whitespace should follow this directive.

\@+middle **(Leo 4.0 and later)**
    Marks the start of intermediate nodes between the node that
    references a section and the node that defines the section.
    Typically no such sentinels are needed:
    most sections are defined in a direct child of the referencing node.

\@-middle **(Leo 4.0 and later)**
    Marks the end of intermediate nodes between the node that
    references a section and the node that defines the section.

\@+node
    Mark the start and end of a node.

        @+node:gnx:&lt;headline&gt;

\@others
    The @+others sentinel indicates the start of the expansion of an \@+others directive,
    which continues until the matching \@-others sentinel.

\@verbatim
    @verbatim indicates that the next line of the external file is not a sentinel.
    This escape convention allows body text to contain lines that would otherwise
    be considered sentinel lines.

\@@verbatimAfterRef
    @verbatimAfterRef is generated when a comment following a section reference would
    otherwise be treated as a sentinel. In Python code, an example would be::

      &lt;&lt; ref &gt;&gt; #+others
</t>
<t tx="ekr.20060928172457"></t>
<t tx="ekr.20060928172457.4">- Added support for controlling Leo from Emacs_ with pymacs_.
  See the `Leo and Emacs`_ chapter for full details.
- Added Minibuffer and Settings submenus of the Cmds menu.
- At long last Leo creates a proper help menu on the Mac.
- Added a new convention for menu tables. If the first item (a string
  representing the menu label) starts with '*' Leo will convert hyphens to
  spaces and upcase the label. This convention allows a single string to
  represent both the menu label and its associated minibuffer command. As part
  of this reorganization, all menu tables in Leo's core now use only strings.
  This is an essential precondition to supporting @menu nodes in
  leoSettings.leo.
- Leo's Help menu now contains the Open scripts.leo command.
- Leo uses ctypes to import Aspell when run from Python 2.5 or later.
  Leo no longer needs Python-specific versions of aspell.dll.
- Added support for x-windows middle-button paste.
  This only works when the paste is made in the pane containing the selected text.
- Leo looks for myLeoSettings.leo files in the same place Leo looks for leoSettings.leo files.
- Created three scripts (in test.leo) that help create unit tests for Leo's edit commands.
  Create Created runEditCommandTest for use by these scripts.
- Improved print-bindings command.
  The bindings are sorted by prefix: this is a big help in understanding bindings.
  For each prefix, first print items with only a single character after the prefix.
- Made writing .leo files faster.
  The new code almost exactly twice as fast as the old.
- Added p.archivedPosition.
  This is a key first step towards Leap 204.
- Integrated sax with read logic.
- You can now store settings in myLeoSettings.leo without fear of those settings
  being changed by cvs updates or in future versions of Leo.
- Eliminated unnecessary redraws when moving the cursor in the outline pane.
- Much faster navigation through the outline using Alt-arrow keys.
- When focus is in the outline pane, you can move to headlines by typing the first letter of headlines.
- The find command now closes nodes not needed to show the node containing the present match.
- Numerous changes that make Leo easier to use without using a mouse.
- Many new minibuffer commands now appear in the Cmds menu.

Further improved outline navigation:

- Generalized navigation in outline pane to ignore @file, @thin, etc prefixes.
- Made outline navigation cumulative.
  When keystrokes in the outline pane are typed 'close' together Leo first tries to look
  for prefix + ch, where ch is the character just typed and prefix is the previous match.
  The term 'close together' is specified by the setting @float outline_nav_extend_delay.
  The outline search revers to a single-character if the extended search
  fails, so in fact the delay is not too significant. In practice everything works
  well without me thinking at all about what is happening.
</t>
<t tx="ekr.20060928172457.5">- Improved the mod_scripting plugin. Every button created by the plugin creates
  a corresponding command. The command name is the 'cleaned' version of the
  button name. Likewise, the plugin also creates a delete-x-button command,
  where x is the command name as just discussed. So now you can delete script
  buttons without right-clicking.
- Made 'About Plugin' dialog scrollable.
- Fixed bugs in groupoperations, multifile, nodenavigator and shortcut_button plugins.
- The rst3 plugin now registers the rst3-process-tree command.
- The leoOPML.py plugin defines commands to read and write OPML files.
- The slideshow.py plugin allows Leo to run slideshows defined by @slideshow and @slide nodes.
- The leo_to_rtf and leo_to_html plugins create rtf and html files from Leo outlines.
- The paste_as_headlines.py plugins creates multiple headlines at once.
- The word_count.py plugin.

Improved the mod_scripting plugin:

- Made showing the Run Script button optional.
- The Script Button button now creates the press-script-button-button command.
- A new utility method does a much better job of massaging button and command names.
</t>
<t tx="ekr.20060929043325">Leo's vnode and tnode classes are now completely independent of the rest of Leo.
Some api's have been changed.  This 'big reorg' and may affect scripts and plugins.
</t>
<t tx="ekr.20060929043325.1">Leo's vnode and tnode classes can optionally be compatible with ZODB databases,
i.e., they can optionally derive from ZODB.Persistence.Persistent.
See Chapter 17: Using ZODB with Leo for details.
</t>
<t tx="ekr.20061009111417.11">- Removed .leoRecentFiles.txt from the distribution and cvs and added @bool
  write_recent_files_as_needed. The presence or absence of .leoRecentFiles.txt
  no longer controls whether Leo creates and updates .leoRecentFiles.txt.
- Added @bool insert_new_nodes_at_end.
- Added @bool select_all_text_when_editing_headlines.
  Creating a new node always selects the entire text, regardless of this option.
- Leo looks for myLeoSettings.leo files in the same place Leo looks for leoSettings.leo files.
- Added settings for all mod_scripting switches.
- Added @bool collapse_nodes_during_finds.
  This greatly speeds searches that used to open many nodes.
  See: http://sourceforge.net/forum/message.php?msg_id=3935780
- Added @bool outline_pane_has_initial_focus.
- Added @bool sparse_move_outline_left.
- Added bindings for Alt-Shift-Arrow keys to force an outline move.
- Added @bool use_sax_based_read = False.
  True:  Use a sax-based parser to read .leo files.
  This is slower than using Leo's legacy xml parser, but may solve some unicode problems.

Changed default settings::

    focus-to-body = Alt-D
    focus-to-tree = Alt-T
    toggle-extend-mode = Alt-3
</t>
<t tx="ekr.20061009111417.18">::

    extend-to-line
    extend-to-paragraph
    extend-to-sentence
    forward-end-word
    forward-end-word-extend-selection
</t>
<t tx="ekr.20061021164213">Set @bool ignore_unbound_non_ascii_keys = False in LeoSettings.leo or myLeoSettings.leo.
</t>
<t tx="ekr.20061025065357"></t>
<t tx="ekr.20061025065357.1">#############
Leo and Emacs
#############

This chapter several topics relating to the Emacs editor.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20061025065357.2">.. Links
.. _elisp:              http://en.wikipedia.org/wiki/Emacs_Lisp
.. _Emacs:              http://www.xemacs.org/
.. _ZODB:               http://www.zope.org/Wikis/ZODB/guide/zodb.html
.. _`Installing ZODB`:  http://www.zope.org/Wikis/ZODB/guide/node3.html#SECTION000310000000000000000
.. _pymacs:             http://pymacs.progiciels-bpi.ca/index.html
.. _`Customizing Leo`:  customizing.html
</t>
<t tx="ekr.20061025070825.1">The leoPymacs module is intended to be called from Emacs using pymacs.  It contains the following top-level functions:

- get_app()

  Returns the hidden app created by the leoPymacs.init function.

- dump(anyPythonObject)

  Returns str(repr(anyPythonObject)).

- get_g()

  Returns the leoGlobals module of the hidden app created by the leoPymacs.init function.

- get_script_result()

  Returns g.app.scriptResult, where g.app is the hidden app.

- init()
  Calls leo.run(pymacs=True) to create a hidden Leo application.
  Later calls to open can open hidden Leo outlines that can be accessed via runScript.

- open(fileName)

  Opens the .leo file given by fileName.
  fileName must be the full path to a .leo file.
  Returns the commander of the open Leo outline, or None if the outline could not be opened.

- run_script(c,script,p=None)

  Executes a script in the context of a commander c returned by the leoPymacs.open.
  c may be None, in which case a dummy commander is created in which to run the script.
  In the executed script, p is set to c.p if no p argument is specified.
  Returns g.app.scriptResult, where g.app is the hidden app.
</t>
<t tx="ekr.20061025081359">Leo's leoPymacs module is a simple 'server' for the pymacs_ package.
Using pymacs and leoPymacs, elisp_ scripts in Emacs_ can open .leo files and execute *Python* scripts
as if they were executed inside Leo.
In particular, such scripts can use Leo's predefined c, g and p variables.
Thus, *Python* scripts running in Emacs can:

- Open any .leo file. 
- Access any part of the outline. 
- Change any part of the outline, including external files, 
- Save .leo files.
- Execute *any* Leo script.

In short, you can now do from Emacs anything that you can do with Leo scripting inside Leo.

Here are step-by-step instructions for executing Python scripts in Emacs:

**Step 1. Install pymacs** 

   The pymacs installation instructions should be clear enough.
   A clarification is needed about two-way communication between Python and lisp scripts:
   in truth, Python scripts can call the Pymacs.lisp function *only* if the Python script
   was invoked from emacs.
   Otherwise, calling Pymacs.lisp will hang the process making the call.
   For example, executing the following script as an ordinary Leo script will hang Leo::

        from Pymacs import lisp
        print lisp("""2+2""") # Hangs

**Step 2. Load the leoPymacs module from Emacs, creating a hidden Leo application**

  From inside Emacs, you load Leo's leoPymacs module as follows::

    (pymacs-load "leoPymacs" "leo-")

  The call to pymacs-load is similar to 'import leoPymacs as leo-' in Python.
  The side effect of pymacs-load is to define the elisp function leo-x for every top-level function x in leoPymacs.py,
  namely leo-dump, leo-get-app, leo-get-g, leo-get-script-result, leo-init, leo-open and leo-run-script.
  The first call to any of these functions creates a **hidden Leo application**
  in which .leo files may be loaded, modified and saved,
  and in which Leo scripts may be executed.
  This hidden Leo application uses Leo's nullGui class as its gui,
  so Leo commands and Leo scripts that require a fully functional gui will not work as
  expected in the hidden Leo application.
  Steps 3 and 4 tell how to use this hidden Leo application.

  pymacs-load works like a Python reload, so you can redefine leoPymacs.py while Emacs is running.
  However, calling pymacs-load destroys the old hidden Leo application and creates a new one,
  so typically you would want to call pymacs-load only once per Emacs session.
  Like this::

        (setq reload nil) ; change nil to t to force a reload.

        (if (or reload (not (boundp 'leoPymacs)))
            (setq leoPymacs (pymacs-load "leoPymacs" "leo-"))
            (message "leoPymacs already loaded")
        )

**Step 3. From Emacs, open .leo files**

   Once we have loaded the leoPymacs module
   we can open a .leo file as follows::

    (setq c (leo-open fileName))

   This binds the elisp c variable to the Leo commander created by opening fileName.
   fileName should be the full path to a .leo file.
   In the next step we will use this c variable to execute *Leo* scripts in the
   context of an open Leo outline.

   Sometimes we want to execute a Leo script before opening any Leo commanders.
   For example, we might want to compute the fileName passed to leo-open.
   leo-run-script allows the c argument to be nil,
   in which case leo-run-script creates a dummy commander in which to run the script.
   For example, the following script calls g.os_path_join and g.os_path_abspath::

        (setq script "g.app.scriptResult =
            g.os_path_abspath(g.os_path_join(
                g.app.loadDir,'..','test','ut.leo'))"
        )

        (setq fileName (leo-run-script nil script))

   leo-run-script returns the value of g.app.scriptResult
   As shown above, Python scripts may set g.app.scriptResult to indicate their result.
   elisp scripts can also get g.app.scriptResult using leo-script-result.
   Note that the Python script may span multiple lines.

**Step 4. From Emacs, execute Leo (Python) scripts**

   From emacs we can execute a Python script **as if** it were executed in an
   open Leo outline.
   Suppose aLeoScript is an **elisp** string containing a Leo (Python) script.
   We can execute that script in the hidden Leo application as follows::

        (leo-run-script c aLeoScript)

   For example::

        (setq c (leo-open fileName)
        (csetq script "print 'c',c,'h',c.p.h")
        (leo-run-script c script)

Putting this all together, we get::

        ; Step 1: load leoPymacs if it has not already been loaded.
        (setq reload nil)
        (if (or reload (not (boundp 'leoPymacs)))
            (setq leoPymacs (pymacs-load "leoPymacs" "leo-"))
            (message "leoPymacs already loaded")
        )

        ; Step 2: compute the path to leo/test/ut.leo using a Leo script.
        (setq script
            "g.app.scriptResult = g.os_path_abspath(
                g.os_path_join(g.app.loadDir,'..','test','ut.leo'))"
        )
        (setq fileName (leo-run-script nil script))

        ; Step 3: execute a script in ut.leo.
        (setq c (leo-open fileName))
        (setq script "print 'c',c.shortFileName() ,'current:',c.p.h")
        (leo-run-script c script)
</t>
<t tx="ekr.20061025142434">Leo's mini-buffer is a text area at the bottom of the body pane.
You use Leo's minibuffer like the Emacs mini-buffer to invoke commands by their so-called *long name*.
The following commands affect the minibuffer:

- **full-command**: (default shortcut: Alt-x) Puts the focus in the minibuffer. Type a
  full command name, then hit &lt;Return&gt; to execute the command. Tab completion
  works, but not yet for file names.

- **quick-command-mode**: (default shortcut: Alt-x) Like Emacs Control-C. This mode is
  defined in leoSettings.leo. It is useful for commonly-used commands.

- **universal-argument**: (default shortcut: Alt-u) Like Emacs Ctrl-u. Adds a repeat
  count for later command. Ctrl-u 999 a adds 999 a's.

- **keyboard-quit**: (default shortcut: Ctrl-g) Exits any minibuffer mode and puts
  the focus in the body pane.

For example, to print a list of all commands type Alt-X print-commands &lt;Return&gt;.
</t>
<t tx="ekr.20070115172724">The following three section discuss three ways of debugging scripts with winpdb_.
The first two sections tell how to debug general scripts;
the last section tells how to debug Leo-specific scripts.

winpdb_ and its documentation have been improved recently.
For more details, see the `embedded winpdb`_ docs.
The discussion of embedded debugging may have been written specifically with Leo in mind.
</t>
<t tx="ekr.20070115172724.1">This way of debugging can only be used for general scripts, not leo-specific scripts.  
The debug command writes the script to scriptFile.py and invokes winpdb.
winpdb opens and is already 'attached' to the script to be debugged.
You can single-step as you like.
Leo continues to run, but killing the debugger will also kill Leo.
</t>
<t tx="ekr.20070115172724.3">This way of debugging scripts allows winpdb to debug scripts that use c, g and p.
A bit more work is needed because winpdb does not start automatically.
Here are step-by step instructions:

1. Insert the following two lines of code at the start of the script to be debugged::

    import rpdb2
    rpdb2.start_embedded_debugger('go',fAllowUnencrypted=True)

2. Execute Leo's execute-script command (*not* the debug command).
   Leo will appear to hang: start_embedded_debugger is waiting for *another* copy of winpdb to 'attach' to the script's process.
   The default timeout is 5 minutes, after which an exception gets thrown.

3. Start winpdb explicitly by executing something like the following in a console::

    python /Python26/Scripts/_winpdb.py -t

   The -t option tells winpdb that no encoding of password is necessary.
   The password is specified in the call to rpdb2.start_embedded_debugger in your script.
   In our example, the password is 'go'.

4. Use winpdb's File:Attach command to attach winpdb to Leo.
   Specify the password as 'go' and you will see the scriptFile.py containing your entire script.
   You can now execute or single-step through the script. 
   To repeat, c, g and p are defined, so you can debug any script this way.
</t>
<t tx="ekr.20070116062405">Inserting g.trace statements in my Python code is usually my first debugging
choice. The g.trace statement prints the name of the function in which the call
to g.trace occurs, followed by the value of its arguments. The output of the
g.trace goes to the console, so you must `run Leo in a console window`_ to use
g.trace.

Inserting and deleting g.trace statements is fast, provided that your `work
flow`_ makes it easy to restart the program under test. As a result, using
g.trace statements is similar to setting tracepoints in a debugger, with the
advantage that (disabled) tracepoints remain in the source code for future use.
You will find many examples of using g.trace throughout Leo's source code.

My second choice is using g.pdb to set breakpoints for the pdb_ debugger. Pdb
uses the console for all interaction, so you must `run Leo in a console window`_.
See `the FAQ`_ for a discussion of both g.trace and g.pdb.
</t>
<t tx="ekr.20070120075236">The execute-script command predefines the symbols c, g and p.

c is the **commander** of the outline containing the script.

- Commanders are instances of the Commands class, defined in leoCommands.py.

- Commanders provide access to all outline data *and* all of Leo's source code.

g is Leo's **leo.core.leoGlobals** module.

- This module contains many useful functions, including g.es.

p is the **position** of the presently selected node.

- positions are instances of the position class, defined in leoNodes.py.

- The position class provides safe, convenient ways of accessing and
  modifying outline nodes.

- For any position p, p.v is a **vnode** object.

- vnodes contain all the permanent data in a Leo outline.

The next two sections are crucial: they discuss vnodes and positions in all
necessary detail.
</t>
<t tx="ekr.20070122093626">Positions become invalid whenever the outline changes. 

This script finds a position p2 having the same vnode as an invalid
position p::

    if not c.positionExists(p):
        for p2 in c.all_positions():
            if p2.v == p.v: # found
                c.selectPosition(p2)
        else:
            print('position no longer exists')
</t>
<t tx="ekr.20070317033759"></t>
<t tx="ekr.20070317033759.1">#######################################
Embedding Leo with the leoBridge module
#######################################

The leoBridge module allows complete access to all aspects of Leo from other
Python programs running independently of Leo. Let us call such a program a
**host** program. Using the leoBridge module, host programs can get access to:

- all of Leo's source code,
- the contents of any .leo file,
- the commander of any .leo file.

.. contents::
    :depth: 2

</t>
<t tx="ekr.20070317033759.2">.. Links
</t>
<t tx="ekr.20070317033759.3">Host programs use the leoBridge module as follows::

    import leo.core.leoBridge as leoBridge
    
    controller = leoBridge.controller(gui='nullGui',
        loadPlugins=True,  # True: attempt to load plugins.
        readSettings=True, # True: read standard settings files.
        silent=False,      # True: don't print signon messages.
        verbose=False)     # True: print informational messages.

    g = controller.globals()
    c = controller.openLeoFile(path)

Let us look at these statements in detail. The first two statements
import the leoBridge module and create a **bridge controller**. In
effect, these statements embed an invisible copy of Leo into the host
program. This embedded copy of Leo uses a null gui, which simulates
all aspects of Leo's normal gui code without creating any screen
objects.

The statement::

    g = controller.globals()

provides access to Leo's leoGlobals module, and properly inits globals such as
g.app, g.app.gui, etc. *Host programs should not import leoGlobals directly*,
because doing so would not init the g.app object properly.

The statement::

    c = controller.openLeoFile(path)

invisibly opens the .leo file given by the path argument. This call returns a
completely standard Leo commander, properly inited. This is the big payoff from
the leoBridge module: the host program gets instant access to c.config.getBool,
etc. Do you see how sweet this is?

For example, the following script runs leo/test/leoBridgeTest.py outside of Leo.
leoBridgeTest.py uses the leoBridge module to run all unit tests in leo/test/unitTest.leo::

    import os,sys

    path = g.os_path_abspath(
        g.os_path_join(
            g.app.loadDir,'..','test','leoBridgeTest.py'))

    os.system('%s %s' % (sys.executable,path))

The file leo/test/test.leo contains the source code for leoBridgeTest.py.
Here it is, stripped of its sentinel lines::

    '''A program to run unit tests with the leoBridge module.'''

    import leo.core.leoBridge as leoBridge
    import leo.core.leoTest as leoTest

    def main ():
        tag = 'leoTestBridge'

        # Setting verbose=True prints messages that would be sent to the log pane.
        bridge = leoBridge.controller(gui='nullGui',verbose=False)
        if bridge.isOpen():
            g = bridge.globals()
            path = g.os_path_abspath(g.os_path_join(
                g.app.loadDir,'..','test','unitTest.leo'))
            c = bridge.openLeoFile(path)
            g.es('%s %s' % (tag,c.shortFileName()))
            runUnitTests(c,g)

        print tag,'done'

    def runUnitTests (c,g):
        nodeName = 'All unit tests' # The tests to run.
        try:
            u = leoTest.testUtils(c)
            p = u.findNodeAnywhere(nodeName)
            if p:
                g.es('running unit tests in %s...' % nodeName)
                c.selectPosition(p)
                c.debugCommands.runUnitTests()
                g.es('unit tests complete')
            else:
                g.es('node not found:' % nodeName)
        except Exception:
            g.es('unexpected exception')
            g.es_exception()
            raise

    if __name__ == '__main__':
        main()
</t>
<t tx="ekr.20070317043727">Organizer nodes have headlines that do no start with @.
Organizer nodes may be inserted freely without changing the meaning of an @setting tree.
</t>
<t tx="ekr.20070317043727.2">Simple settings nodes have headlines of the form::

    @&lt;type&gt; name = val

set the value of name to val, with the indicated type.

&lt;type&gt; may be one of the following:

=============== =========================================================================================
&lt;type&gt;          Valid values
--------------- -----------------------------------------------------------------------------------------
\@bool           True, False, 0, 1
\@color          A Tk color name or value, such as 'red' or 'xf2fddff' (without the quotes)
\@directory      A path to a directory
\@float          A floating point number of the form nn.ff.
\@int            An integer
\@ints[list]     An integer (must be one of the ints in the list).
                 Example: @ints meaningOfLife[0,42,666]=42
\@keys[name]     Gives a name to a set of bindings for the Check Bindings script in leoSettings.leo.
\@path           A path to a directory or file
\@ratio          A floating point number between 0.0 and 1.0, inclusive.
\@string         A string
\@strings[list]  A string (must be one of the strings in the list).
                 Example: @strings tk_relief['flat','groove','raised']='groove'
=============== =========================================================================================

**Note**: For a list of Tk color specifiers see:

- http://www.tcl.tk/man/tcl8.4/TkCmd/colors.htm
- http://www.tcl.tk/man/tcl8.4/TkLib/GetColor.htm

**Important**: you can use the show-colors minibuffer command to guide you in making these settings.
</t>
<t tx="ekr.20070317043727.3">Complex settings nodes have headlines of the form::

    @&lt;type&gt; description

The type may be one of the following:

=================== =====================================================================
&lt;type&gt;              Valid values 
------------------- ---------------------------------------------------------------------
\@buttons           Child @button nodes create global buttons
\@commands          Child @command nodes create global buttons
\@data              Body text contains a list of strings, one per line.
\@enabled-plugins   Body text contains a list of enabled plugins
\@font              Body text contains a font description
\@menus             Child @menu and @item nodes create menus and menu items.
\@menuat            Child @menu and @item nodes modify menu tree create by \@menus.
\@mode [name]       Body text contains a list of shortcut specifiers.
\@recentfiles       Body text contains a list of file paths.
\@shortcuts         Body text contains a list of shortcut specifies.
=================== =====================================================================

Complex nodes specify settings in their body text.
See the following sections for details.
</t>
<t tx="ekr.20070325123558"></t>
<t tx="ekr.20070513113903">The highlights of Leo 4.4.3:

- @test and @suite nodes may now be embedded directly in external files.
- Added support for chapters in Leo's core.
- Added support for zipped .leo files.
- The new leoBridge module allows full access to all of Leo's capabilities
  from programs running outside of Leo.
- Better support for the winpdb debugger.
- Added support for @enabled-plugins and @openwith nodes in settings files.
- Removed all gui-dependent code from Leo's core.
- The__wx_gui plugin is now functional.
</t>
<t tx="ekr.20070610174018">This section contains settings for this file.

It also contains other information of little interest to most Leo users.</t>
<t tx="ekr.20070622185234">The 'official' way to start a replace command is::

    &lt;Ctrl-shift-r&gt;find-pattern&lt;return&gt;replace-text&lt;return&gt;

But suppose you with start with::

    &lt;ctrl-f&gt;find-pattern

and then realize you want to do a replace instead of a find.
No problem.  The following also works::

    &lt;Ctrl-f&gt;find-pattern&lt;Ctrl-shift-r&gt;replace-text&lt;return&gt;

In other words, you can think of `&lt;ctrl-f&gt;` as meaning 'show the find dialog'.

**Important**: Once you have started a find (or find &amp; replace), you can

1. Repeat the find operation using F3 (find-next) or
2. Replace the selection with the replace-text using Ctrl-= (replace) or
3. Replace the selection and find again using Ctrl-- (replace-then-find).

There is another trick you should know. After typing `&lt;ctrl-f&gt;` or
`&lt;shift-ctrl-r&gt;` you can use `&lt;alt-ctrl&gt;` keys to set or clear find
options. For example::

    &lt;ctrl-f&gt;&lt;alt-ctrl-w&gt;&lt;find-pattern&gt;&lt;return&gt;

That is, `&lt;ctrl-f&gt;` shows the find dialog,
`&lt;alt-ctrl-w&gt;` toggles the Whole Word checkbox and
`&lt;return&gt;` starts the search.
You can type the `&lt;alt-ctrl&gt;` keys anytime after `&lt;ctrl-f&gt;` (or `&lt;shift-ctrl-r&gt;`) and before `&lt;return&gt;`. 
You can also type multiple `&lt;alt-ctrl-keys&gt;` to toggle multiple checkboxes.
</t>
<t tx="ekr.20070622212132">::

    activate-cmds-menu
    activate-edit-menu
    activate-file-menu
    activate-help-menu
    activate-outline-menu
    activate-plugins-menu
    activate-window-menu
    add-space-to-lines
    add-tab-to-lines
    clean-lines
    clear-selected-text
    click-click-box
    click-headline
    click-icon-box
    clone-find-all
    contract-and-go-right
    contract-body-pane
    contract-log-pane
    contract-outline-pane
    contract-pane
    double-click-headline
    double-click-icon-box
    dump-all-objects
    dump-new-objects
    expand-body-pane
    expand-log-pane
    expand-outline-pane
    expand-pane
    find-again
    find-all
    find-tab-find command
    find-tab-find-previous
    free-text-widgets
    fully-expand-body-pane
    fully-expand-log-pane
    fully-expand-outline-pane
    fully-expand-pane
    goto-first-sibling
    goto-global-line
    goto-last-sibling
    help
    help-for-command
    hide-body-pane
    hide-find-tab
    hide-log-pane
    hide-minibuffer
    hide-outline-pane
    hide-pane,
    open-find-tab
    open-find-tab
    open-outline-by-name (uses filename completion)
    open-spell-tab
    print-bindings
    print-commands    re-search-backward
    re-search-forward
    remove-space-from-lines
    remove-tab-from-lines
    replace-string
    scroll-down
    scroll-down-extend-selection
    scroll-outline-down-line
    scroll-outline-down-page 
    scroll-outline-up-line
    scroll-outline-up-page
    scroll-up
    scroll-up-extend-selection
    search-backward
    search-forward
    search-with-present-options
    set-find-everywhere
    set-find-node-only
    set-find-suboutline-only
    show-colors
    show-fonts
    show-minibuffer
    show-search-options
    simulate-begin-drag
    simulate-end-drag
    toggle-find-ignore-case-option
    toggle-find-in-body-option,
    toggle-find-in-headline-option
    toggle-find-mark-changes-option
    toggle-find-mark-finds-option
    toggle-find-regex-option
    toggle-find-reverse-option
    toggle-find-word-option and
    toggle-find-wrap-around-option
    toggle-mini-buffer
    verbose-dump-objects
    word-search-backward
    word-search-forward
</t>
<t tx="ekr.20070622212732">- Added @font menu font setting.
- Added support for commands to be executed on entry to a mode.
- Added support for bindings that are active only in command, enter and insert key states.
- Added support for @abbrev nodes in leoSettings.leo.
- Improved check bindings script in leoSettings.leo.
- Allow @mode outside of leoSettings.leo.
- Added warnings about the @bool expanded_click_area setting.
</t>
<t tx="ekr.20070623145346"></t>
<t tx="ekr.20070623145346.1">Leo's setup.py script is intended only to create source distributions. It can't
be used to install Leo because Leo is not a Python package.
</t>
<t tx="ekr.20070628083442"></t>
<t tx="ekr.20070628083442.1">#####################
Unit testing with Leo
#####################

This chapter describes how you can execute Python unit test from within Leo
outlines.

Leo's **unit test commands** run the unit tests created by @test and @suite
nodes. run-unit-tests and run-unit-tests-locally run all unit tests in the
presently selected part of the Leo outline; run-all-unit-tests and
run-all-unit-tests-locally run all unit tests in the entire Leo outline.

Important: you must `run Leo in a console window`_ to see the output the
unit tests. Leo's unit test commands run all the unit tests using the
standard unittest text test runner, and the output of the unit tests
appears in the console.

test/unitTest.leo contains many examples of using @test and @suite nodes.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20070628083442.2">.. Links

.. _`run Leo in a console window`:      installing.html#running-leo-from-a-console-window
</t>
<t tx="ekr.20070628084351">**@test nodes** are nodes whose headlines start with @test. The unit test
commands convert the body text of @test nodes into a unit test automatically.
That is, Leo's unit test commands automatically create a unittest.TestCase
instances which run the body text of the @test node. For example, let us
consider one of Leo's actual unit tests. The headline is::

    @test consistency of back/next links

The body text is::

    if g.unitTesting:
        c,p = g.getTestVars() # Optional: prevents pychecker warnings.
        for p in c.all_positions():
            back = p.back()
            next = p.next()
            if back: assert(back.getNext() == p)
            if next: assert(next.getBack() == p)

When either of Leo's unit test commands finds this @test node the command will
run a unit test equivalent to the following::

    import leo.core.leoGlobals as g

    class aTestCase (unittest.TestCase):
        def shortDescription():
            return '@test consistency of back/next links'
        def runTest():
            c,p = g.getTestVars()
            for p in c.all_positions():
                back = p.back()
                next = p.next()
                if back: assert(back.getNext() == p)
                if next: assert(next.getBack() == p)

As you can see, using @test nodes saves a lot of typing:

- You don't have to define a subclass of unittest.TestCase.
- Within your unit test, the c, g and p variables are predefined, just like in Leo scripts.
- The entire headline of the @test node becomes the short description of the unit test.

**Important note**: notice that the first line of the body text is a **guard line**::

    if g.unitTesting:

This guard line is needed because this particular @test node is contained in the
file leoNodes.py. @test nodes that appear outside of Python source files do not
need guard lines. The guard line prevents the unit testing code from being
executed when Python imports the leoNodes module; the g.unitTesting variable is
True only while running unit tests.

**New in Leo 4.6**: When Leo runs unit tests, Leo predefines the 'self' variable to
be the instance of the test itself, that is an instance of unittest.TestCase.
This allows you to use methods such as self.assertTrue in @test and @suite nodes.

**Note**: Leo predefines the c, g, and p variables in @test and @suite nodes,
just like in other scripts.  Thus, the line::

    c,p = g.getTestVars()

is not needed.  However, it prevents pychecker warnings that c and p are undefined.
</t>
<t tx="ekr.20070628094515.1">**@suite nodes** are nodes whose headlines start with @suite. @suite nodes allow
you to create and run custom subclasses of unittest.TestCase.

Leo's test commands assume that the body of an suite node is a script that
creates a suite of tests and places that suite in g.app.scriptDict['suite'].
Something like this::

    if g.unitTesting:
        __pychecker__ = '--no-reimport' # Prevents pychecker complaint.
        import unittest
        c,p = g.getTestVars() # Optional.
        suite = unittest.makeSuite(unittest.TestCase)
        &lt;&lt; add one or more tests (instances of unittest.TestCase) to suite &gt;&gt;
        g.app.scriptDict['suite'] = suite

**Note**: as in @test nodes, the guard line, 'if unitTesting:', is needed only if the
@suite node appears in a Python source file.

Leo's test commands first execute the script and then run suite in
g.app.scriptDict.get('suite') using the standard unittest text runner.

You can organize the script in an @suite nodes just as usual using @others,
section references, etc. For example::

    if g.unitTesting:
        __pychecker__ = '--no-reimport'
        import unittest
        c,p = g.getTestVars() # Optional.
        # children define test1,test2..., subclasses of unittest.TestCase.
        @others 
        suite = unittest.makeSuite(unittest.TestCase)
        for test in (test1,test2,test3,test4):
            suite.addTest(test)
        g.app.scriptDict['suite'] = suite
</t>
<t tx="ekr.20070628094515.2">The run-all-unit-tests-locally and run-unit-tests-locally commands run unit
tests in the process that is running Leo. These commands *can* change the
outline containing the unit tests.

The run-all-unit-tests and run-unit-tests commands run all tests in a separate
process, so unit tests can never have any side effects. These commands never
changes the outline from which the tests were run. These commands do the
following:

1. Copy all @test, @suite, @unit-tests and @mark-for-unit-test nodes
   (including their descendants) to the file test/dynamicUnitTest.leo.

2. Run test/leoDynamicTest.py in a separate process.

   - leoDynamicTest.py opens dynamicUnitTest.leo with the leoBridge module.
     Thus, all unit tests get run with the nullGui in effect.

   - After opening dynamicUnitTest.leo, leoDynamicTest.py runs all unit tests
     by executing the leoTest.doTests function.

   - The leoTests.doTests function searches for @test and @suite nodes and
     processes them generally as described above. The details are a bit
     different from as described, but they usually don't matter. If you *really*
     care, see the source code for leoTests.doTests.
</t>
<t tx="ekr.20070806090226.15"></t>
<t tx="ekr.20070806095535.1">@auto trees allows people to use Leo in collaborative environments without using
sentinels in the files Leo generates. In contrast to @nosent, @auto trees can
change when the corresponding file changes outside of Leo.

Leo will automatically recreate (import) all @auto trees when reading a .leo
file, and will write all dirty @auto trees when saving a .leo file. There are
two exceptions to this statement:

1. Leo will never read (import) or write an @auto tree if
the root @auto tree is under the influence of an @ignore directive.

2. Saving a .leo file does not save @auto nodes if a) they haven't been changed
or b) they do not contain a **significant** amount of information. An @auto tree
contains a significant amount of information if it has  children or if the
root node contains more than 10 characters.

Leo creates @auto trees by parsing the corresponding external file. Parsers
create descendant nodes of the @auto tree: one node for each class, method and
function in the external file.

Parsers presently exist for C, elisp, Java, Pascal, PHP and Python. Leo
determines the language using the file's extension. If no parser exists for a
language, the entire body of an @auto tree contains a significant amount of
information if it has any children or if the root node contains more than 10
non-blank lines. the external file is copied to the body of the @auto node.

Leo does not write the contents of @auto trees to .leo files. In this respect,
@auto trees work much like @file trees. @auto trees whose root node is under the
scope of an @ignore directive *will* be written to the .leo, just like @file
trees.
</t>
<t tx="ekr.20070806100055">All present parsers are short overrides of a powerful base parser class. Thus,
it would be simple to add support for other languages. See the node::

    @file leoImport.py--&gt;Import--&gt;Scanners for createOutline

in leoPy.leo to see how easy it is to create new parsers.

</t>
<t tx="ekr.20070806101412">Three new commands in the File:Read/Write menu allow you to manually read and
write @auto nodes from the presently selected outline. As always, an @ignore
directive in the @auto node or its ancestors will suppress any of these
commands:

- The Read @auto Nodes (read-at-auto-nodes) command reads all @auto nodes in the
  presently selected outline. An @ignore directive will suppress this import.

- The Write @auto Nodes (write-at-auto-nodes) command writes all @auto nodes. An
  @ignore directive will suppress this import. Caution: the write will occur even
  if Leo has not previously read the @auto node.

- The Write Dirty @auto Nodes (write-dirty-at-auto-nodes) is the same as the
  write-at-auto-nodes command, except that only changed @auto trees are written.

Most users will rarely use these explicit commands, because reading and writing
.leo files handles @auto nodes well enough. However, you can use the
read-at-auto-nodes command to update @auto nodes without having to reload the
.leo file.
</t>
<t tx="ekr.20070809141529">Leo performs several checks to ensure that the result of importing an external
file will be equivalent to the file that writing the @auto tree would produce.

These checks can produces **errors** or **warnings**. Errors indicate a
potentially serious problem. Leo inserts an @ignore directive in the @auto tree
if any error is found. This @ignore directive prevents the @auto tree from
modifying the external file. If you @ignore directive, a later write of the
@auto tree will attempt to fix the problems that gave rise to the errors. There
are no guarantees however.

**Strict languages** are languages like Python for which leading whitespace is
especially significant. Before importing a file for a strict language, Leo
**regularizes** the leading whitespace of all lines of the original source file.
That is, Leo converts blanks to tabs or tabs to blanks depending on the value of
the @tabwidth directive in effect for the @auto node. Leo cannot guarantee to
reproduce the original source file exactly if problems are discovered while
regularizing leading whitespace.

After importing a file, Leo verifies that writing the @auto node would create
the same file as the original file. For strict languages, the comparison must be
exact, or nearly so. For non-strict languages, differences in leading whitespace
generate warnings, not errors.

File comparison mismatches can arise for several reasons:

1. Bugs in the import parsers. Please report any suspected bugs immediately.

2. Underindented lines in classes, methods or functions in strict languages. An
   **underindented line** is a line that is indented less then the starting line
   of the class, method or function in which it appears. Leo outlines can not
   represent such lines exactly: every line of node implicitly has at least the
   indentation of any unindented line of the node.

Leo will issue a warning (not an error) for underindented Python comment lines.
Such lines can not change the meaning of Python programs.
</t>
<t tx="ekr.20070809145744">Leo 4.4.4 contains many important features originally planned for later releases.
The highlights of Leo 4.4.4:

- **The Great Graph Aha**:
  A Leo outline doesn't have to *be* an arbitrary graph in order to *represent* an arbitrary graph.

  That is, simple scripts allow Leo outlines to represent arbitrary
  directed graphs. There is no need for a separate 'graph world'. The graphed.py
  plugin is a direct result of this Aha. It allows you to create general graphs
  from Leo outlines.

- Support for **@auto nodes**.  Such nodes allow people to collaborate using Leo
  without inserting Leo sentinels in the files Leo generates.

- **@menus trees** in settings files create all of Leo's menus.  It is now dead
  easy to make Leo's menus look the way you want.

- **@buttons trees** in settings files create common @button nodes created in all
  Leo outlines.

- A new, faster, **colorizer plugin** replaces the __jEdit_colorizer__ plugin.

- New commands for **resolving cvs conflicts**.

- Leo's core is now compatible with jython.
</t>
<t tx="ekr.20070809145744.4">::

    check-derived-file
    check-leo-file
    compare-leo-outlines
    insert-child
    read-at-auto-nodes
    read-file-into-node
    write-at-auto-nodes
    write-dirty-at-auto-nodes
    write-file-from-node
</t>
<t tx="ekr.20070809145744.5"></t>
<t tx="ekr.20070809145744.6">- The graphed plugin allows users to manipulate parts of Leo outlines as if they
  were general graphs. It is still early days for this exciting plugin.

- The threading_colorizer plugin replaces the __jEdit_colorizer__ plugin. This
  plugin features an elegant new algorithm that has much better performance and
  eliminates almost all flash.
</t>
<t tx="ekr.20070809145744.7">- See the release notes for a list of bugs fixed in Leo 4.4.4.

- Added the 'clear-all-marks' hook.

- Added button font setting. See the node::

    "@settings--&gt;Fonts--&gt;@font button font" in leoSettings.leo.

- Plugins and scripts may call the c.frame.canvas.createCanvas method to create a
  log tab containing a Tk.Canvas widget. Here is an example script::

    log = c.frame.log ; tag = 'my-canvas'
    w = log.canvasDict.get(tag)
    if not w:
        w = log.createCanvas(tag)
        w.configure(bg='yellow')
    log.selectTab(tag)

- Improved the yank and yank-pop commands and added @bool add_ws_to_kill_ring setting.

- Improved the debug command: it now adds the following code to the beginning of debug scripts::

    class G:
        def es(s,c=None):
          pass
    g = G()

- Added the @bool rst3 strip_at_file_prefixes setting.

- Added the g.app.inBridge ivar.

- Added @bool big_outline_pane setting. False (legacy): Top pane contains outline and log panes.
  True: Top pane contains only the outline pane.  Bottom pane contains body and log panes.
</t>
<t tx="ekr.20070814104719" str_atime="1376412994.0">You enable or disable plugins using @enabled-plugins nodes in leoSettings files
(leoSettings.leo, myLeoSettings.leo or the .leo file being loaded). See
`Specifying settings`_ for full details of settings files.

The body text of the @enabled-plugins node contains a list of enabled plugins.
Notes:

- Leo attempts to load all plugins every time an @enabled-plugins node is seen.
   If the plugin has already been loaded, Leo silently ignores the request to
   re-enable the plugin. Leo never attempts to disable a plugin while processing
   enabled plugin strings. Thus, plugins enabled in an @enabled-plugins node in
   leoSettings.leo *will* be enabled regardless of the contents of any other
   @enabled-plugins node.

- g.app.gui.getEnabledPlugins contains the last processed @enabled-plugins node.
</t>
<t tx="ekr.20070816092449">Question and answer from plumloco.

Add the equivalent of::

    import sys 
    leocore = "path/to/leo/core" 
    if leocore not in sys.path: sys.path.append(leocore) 
    import leo.core.leoBridge as leoBridge

at the head of each file that uses leoBridge.

The problem is not importing leoBridge itself but (if I use 'from leo.core') the
importing of plugins, who get a different leoGlobals from leoBridge, without
g.app etc, and so do not work if they rely on dynamic values in g.etc.

&gt; Why can't you simply add leo/core to sys.path in sitecustomize.py?  

Putting leo/core on the python path as you suggest would put forty python modules
in the global module namespace for all python programs when I want just one.
Also, I have a safe working copy of leo and a cvs/testing version. I would wish
to test any programs against the testing version while using the working
version, but both /core directories can't be exposed at the same time.

&gt; Do you need plugins while running from the leoBridge? 

Afraid so, at least the rst3 plugin. The solution I am using now is to place::

    sys.modules['leoGlobals'] = leoGlobals  

in leoBridge after import leo.core.leoGlobals as leoGlobals

This allows my scripts
to be portable over the several computers/platforms I need to use them on, and
makes testing scripts against multiple leo versions easy. It does mean that my
scripts are not portable to other leo users but that is not likely to be a
problem.
</t>
<t tx="ekr.20070920092716">The so-called resolve-cvs-conflict project has resolved itself into small,
easily understood commands.

The **read-file-into-node** command prompts for a filename, and creates an node
whose headline is @read-file-into-node &lt;filename&gt; and whose body text is the
entire contents of the file.

The **write-file-from-node** command writes the body text of the selected not to a file.
If the headline of the presently selected node starts with @read-file-into-node
the command use the filename that follows in the headline. Otherwise, the
command prompts for a filename.

When a cvs conflict occurs, the user will:

- read the file into a node using the read-file-into-node command,

- fix the conflict, as with any other editor, and

- write the file with the write-file-from-node command.

Any file can be fixed in this way, including external files and .leo files. The
only complication is that the user must not change sentinel lines. Two new
commands check the contents of a node: The **check-derived-file** and
**check-leo-file** commands tell whether a trial read of the presently selected
node can be done successfully. The check-derived-file command assumes the body
text is a external file; the check-leo-file command assumes the body text is an
entire .leo file.

The **compare-leo-outlines** command prompts for another (presumably similar)
.leo file that will be compared with the presently selected outline file (main
window). It then creates clones of all inserted, deleted and changed nodes.
</t>
<t tx="ekr.20071001122703">All @buttons tree in a settings file defines global buttons that are created in
the icon area of all .leo files. You define @button nodes in the @buttons tree
as usual.
</t>
<t tx="ekr.20071004103659">The Great Graph Aha is:

A Leo outline doesn't have to *be* an arbitrary graph in order to *represent* an arbitrary graph.

So the graph world is unnecessary because we can use Leo nodes and trees as data
to other graphing packages.** That is, Python scripts can build arbitrary graphs
using Leo's existing nodes and trees. And Python scripts can manipulate those
graphs. And Python scripts could do the reverse: manipulate the Leo outline by
traversing general graphs. So there is no need to complicate Leo's fundamental
data structures. Hurray! Instead, we build on the strengths of already existing
graphing packages.

The Great Graph Aha created the opportunity for immediate action:

1. test.leo contains the essential scripts to implement graphs in Leo files.
   These short, simple, self-contained, easily modifiable scripts make possible
   everything ever envisaged by the (now-defunct) graph world project::

    leo2graph: convert a normal Leo tree to a NetworkX graph. 
    at-graph2graph: convert an @graph tree to a NetworkX graph. 
    at-networkx2graph: convert an @networkx tree to a NetworkX graph 
    at-networkx2at-graph: create an @graph tree from an @networkx tree.

2. The graphed plugin allows users to manipulate parts of Leo outlines as if
they were general graphs. It is still early days for this exciting plugin.
</t>
<t tx="ekr.20071004110818">Leo creates its menus from the @menu and @item nodes in the @menus tree. Within
@menus trees, @menu nodes create menus and @item nodes create menu items.

The menu name always follows @menu. If the menu name is 'Plugins', Leo will
create the Plugins menu and populate the menu by calling the
'create-optional-menus' hook. This creates the Plugins menu as usual. Nested
@menu nodes define submenus.

The command name follows @item. If the body text of an @item node exists, this
body text is the menu name. Otherwise, the menu name is the command name.
However, if the command name starts with a '*', hyphens are removed from the
menu name. Menu names and command names may contain a single ampersand (&amp;). If
present, the following character is underlined in the name. If the command name
in an @item node is just a hyphen (-), the item represents a menu separator.
</t>
<t tx="ekr.20071005100213">Essentially all of Leo's startup code now runs with jython 2.2 and the (unfinished!) swing gui.
</t>
<t tx="ekr.20071026055929"></t>
<t tx="ekr.20071026055929.1">First, you must change Python's default encoding to something other than 'ascii'.  To do this, put the following in your sitecustomize.py file in Python's Lib folder::

    import sys 
    sys.setdefaultencoding('utf-8') # 'iso-8859-1' is another choice.

You must restart Python after doing this: sys.setdefaultencoding can not be called after Python starts up. 

Leo's g.es_print and g.pr functions attempts to convert incoming arguments to unicode using the default encoding.
For example, the following Leo script shows various ways of printing La Peña properly::

    @first # -*- coding: utf-8 -*-

    import sys
    e = sys.getdefaultencoding()
    print 'encoding',e
    table = (
        'La Peña',
        unicode('La Peña','utf-8'),
        u'La Peña',
        u'La Pe\\xf1a',
    )

    for s in table:
        print type(s)
        g.es_print('g.es_print',s)
        if type(s) != type(u'a'):
            s = unicode(s,e)
        print 'print     ',s
        print 'repr(s)   ',repr(s)

For still more details, see:
http://www.diveintopython.org/xml_processing/unicode.html 
</t>
<t tx="ekr.20071026180804">The prototype in test.leo now will use PIL (Python Imaging Library) if
available, so many more kinds of icons can be used. Buttons now exist to add
icons to do the following:

- Add any icon to any node.
- Delete all icons from a single node or the entire tree.
- Print the icon files associated with a node.
- Print the sizes of icons in a directory.

Fixed a bug in the icon handling in the outline widget that caused
duplicate icons not to be drawn properly.
</t>
<t tx="ekr.20071026183116">Scripts can invoke various dialogs using the following methods of the
g.app.gui object.

Here is a partial list. Use typing completion to get the full list::

    g.app.gui.runAskOkCancelNumberDialog(c,title,message)
    g.app.gui.runAskOkCancelStringDialog(c,title,message)
    g.app.gui.runAskOkDialog(c,title,message=None,text='Ok')
    g.app.gui.runAskYesNoCancelDialog(c,title,message=None,
        yesMessage='Yes',noMessage='No',defaultButton='Yes')
    g.app.gui.runAskYesNoDialog(c,title,message=None)

The values returned are in ('ok','yes','no','cancel'), as indicated by the
method names. Some dialogs also return strings or numbers, again as indicated by
their names.

Scripts can run File Open and Save dialogs with these methods::

    g.app.gui.runOpenFileDialog(title,filetypes,defaultextension,multiple=False)
    g.app.gui.runSaveFileDialog(initialfile,title,filetypes,defaultextension)

For details about how to use these file dialogs, look for examples in Leo's own
source code. The runOpenFileDialog returns a list of file names.
</t>
<t tx="ekr.20071116062917"></t>
<t tx="ekr.20071116062917.18">::

    delete-all-icons
    delete-first-icon
    delete-last-icon
    delete-node-icons
    insert-icon
    reverse-sort-lines
    reverse-sort-lines-ignoring-case.
    sort-lines-ignoring-case
    toggle-collapse_nodes_during_finds
</t>
<t tx="ekr.20071116062917.2">.. Links used in this document.
.. _`leoBridge`:            leoBridge.html
.. _`debugging with Leo`:   debuggers.html
.. _`Using @shadow`:        atShadow.html
.. _`Python's gettext`:     http://docs.python.org/lib/module-gettext.html
.. _Emacs:                  http://www.xemacs.org/
.. _pymacs:                 http://pymacs.progiciels-bpi.ca/index.html
.. _`Leo and Emacs`:        emacs.html


</t>
<t tx="ekr.20071116062917.3">- Leo now supports all directives in headlines.

- Moved all unit tests to unitTest.leo and reorganized the unit tests by Leo source file.

- Installed small icon set from Tango library.

- The rst3 plugin now supports @rst-preformat nodes.
</t>
<t tx="ekr.20071116063202">.. _`zombie`: http://sourceforge.net/forum/message.php?msg_id=3768494

.. _`vampire`: http://sourceforge.net/forum/message.php?msg_id=3525277

- Fixed hung (`zombie`_) windows.

- Fixed resurrected (`vampire`_) nodes.
</t>
<t tx="ekr.20071116063649">- @bool at_auto_warns_about_leading_whitespace

  This option has effect only when importing so-called non-strict languages, for
  which leading whitespace is not terribly significant.

- @bool warn_when_plugins_fail_to_load

  There is also an @bool trace_plugins setting.

- @bool vim_plugin_opens_url_nodes

  vim.py does not open url nodes if this setting is False.
</t>
<t tx="ekr.20071210094621">This following is adapted from Terry Brown's entry in Leo's wiki.

You can not just run leoBridge from Leo, because the leoBridge module is designed
to run a separate copy of Leo. However, it is possible to run leoBridge from a
separate process. That turned out to be more, um, interesting than anticipated,
so I'm recording the results here.

The idea is that script A running in Leo (i.e. in a regular GUI Leo session)
calls script B through subprocess.Popen(), script B uses LeoBridge to do
something (parse unloaded Leo files), and returns the result to script A.
Passing the result back via the clipboard seemed like a possibility, but
XWindows / tcl/tk clipboard madness being what it is, that didn't seem to work.

First trick, calling script B from script A::

    import subprocess
    p = subprocess.Popen(('python',
        path_to_script_B,
        parameter_for_script_B,),
        stdout=subprocess.PIPE,
        env={'PYTHONPATH': g.app.loadDir,'USER': g.app.leoID},
    )
    p.wait()

Setting PYTHONPATH in the environment seemed like the easiest way to let
script B find leoBridge.py (which it needs to import).  But by setting the
env parameter you limit script B's environment to be **only** PYTHONPATH,
which causes leoBridge to fail because, in unix at least, it depends
on USER in the environment.  So you need to pass that through, too.

Now, because passing stuff back on the clipboard seems unreliable, at least
in XWindows, script B passes results back to script A via stdout (print),
but there's some Leo initialization chatter you want to avoid.  So put a
sentinel, 'START_CLIPBOARD', in the output, and collect it like this::

    response = p.stdout.readlines()
    while response and 'START_CLIPBOARD' not in response[0]:
        del response[0]
    del response[0]  # delete the sentinel as well
    response = ''.join(response)

This is the basic mechanism.  What I *actually* wanted to do was have script
B generate a branch of nodes and pass that back to script A for insertion in
the tree script A is running in.  That's relatively easy if you use::

    c.setCurrentPosition(pos_of_branch_to_return)
    c.copyOutline()
    print '&lt;!-- START_CLIPBOARD --&gt;'
    print g.app.gui.getTextFromClipboard()
    print '&lt;!-- END_CLIPBOARD --&gt;'

at the end of script B. Back in script A, after you've rebuilt
`response` as shown above, do::

    g.app.gui.replaceClipboardWith(response)
    c.pasteOutline()
</t>
<t tx="ekr.20071217093444"></t>
<t tx="ekr.20071217093444.5">::

    find-next-clone
    toggle-sparse-move

Replaced the delete-all-icons command with a script in scripts.leo.  This command was too dangerous.
</t>
<t tx="ekr.20071217093444.6">- Added support for @data nodes in settings files.

- The @data import_xml_tags setting specifies the xml tags that act as organizers.
  This settings is used by @auto when importing xml files.
</t>
<t tx="ekr.20080109074102">You can add an icon to the presently selected node with
c.editCommands.insertIconFromFile(path). path is an absolute path or a path
relative to the leo/Icons folder. A relative path is recommended if you plan to
use the icons on machines with different directory structures.

For example::

    path = 'rt_arrow_disabled.gif' 
    c.editCommands.insertIconFromFile(path) 

Scripts can delete icons from the presently selected node using the following methods::

    c.editCommands.deleteFirstIcon() 
    c.editCommands.deleteLastIcon() 
    c.editCommands.deleteNodeIcons() 
</t>
<t tx="ekr.20080116071239">- Added support for @auto xml and @auto javascript.
  Use @data import_xml_tags setting to specify the xml tags that act as organizers.
  Javascript regexps that look like section references cause problems, but that can not be helped.
</t>
<t tx="ekr.20080203101507"></t>
<t tx="ekr.20080203101507.1">##########################
ILeo: Leo's IPython Bridge
##########################

.. contents::
    :depth: 2
</t>
<t tx="ekr.20080203101507.2">.. Links

.. _ipython:                http://ipython.scipy.org/
.. _IPython:                http://ipython.scipy.org/
.. _`IPython Notebook`:     http://projects.scipy.org/ipython/ipython/wiki/NoteBook
.. _extensionAPI:           http://ipython.scipy.org/moin/IpythonExtensionApi
.. _`The Ipython Extension API`: extensionAPI_
.. _`Scripting Leo with Python`:    tutorial-scripting.html

.. _`run Leo in a console window`:  installing.html#running-leo-from-a-console-window
.. _`console window`:               installing.html#running-leo-from-a-console-window

</t>
<t tx="ekr.20080310093038.4">.. _gettext: http://docs.python.org/lib/module-gettext.html

It is easy to translate Leo's menu strings: simply create an @menus tree in
leoSettings.leo or myLeoSettings.leo that contains the translated menu names.

**New in Leo 4.4.8**:
Leo now contains support for translating messages sent to Leo's log:

- Rather than using an '_' function to denote strings to be translated, Leo's
  g.es and g.es_print functions translate "odd" (first, third, fifth) arguments,
  leaving "even" arguments untranslated. Keyword arguments, color, newline, etc.
  are never translated.

- All calls to g.es and g.es_print in Leo's core follow this convention.

- g.translateString does the actual translation using Python's `gettext`_ module.

- You can use the script in the node "@button print g.es stats" in scripts.leo
  to create catalogs of all scripts that need to be translated. Such catalogs
  are used by Python's gettext module. (This script was also used to check that
  the proper arguments to g.es and g.es_print were translated.)
</t>
<t tx="ekr.20080314081157.124">- Better support for unicode in \@auto trees.

- All import commands now honor \@path

- Leo now supports arguments to minibuffer commands.

- Leo can now translate messages sent to Leo's log. Rather than using an '_'
  function to denote strings to be translated, Leo's g.es and g.es_print
  functions translate "odd" (first, third, fifth) arguments, leaving "even"
  arguments untranslated. Keyword arguments, color, newline, etc. are never
  translated. g.translateString does the actual translation using
  `Python's gettext`_ module.

- \@menu items may not refer to commands created by @button and @command nodes.
</t>
<t tx="ekr.20080314081157.125">- Added support for @commands trees in leoSettings files.

- Added support for @bool open_with_save_on_update setting. If True, Leo will
  automatically save the outline whenever an external editor changes the
  outline.
</t>
<t tx="ekr.20080314081157.127"></t>
<t tx="ekr.20080314081157.128">- The ipython plugin creates a simple, powerful, effective bridge between IPython and Leo.
  See http://leoeditor.com/IPythonBridge.html

- Improved marks/recent buttons plugin.
</t>
<t tx="ekr.20080315115427.568">This series of releases featured **hundreds** of improvements.  The highlights were truly significant:

- Added the leoBridge module. See `Embedding Leo with the leoBridge Module`_.

- Added support for @enabled-plugins and @openwith (formerly @open-with) nodes in settings files.

- Added support for ZODB. See `Using ZODB with Leo`_.

- Added leoPymacs module. See `Leo and Emacs`_.

- Added perfect import of external files with @auto nodes.

- Used the sax parser to .leo files. This allows the format of .leo files to be
  expanded easily.

- Added support for myLeoSettings.leo.

- Supported multiple editors in body pane.

- Added the jEdit_colorizer plugin. See `Controlling Syntax Coloring`_.

- Many other new plugins.

For a complete list, see the `What's New`_ chapter.
</t>
<t tx="ekr.20080411111008.1">Leo ignores any subtree of an @settings tree whose headline starts with @ignore.

You can use several other kinds of nodes to cause Leo to ignore parts of  an @settings tree:

- @if *expression*

  A node whose headline starts with @if *expression* acts like an organizer node if the expression evaluates to True,    
  otherwise acts like an @ignore node.
  If the expression is empty the body text should contain a script that will be evaluated (in an empty context).

- @ifplatform *platform-name*

  Same as @if sys.platform == "platform-name": except that it isn't necessary to import sys.

- @ifhostname *hostA,!hostB*

  Evaluates to True if and only if: h=g.computeMachineName(); h==hostA and h!=hostB.
  The "!" version allows matching to every machine name except the given one
  to allow differing settings on only a few machines.
</t>
<t tx="ekr.20080412124815.1"></t>
<t tx="ekr.20080527063511.1">I had a need to figure out why a part of some python code I had written
was taking too long.

I pulled the code into LEO and the relevant part of the outline looked
something like this::

    + Main module
    -- Generate cryptographic key
    -- Hashing algorithm

etc. So I cloned just the segment I wanted to profile and pulled it under a new
section::

    + Main module
    -- [clone] Generate cryptographic key
    -- Hashing algorithm

    + Profiling Experiment
    -- [clone] Generate cryptographic key

And in the body of the "Profiling experiment", I used this code::

    code_under_here = """
    @others
    """

    from timeit import Timer
    t = Timer("print my_key_generator()", code_under_here)
    print t.timeit(number = 10)

And then I hit Control-B to execute the Profiling Experiment body. This
let me make adjustments to the code in the clone body and keep hitting
Control-B to execute the code with the timeit module to see immediately
if what I had done was making a difference.

The great thing about this was that I just used the LEO @others construct
to create a wrapper around the code and did not need to litter my code
with debug or profiling statements.  -- Kayvan
</t>
<t tx="ekr.20080603124653.1">Many users will want to track the development version of Leo, in order to stay
on top of the latest features and bug fixes. Running the development version is
quite safe and easy, and it's also a requirement if you want to contribute to
Leo.

1. First, you need to get Bazaar (bzr) from http://bazaar-vcs.org. For windows
   users we recommend the standalone installer - the python installer may have
   problems pushing to Launchpad. Plain bzr installer only contains the command
   line version, so you might want to augment that with a friendly GUI - qbzr is
   recommended as it's the easiest one to install. It provides command like
   'bzr qlog', 'bzr qannotate' etc.

2. Get Leo from launchpad by doing::

    bzr branch lp:leo-editor

And that's it! You can run the launchLeo script (in the top-level branch directory) directly.
When you want to refresh the code with latest modifications from Launchpad, 'run bzr pull'.

If you make modifications to Leo (with the interest in sharing them with the Leo
community), you can check them in to your local branch by doing 'bzr checkin'.
Now, to actually request your changes to be merged to Leo trunk, you need a
Launchpad account with RSA keys in place. There is showmedo video about how to
accomplish this on Windows using puttygen and pageant at
http://showmedo.com/videos/video?name=1510070&amp;fromSeriesID=151.

After your Launchpad account is set up, go to
https://launchpad.net/leo-editor, choose Code tab -&gt; Register Branch, select
Branch type "Hosted" and fill in descriptive details about the branch. After
that, go to the branch home page from Code tab again, and copy-paste the push
command line to terminal. For example, for branch::

 https://code.launchpad.net/~leo-editor-team/leo-editor/mod_rclick

The push command is::

 bzr push bzr+ssh://my_name@bazaar.launchpad.net/~leo-editor-team/leo-editor/mod_rclick

You may wish to add --remember command line option to bzr push, to direct all
future pushes to that location. Then, you only need to execute 'bzr push'.

After your branch is pushed, you can email the Leo mailing list and request it
to be reviewed and merged to trunk.

-- Ville M. Vainio - vivainio.googlepages.com
</t>
<t tx="ekr.20080729064227.6">The timit button in unitTest.leo allows you to apply Python's timeit module.
See http://docs.python.org/lib/module-timeit.html.
The contents of @button timer is::

    import leo.core.leoTest as leoTest
    leoTest.runTimerOnNode(c,p,count=100)

runTimerOnNode executes the script in the presently selected node using timit.Timer and prints the results.
</t>
<t tx="ekr.20080729064227.7">The profile button in unitTest.leo allows you to profile nodes using Python's profiler module.
See http://docs.python.org/lib/module-profile.html
The contents of @button profile is::

    import leo.core.leoTest as leoTest
    leoTest.runProfileOnNode(p,outputPath=None) # Defaults to leo\test\profileStats.txt

runProfileOnNode runs the Python profiler on the script in the selected node, then reports the stats.
</t>
<t tx="ekr.20080730212711.14"></t>
<t tx="ekr.20080730212711.15">#############
Using @shadow
#############

This chapter describes an important new feature that debuted in Leo 4.5 b2: @shadow trees.
These trees combine the benefits of @auto, @file and @nosent trees:

- The (public) files created by @shadow trees contain no sentinels, but
- Leo is able to update @shadow trees in the Leo outline based on changes made
  to public files outside of Leo.

@shadow trees are often useful for studying or editing source files from projects that don't use Leo. 
In such situations, it is convenient to import the @shadow tree from the (public) sources.
As discussed below, Leo can import @shadow trees automatically,
using the same algorithms used by `@auto trees`_.

The crucial ideas and algorithms underlying @shadow trees are the invention of Bernhard Mulder.

.. contents::
    :depth: 2

</t>
<t tx="ekr.20080730212711.16">.. Links
.. _`@auto trees`:          directives.html#auto    
</t>
<t tx="ekr.20080730212711.39">Using @shadow trees is the best choice when you want to have the full power of
Leo's outlines, but wish to retain the source files in their original format,
without Leo sentinels (markup) in comments in the source file. 

Leo's @file trees create external files containing comments called sentinels.
These sentinel lines allow Leo to recreate the outlines structure of @file
trees. Alas, many people and organizations find these added sentinel lines
unacceptable. \@nosent nodes create external files without sentinels, but at a
cost: Leo can not update \@nosent trees when the corresponding external file is
changed outside of Leo.

\@shadow trees provide a way around this dilemma. When Leo saves an \@shadow
tree, it saves two copies of the tree: a **public** file without sentinels, and
a **private** file containing sentinels. Using Bernhard Mulder's brilliant
**update algorithm**, Leo is able to update @shadow trees in the Leo outline
based *solely* on changes to public files.

Leo writes private files to a subfolder of the folder containing the public file:
by default this folder is called .leo_shadow.
You can change the name of this folder using the @string shadow_subdir setting.
Note that private files need not be known to source code control systems such as bzr or cvs.

That's *almost* all there is to it.  The following sections discuss important details:

- How to create @shadow trees.
- How @shadow works.
- Why the update algorithm is sound.
</t>
<t tx="ekr.20080730212711.40">Suppose our @shadow tree is @shadow a.py. When Leo writes this tree it creates a
public file, a.py, and a private file, .leo_shadow/xa.p (or just xa.p for
short). Public files might can committed to a source code control system such as
cvs or bzr. Private files should *not* be known to cvs or bzr.

Now suppose a.py has been changed outside of Leo, say as the result of a bzr
merge. The corresponding private file, xa.p, will *not* have been changed.
(Private files should *never* change outside of Leo.

When Leo reads the *new* (and possibly updated) public file it does the
following:

1. Recreates the *old* public file by removing sentinels from the (unchanged!) *private* file.
2. Creates a set of diffs between the old and new *public* files.
3. Uses the diffs to create a new version of the *private* file.
4. Creates the @shadow tree using  the new *private* file.

**Important**: The update algorithm never changes sentinels. This means that the
update algorithm never inserts or deletes nodes. The user is responsible for
creating nodes to hold new lines, or for deleting nodes that become empty as the
result of deleting lines.

Step 3 is the clever part. To see all the details of how the algorithm works,
please study the x.propagate_changed_lines method in leoShadow.py. This code is
heavily commented.
</t>
<t tx="ekr.20080730212711.42">The first step in creating an @shadow tree is to create a node whose
headline is @shadow *&lt;filename&gt;*.

Thus, you can create an @shadow node and save your outline, regardless of
whether the original file exists. The next time Leo reads the @shadow node, Leo
will **create** the entire @shadow tree using the same logic as for `@auto
trees`_. You can cause Leo to read the @shadow node in two ways: 1) by closing
and reloading the Leo outline or 2) by selecting the @shadow node and executing
the File:Read/Write:Read @shadow Node command.

**Important**: Leo imports the private file into the @shadow tree only if

a) the public file exists and
b) the private file does *not* exist.

Thus, Leo will import code into each @shadow node at most once. After the first
import, updates are made using the update algorithm.

**Note**: just as for @auto, Leo will never read (import) or write an @shadow
tree if the @shadow node is under the influence of an \@ignore directive.

**Important**: At present, Leo puts all nodes included by @others at the
same outline level. This could fairly be called a bug. See:
https://bugs.launchpad.net/leo-editor/+bug/1226353 The workaround is to
place an @others directive at the end of any node with children.
</t>
<t tx="ekr.20080730212711.52">There are several boundary cases that the update algorithm can not resolve.
For example, if a line is inserted at the boundary between nodes,
the updated algorithm can not determine whether the line should be inserted
at the end of one node of the start of the next node.

Happily, the inability of the update algorithm to distinguish between
these two cases **does not matter**, for three very important reasons:

1. No matter which choice is made, the *public* file that results is the same.
   **The choice doesn't matter**, so the update algorithm is completely and
   absolutely safe.

2. Leo reports any nodes that were changed as the result of the update
   algorithm. In essence, these reports are exactly the same as the reports Leo
   makes when @file trees were changed as the result of changes made externally
   to Leo. It is as easy for the user to review changes to @shadow trees as it
   is to review changes to @thin or @file trees.

3. Suppose the user moves a line from the end of one node to the beginning of
   the following node, or vice versa. Once the user saves the file, the
   *private* file records the location of the moved line. The next time the user
   reads the @shadow file, the line will *not* be subject to the update
   algorithm because the line has not been changed externally. The location of
   the line (on the boundary) will be completely determined and it will never
   need to be moved across the boundary.

Understanding these three reasons finally convinced me that @shadow could be
made to work reliably.
</t>
<t tx="ekr.20080806211440.185"></t>
<t tx="ekr.20080806211440.188">.. _`v.uA's`: http://groups.google.com/group/leo-editor/browse_thread/thread/750bb3099090f5b

- Added support for @shadow files.
  This is a major breakthrough.
  See the `Using @shadow`_ chapter for full details.

- Added much improved support for vim bindings.

- Allow `v.uA's`_ in @file and @shadow nodes.
</t>
<t tx="ekr.20080806211440.189">- The default settings for @shadow files are now located in leoSettings.leo in the node::

        @settings--&gt;File options--&gt;Shadow files

    The defaults for these settings are::

        @string shadow_prefix = x
        @string shadow_subdir = .leo_shadow

- Added support for @bool fixedWindow option.

    Leo suppresses marks, expansion state, orphan bits and current position bits
    when writing fixed .leo files. As a result, all nodes will be collapsed and
    the root node will always be selected when Leo opens a fixed .leo file.

    You can optionally specify the size and position on the screen of fixed .leo
    files by putting an '@data fixedWindowPosition' node in the
    \@settings tree of myLeoSettings.leo or leoSettings.leo.  You should
    **not** put such a node in the fixed .leo file itself--everyone who
    opens the file would get that fixed position.

    The body of the '@data fixedWindowPosition' node should contain
    something like this::

        # Must be four entries: width,height,left,top.
        # Put this in myLeoSettings.leo, **not** in individual .leo files.

        1200
        800
        50
        50

- Added @bool cleo_color_ignore = True

    This determines whether cleo colors @ignore headlines. The default is True.
</t>
<t tx="ekr.20080806211440.253">- Leo now uses a sax-based parser to read .leo files.
  This makes it possible to extend Leo's file format without invalidating previous versions of Leo.

- Leo now supports the so-called 'Graph World'.
  When g.unified_nodes is True, Leo moves all information from tnodes into vnodes.

- Leo now uses a new key binding scheme.
  This allows substantially simpler key bindings. Indeed, most per-pane bindings
  have been eliminated.
  Added support for kill bindings.

- Leo is now an installable package.
  To make this work, Leo adds os.curdir to sys.path if needed on startup.

- Reorganized Leo's drawing and focus code.
  As a result, calls to c.beginUpdate and c.endUpdate are no longer needed.

- Leo is now ready for Python 3.x:
  Change most print statements to calls to g.pr.
</t>
<t tx="ekr.20080806211440.256">- Added g.Tracer class.  This is a Python 'debugger' that computes a call graph.
  To trace a function and its callers, put the following at the function's start::

    g.startTracer()

- The find-character command now finds characters across line boundaries.

- Set cwd in read/write commands. This affect the following commands:
  open, save, save-as, save-to, read-outline-only, read-file-into-node,
  write-file-from-node and all the import/export commands.

- Leo creates the .leo folder in the user's HOME directory, and puts several configuration files there.
  Leo looks for myLeoSettings.leo in HOME/.leo.
  Leo uses os.path.expanduser("~") if there is no home setting.
</t>
<t tx="ekr.20080813064908.2">In version 4.5, Leo changed to using a sax parser for .leo files. This can cause
problems if your .leo file contains invalid characters.
Bugs in previous versions of Leo permitted these bad characters to appear.

The sax parser complains that these characters are not valid in .xml files.
Remove these invalid characters as follows:

1. `run Leo in a console window`_, and load the .leo file.
   Near the bottom of the error message you will see a line like::

    SAXParseException: &lt;unknown&gt;:123:25: not well-formed (invalid token)

   This line reports a bad character at character 25 of line 123.

2. Open the .leo file in an external editor.
   The Scite editor, http://www.scintilla.org/SciTE.html,
   is a good choice because it clearly shows non-printing characters.
   Remove the invalid character, save the .leo file.

Repeat steps 1 and 2 until all invalid characters are gone.
</t>
<t tx="ekr.20080922124033.1">The following code can be run from a script to get input from the user using the minibuffer::

    def getInput (event=None):

       stateName = 'get-input'
       k = c.k
       state = k.getState(stateName)

       if state == 0:
           k.setLabelBlue('Input: ',protect=True)
           k.getArg(event,stateName,1,getInput)
       else:
           k.clearState()
           g.es_print('input: %s' % k.arg)

    getInput()

Let's look at this in detail.  The lines::

    stateName = 'get-input'
    k = c.k
    state = k.getState(stateName)

define a state *name*, 'get-input', unique to this code.
k.getState returns the present state (an int) associated with this state.

When getInput() is first called, the state returned by k.getState will be 0,
so the following lines are executed::

    if state == 0:
        k.setLabelBlue('Input: ',protect=True)
        k.getArg(event,stateName,1,getInput)

These lines put a protected label in the minibuffer:
the user can't delete the label by backspacing.
getArg, and the rest of Leo's key handling code, take care of the extremely
complex details of handling key strokes in states.
The call to getArg never returns.
Instead, when the user has finished entering the input by typing &lt;Return&gt;
getArg calls getInput so that k.getState will return state 1, the value
passed as the third argument to k.getArg.
The following lines handle state 1::

    else:
        k.clearState()
        g.es_print('input: %s' % k.arg)

k.arg is the value returned by k.getArg.
This example code just prints the value of k.arg and clears the input state.
</t>
<t tx="ekr.20080923182326.1">This option applies to directories specified in filenames in all kinds of @file trees, and to filenames specified in the @path directive.

True:  Leo attempts to create directories if they do not exist.
False: Leo never attempts to create directories.
</t>
<t tx="ekr.20081205084002.2">Scripts can easily determine what directives are in effect at a particular
position in an outline. c.scanAllDirectives(p) returns a Python dictionary whose
keys are directive names and whose values are the value in effect at position p.
For example::

    d = c.scanAllDirectives(p)
    g.es(g.dictToString(d))

In particular, d.get('path') returns the full, absolute path created by all
\@path directives that are in ancestors of node p. If p is any kind of @file node
(including @file, @auto, @nosent, @shadow, etc.), the following script will
print the full path to the created file::

    path = d.get('path')
    name = p.anyAtFileNodeName()
    if name:
       name = g.os_path_finalize_join(path,name)
       g.es(name)
</t>
<t tx="ekr.20090116094356.10">\@menuat modifies the menu tree created by \@menus. This allows settings in
myLeoSettings.leo to change menus without copying the entire menu tree from
leoSettings.leo. This ensures you don’t miss out when new things are added in
the @menus in leoSettings.leo, as you would if you replaced the @menus in
leoSettings.leo with one in myLeoSettings.leo.

\@menuat should occur in a \@settings tree, but not as a descendant of a \@menus
tree. Its children are \@menu and \@item nodes as for the
@menu setting.

The @menuat setting has 2-3 parameters in its head text]::

    @menuat *&lt;path&gt;* *&lt;action&gt;* *[clipboard]*

The path argument specifies a **target** in the menu tree as defined by
\@menus and modified by earlier @menuat settings. The path takes the form::

    /entry1/entry2/entry3
    
Each entry is the **cleaned** name of a menu or item. Cleaned names are a
name with all text except a-z and 0-9 removed and upper case letters converted
to lower case. For example, specify::

    Outline-&gt;Move-&gt;Move Down
    
as::
    
     /outline/move/movedown

The action argument specifies what the menu item does. There are 5 available
actions:

- **before**: Insert items and sub menus immediately before the target.
- **after**:  Insert items and sub menus immediately after the target.
- **append**: Append items and sub menus at the end of the target menu or item.
- **cut**:    Remove the target from the menu tree and save it to an internal clipboard.
- **copy**:   Copy the target to an internal clipboard. Descendants of the @menuat setting are ignored.

The cut and copy arguments ignore descendants of the @menuat setting .

The optional clipboard argument modifies the action of the before, after, and
append actions. By default these actions insert the menus and items supplied as
descendants of the @menuat setting. If you specify “clipboard” (without the
quotes) as the source, the contents of the clipboard from a previous cut or copy
action will be used instead.
</t>
<t tx="ekr.20090116094356.11">The body text contains a list of settings for a font.  For example::

    body_text_font_family = Courier New
    body_text_font_size = None
    body_text_font_slant = None
    body_text_font_weight = None

**Important**: you can use the show-fonts minibuffer command to guide you in making these settings.

</t>
<t tx="ekr.20090116094356.12">The body text contains a list of shortcut specifiers.
</t>
<t tx="ekr.20090116094356.13">The body text contains a list of paths of recently opened files, one path per
line. Leo writes the list of recent files to .leoRecentFiles.txt in Leo's
config directory, again one file per line.
</t>
<t tx="ekr.20090116094356.14">Leo now allows you to specify input modes. You enter mode x with the
enter-x-mode command. The purpose of a mode is to create different bindings
for keys within a mode. Often plain keys are useful in input modes.

You can specify modes with @mode nodes in leoSettings.leo. @mode nodes work
just like @shortcuts nodes, but in addition they have the side effect of
creating the enter-&lt;mode name&gt;-mode command.

The form of this node is::

    @mode *&lt;mode name&gt;*

The body text contains a list of shortcut specifiers. @mode nodes work just
like @shortcuts nodes, but in addition they have the side effect of creating
the enter-&lt;mode name&gt;-mode command.

Notes:

- You can exit any mode using the keyboard-quit (Control-g) command. This is the
  **only** binding that is automatically created in each mode. All other bindings
  must be specified in the @mode node. In particular, the bindings specified in
  @shortcuts nodes are **not** in effect in mode (again, except for the
  keyboard-quit binding).

- Leo supports something akin to tab completion within modes: if you type a key
  that isn't bound in a mode a 'Mode' tab will appear in the log pane. This tab
  shows all the keys that you can type and the commands to which they are bound.
  The mode-help command does the same thing.

- @shortcuts nodes specify the bindings for what might be called the 'top-level'
  mode. These are the bindings in effect when no internal state is present, for
  example, just after executing the keyboard-quit command.

- The top_level_unbound_key_action setting determines what happens to
  unbound keys in the top-level mode. Leo ignores unbound keys in all other modes.
  The possibilities are 'insert', 'replace' and 'ignore'.

- The set-insert-mode, set-overwrite-mode and set-ignore-mode
  commands alter what happens to unbound keys in the top-level mode.
  
- If the @mode headline contains ::, everything following
  the :: is the mode prompt. For example::
    
    @mode abc :: xyz
    
Creates the enter-abc-mode command, but the prompt for the command is xyz.

With all these options it should be possible to emulate the keyboard behavior of any other editor.
</t>
<t tx="ekr.20090116094356.2">When reading a .leo file, Leo looks for settings in default settings
files first, then settings in personal settings files, and finally
settings in local settings files.  The exact search order is:

1. Default settings files:

   a. configDir/leoSettings.leo
   b. homeDir/leoSettings.leo
   c. localDir/leoSettings.leo

2. Personal settings files:

   a. configDir/myLeoSettings.leo
   b. homeDir/myLeoSettings.leo
   c. homeDir/&lt;machine-name&gt;LeoSettings.leo (note capitalization)
   d. localDir/myLeoSettings.leo

3. Local settings files:

   a. The file specified by the -c command-line option.
   b. The file being loaded.

Settings that appear later in this list override settings that
appear earlier in this list.  This happens on a setting-by-setting
basis, *not* on a file-by-file basis.  In other words, each individual
setting overrides only the *corresponding* setting in previously-read
files.  Reading a setting file does *not* reset all previous settings.
Note that the same file might appear several times in the search list.
Leo detects such duplicate file names and only loads each settings file once.
Leo remembers all the settings in settings files and does not reread those
settings when reading another .leo file.

**Caution**: This search order offers almost too much flexibility. This can be
confusing, even for power users. It's important to choose the "simplest
configuration scheme that could possibly work".  Something like:

- Use a single leoSettings.leo file for installation-wide defaults.
- Use a single myLeoSettings.leo files for personal defaults.
- Use local settings sparingly.

**Important**: it is good style to limit settings placed in 
myLeoSettings.leo to those settings that differ from default settings.
</t>
<t tx="ekr.20090116094356.3">You should use special care when placing default or personal settings files in
**local** directories, that is, directories other than homeDir, configDir or
machineDir. In particular, the value of localDir can change when Leo reads
additional files. This can result in Leo finding new default and personal
settings files. The values of these newly-read settings files will, as always,
override any previously-read settings.

Let us say that a setting is **volatile** if it is different from a default
setting. Let us say that settings file A.leo **covers** settings file if B.leo
if all volatile settings in B.leo occur in A.leo. With these definitions, the
**safe rule** for placing settings files in local directories is::

   Settings files in local directories should
   cover all other settings files.

Following this rule will ensure that the per-directory defaults specified in the
local settings file will take precedence over all previously-read default and
personal settings files. Ignore this principle at your peril.
</t>
<t tx="ekr.20090116094356.5">An @buttons tree in a settings file defines global buttons that
are created in the icon area of all .leo files.
All @button nodes in the @commands tree create global buttons.
All @button nodes outside the commands tree create buttons local to the settings file.
</t>
<t tx="ekr.20090116094356.6">An \@commands tree in a settings file defines global commands.
All \@command nodes in the @commands tree create global commands.
All \@command nodes outside the commands tree create commands local to the settings file.
</t>
<t tx="ekr.20090116094356.7">The body text contains a list of strings, one per line.
Lines starting with '#' are ignored.
</t>
<t tx="ekr.20090116094356.8" str_atime="1376412853.0">The body text of the @enabled plugins node contains a list of enabled plugins,
one per line. Comment lines starting with '#' are ignored. Leo loads plugins in
the order they appear.
**Important**: Leo handles @enabled-plugins nodes a differently from other kinds
of settings. To avoid confusion, **please read the following carefully**.

As always, Leo looks for @enabled-plugins nodes in settings files in the order
specified by `Search order for settings files`_. Leo will enable all plugins
found in the @enabled-plugins node it finds *last* in the search order. Leo does
*not* enable plugins found in any other @enabled-plugins node. In particular,
**you can not specify a list of default plugins by placing that list in a
settings file that appears early in the search list**. Instead, the last
@enabled-plugins node found in the search list specifies all and *only* the plugins
that will be enabled.

Let us distinguish two different situations. First, what Leo does when loading a
file, say x.leo. Second, what Leo does when loading a second file, say y.leo,
*from x.leo*. When loading the first .leo file, Leo enables plugins from the
@enabled-plugins node it finds *last* in the search order. But after plugins
have *already* been loaded and enabled, there is no way to disable previously
loaded-and-enabled plugins. But local settings files can enable additional
plugins.

To avoid confusion, I highly recommend following another kind of safe rule.
We say that an @enabled-plugin node in file A.leo **covers** an @enabled-plugin
node in file B.leo if all plugins specified in B's @enabled-plugin node appear
A's @enabled-plugin node. The safe rule for plugins is::

  @enabled-plugin nodes in settings files in local directories
  should cover @enabled-plugins nodes in all other settings files.
</t>
<t tx="ekr.20090116094356.9">Leo creates its menus from the @menu, @item and @popup nodes in the @menus tree.
Within @menus trees, @menu nodes create menus and @item nodes create menu items. 

The menu name always follows @menu. If the menu name is 'Plugins', Leo will
create the Plugins menu and populate the menu by calling the
'create-optional-menus' hook. This creates the Plugins menu as usual. Nested
@menu nodes define submenus.

The command name follows @item. If the body text of an @item node exists, this
body text is the menu name. Otherwise, the menu name is the command name.
However, if the command name starts with a '*', hyphens are removed from the
menu name. Menu names and command names may contain a single ampersand (&amp;). If
present, the following character is underlined in the name. If the command
name in an @item node is just a hyphen (-), the item represents a menu
separator.

@popup *&lt;widget-name&gt;* creates a popup menu for use by the rClick plugin.
The children of this node should be @menu and @item nodes, used as with
@menus.
</t>
<t tx="ekr.20090116130002.1">Settings files can be found in the following directories:

- **homeDir**, the HOME/.leo directory. HOME is given by Python's HOME
  environment variable, or by os.expanduser('~') if no HOME environment variable
  exists.

- **configDir**, Leo's configuration directory: leo/config.

- **machineDir**, the HOME/.leo/MACHINE directory. MACHINE is given by Python's
  HOSTNAME environment variable, or by Python's COMPUTERNAME environment
  variable if there is no HOSTNAME variable, or by the value returned by
  socket.gethostname() if neither environment variable exists.

- **localDir**, the directory containing the .leo file being loaded.

In addition, Leo's -c command-line option can specify any .leo file anywhere.
</t>
<t tx="ekr.20090130144433.1">All questions are welcome at http://groups.google.com/group/leo-editor
</t>
<t tx="ekr.20090130144433.2">You can discuss possible bugs at
http://groups.google.com/group/leo-editor

Please report bugs at
http://bugs.launchpad.net/leo-editor

When reporting a bug, please include *all* of the following:

- The version of Leo used.

- The version of Python used.

- The platform or platforms used: Linux, Windows, MacOS.

- A clear description of the problem.

- Information sufficient to recreate the problem.

It's polite to make the bug report self contained, so that six weeks later
somebody will be able to understand the report as it stands.
</t>
<t tx="ekr.20090202191501.7">You can simply unpack Leo anywhere and run from there.  You don't need the
installer.

From a console window, cd to the top-level leo folder.  Run Leo as follows::

    python launchLeo.py

To run Leo with Qt look and feel, use the --gui=qt option::

    python launchLeo.py --gui=qt

To load Leo's source, load leoPyRef.leo::

    python launchLeo.py --gui=qt leo\\core\\leoPyRef.leo
</t>
<t tx="ekr.20090212054250.5"></t>
<t tx="ekr.20090212054250.6">You can get the latest official releases of Leo at
http://sourceforge.net/project/showfiles.php?group_id=3458&amp;package_id=29106

However, if at all possible, it is better to use bzr to get the latest sources.  See the next entry.
</t>
<t tx="ekr.20090212054250.7">Daily snapshots are available at http://www.greygreen.org/leo/
</t>
<t tx="ekr.20090221070927.1">All parts of Leo are distributed under the following copyright. This is intended
to be the same as the MIT license, namely that Leo is absolutely free, even for
commercial use, including resale. There is no GNU-like "copyleft" restriction.
This license is compatible with the GPL.

**Copyright 1997-2013 by Edward K. Ream. All Rights Reserved.**

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.**
</t>
<t tx="ekr.20090223065025.3">Let::

    w = c.frame.body.bodyCtrl # Leo's body pane.

Scripts can get or change the context of the body as follows::

    w.appendText(s)                     # Append s to end of body text.
    w.delete(i,j=None)                  # Delete characters from i to j.
    w.deleteTextSelection()             # Delete the selected text, if any.
    s = w.get(i,j=None)                 # Return the text from i to j.
    s = w.getAllText                    # Return the entire body text.
    i = w.getInsertPoint()              # Return the location of the cursor.
    s = w.getSelectedText()             # Return the selected text, if any.
    i,j = w.getSelectionRange (sort=True) # Return the range of selected text.
    w.replace(i,j,s)                    # Replace the text from i to j by s.
    w.setAllText(s)                     # Set the entire body text to s.
    w.setSelectionRange(i,j,insert=None) # Select the text.

**Notes**:

- These are only the most commonly-used methods.
  For more information, consult Leo's source code.

- i and j are zero-based indices into the the text. When j is not
  specified, it defaults to i. When the sort parameter is in effect,
  getSelectionRange ensures i &lt;= j.

- color is a Tk color name, even when using the Gt gui.
</t>
<t tx="ekr.20090324145450.20"></t>
<t tx="ekr.20090324145450.23">- Leo opens a default .leo file if no other is specified, using the @string
  default_leo_file setting. The default for this setting is::

    ~/.leo/workbook.leo

- Added escapes for underindented lines. The escape is specified by the @string
  underindent-escape-string setting. By default, this escape is \- If a line
  starts with \-N, Leo will write the line with N fewer spaces than expected.

- Leo now warns when attempting to write a file that has been changed outside of
  Leo. This prevents bzr reversions.

- Leo tests syntax of .py files when saving them.

- Leo can now open any file into an @edit node. This allows Leo to be associated
  with the edit action of .py files. Like this::

    C:\Python26\python.exe "c:\leo.repo\trunk\launchLeo.py" --gui=qt %1 %2

- Leo now warns if when writing an @auto node if the the file exists and the
  node has not been read previously.  This prevents a newly-created
  @auto node from overwriting an existing file.
</t>
<t tx="ekr.20090324145450.27">.. _`autoCompleter.getExternalCompletions`: http://groups.google.com/group/leo-editor/browse_thread/thread/4ad91984a6d0acac
.. _`c.getNodePath and c.getNodeFileName`: http://groups.google.com/group/leo-editor/browse_thread/thread/3b5f1232ecc6bba7

- Added `autoCompleter.getExternalCompletions`_.

- Added g.posList.

- c.config.doEnabledPlugins sets g.app.config.enabledPluginsFileName

- Added the following properties:
    - p.b, t.b and v.b return the body string of the position or node.
    - p.h, t.h and v.h return the head string of the position or node.
    - t.u and v.u return the uA of the node.
    - p.gnx, t.gnx and v.gnx return the gnx of the position or node.

- Added script to leoSettings.leo to ensure all menu items are valid.

- c.config.getSettingSource(setting_name)
  returns the name of the file which Leo used to determine the setting:

    - D indicates default settings.
    - F indicates the file being loaded
    - L indicates leoSettings.leo
    - M indicates myLeoSettings.leo

- Predefined 'self' in @test/@suite nodes.

- Added `c.getNodePath and c.getNodeFileName`_.
</t>
<t tx="ekr.20090324145450.36">- The ``--config`` command-line option specifies a single config (.leo) file
  to use for configuration.
  See http://groups.google.com/group/leo-editor/browse_thread/thread/f3f95d93bcd93b94

- The ``--file=fileName`` command-line option loads a file.
  Only .zip and .leo extensions are allowed at present.

- The ``--gui=name`` command-line option specifies the gui to use.
  The valid values are ``--gui=qt`` and ``--gui=tk``.
</t>
<t tx="ekr.20090324145450.40">- Added smart home (back-to-home) command.

- Added support for standard behavior of Tab and Shift-Tab keys.
  The tab key indents the text selection, if there is one;
  otherwise, the tab key insert a tab or blanks, depending on the @tabwidth setting.
  Shift-Tab always unindents one or more lines.

- The open command creates @edit nodes when opening non-.leo files
  The open file dialog now shows all files by default.
  Selecting a non-.leo file will load that file into a new node in the present outline.

- Added added pdb minibuffer command.
  This works, but stops Leo in the middle of the command-handling logic.
  You may get the commander c by stepping out into
  k.masterKeyHandler or k.masterCommandHandler.
  Using c, you can then get all other info.

- Improved the isearch commands.

- find-clone-all is a synonym for clone-find-all.

- open-quickstart-leo command opens leo/doc/quickstart.leo.

- The Alt-Right and Alt-Left keys (expand-and-go-right and contract-or-go-left
  commands) now move to the previous or next node if now left/right movement is
  possible.
</t>
<t tx="ekr.20090324145450.46">- Added @nocolor-node directive.

- Improved \@path handling.
</t>
<t tx="ekr.20090324145450.49">.. _`meta keys`: http://groups.google.com/group/leo-editor/browse_thread/thread/b6a39ed672a28c65?pli=1

- @string default_leo_file = ~/.leo/workbook.leo

- @string underindent-escape-string = \-

- @int icon_bar_widgets_per_row

- Added support for `meta keys`_.

- The qt gui is now the default.

- The old bindings bound the PageUp/Down keys to back/forward page commands, and
  these commands work only for text.

  The new default bindings in leoSettings.leo: @keys EKR bindings are::

    back-page                       ! text = PageUp
    back-page-extend-selection      ! text = Shift-PageUp
    forward-page                    ! text = PageDn
    forward-page-extend-selection   ! text = Shift-PageDn

    scroll-down-half-page   ! tree = Shift-PageDn
    scroll-down-page        ! tree = PageDn
    scroll-up-half-page     ! tree = Shift-PageUp
    scroll-up-page          ! tree = PageUp    

- @bool enable_alt_ctrl_bindings.
  The default is False, needed for AltGr functionality on Windows.
</t>
<t tx="ekr.20090324145450.54">- Improved nav_buttons plugin and corresponding nodeHistory class.

- Created qtGui and tkGui plugins.

- Created leoGuiPluginsRef.leo.

- Leo issues an error message if a non-existent plugin appears
  in an @enabled-plugin node.

- New plugins: spydershell.py, qtframecommands.py, and mod_framesize.py.
</t>
<t tx="ekr.20090401113141.1">To generate .odt or .rtf or .pdf files, you create an intermediate file and
ignore the the "official" output file, in this case test.html. The intermediate
file contains the rST text corresponding to the @rst tree.

To tell the rst3 plugin to generate an intermediate file, do::

    write_intermediate_file = True

After you create the intermediate file, in this case, test.html.txt,
You can create an odt file as follows::

    python &lt;path-to-python&gt;/scripts/rst2odt.py test.html.txt test.odt

I a batch file, rst2odt.bat, like this:

    rst2odt test

Note that rst3odt.py is in the tools directory of the DocUtils distribution.

To generate .rtf, you can use PanDoc to convert test.html.txt to RTF.

To generate .pdf files, you would first convert test.html.txt to LaTeX::

    python rst2newlatex.py test.html.txt test.tex

    -- OR --

    cd leo\docs\html
    make latex

You can then use one of the LaTeX to .pdf converters to create the final .pdf
file. See http://docutils.sourceforge.net/docs/user/latex.html#pdf-generation
for details.
</t>
<t tx="ekr.20090401113141.2">====
Test
====

This is a test.
</t>
<t tx="ekr.20090401113141.4">This is section 1
</t>
<t tx="ekr.20090620073906.12095">- leoDynamicTest.py now supports a ``--path`` argument giving the .leo file.
  This is so useful!

- leoDynamicTest.py now honors the ``--silent`` argument.

- leoTest.runUnitTestLeoFile runs all unit tests in a given .leo file
  in a separate process.

- leoTest.runTestsExternally calls runUnitTestLeoFile after creating
  dynamicUnitTest.leo.

- When reporting that no unit tests were found, all unit tests commands tell
  whether the entire outline or just the selected outline was searched.
  This fixes sometimes-misleading error messages.

- test.leo contains a 'run-test.leo-tests' button.

- leoPy.leo contains a 'run-all-core-tests' button.
</t>
<t tx="ekr.20090620082840.5608">Added support for @auto-rst nodes. These import reStructuredText (rST) files
so that the files can be "round-tripped" without introducing extraneous changes.
This makes Leo a superb environment for using rST.
</t>
<t tx="ekr.20090620131445.5595">I just tweaked conf.py a bit to enable pdf generation.

Howto:

QQQ

4. To create pdf (probably easiest on Linux, with necessary latex
packages installed):

- make latex
- cd _build/latex
- make all-pdf

QQQ

There were several errors in the pdf generation process. Notably,
there are probably lots of unicode errors (and toc doesn't appear).
Nevertheless, you can steal a peek at the doc here:

http://vvtools.googlecode.com/files/Leodocumentation.pdf 
</t>
<t tx="ekr.20090706042206.14718">Leo's sentinels add outline structure to source files.
However, those sentinels annoy some people who don't use Leo.

You can use @auto, @shadow or @nosent trees to edit
files that are shared with those who don't want to see sentinel comments.

- @auto is best for files whose imported outline structure often changes. In
  most cases, this will be the best option. The drawback of @auto files are a)
  you can't use clones and b) you can't add your own organizer nodes.

- @shadow will work for files whose outline structure seldom changes.
  The advantage of @shadow is that you can add your own structure.

- @nosent is appropriate only for files that you alone modify.
</t>
<t tx="ekr.20090711120622.10446">@language rest
</t>
<t tx="ekr.20090711120622.10447">################
Leo screen shots
################

</t>
<t tx="ekr.20090811090022.14452">.. |leoQtMainWindow|    image:: screen-shots/leo-main-window.png

Here is Leo's main window on Windows 7 showing
the outline pane (1),
the body pane (2),
the minibuffer (3),
the log pane, showing the find tab (4).

The body pane shows the contents of the presently selected node in the outline pane.

|leoQtMainWindow|

.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html

.. |renderRST|      image:: screen-shots/render-rst.png
.. |renderSVGref|   image:: screen-shots/render-svg-movie.png
.. |renderSVGsrc|   image:: screen-shots/render-svg-sources.png
.. |renderSplash|   image:: screen-shots/render-splash-screen.png

The following screenshots show Leo's rendering pane.  It can render `reStructuredText`_:

|renderRST|

The rendering pane can render svg pictures, including animated pictures.  Here we see
an .svg file included by reference:

|renderSVGref|

The rendering pane can also render svg sources contained in the body pane:

|renderSVGsrc|

The rendering pane can show pictures, music and movies.  Here we see Leo's splash screen:

|renderSplash|
</t>
<t tx="ekr.20090811090022.14453">.. |LinuxMainWindow| image:: screen-shots/leo-qt-main-window-linux.png

Here is Leo's main window as it appears on Linux:

|LinuxMainWindow|
</t>
<t tx="ekr.20091105080104.9031">When using the Qt gui, you specify fonts
using the node in leoSettings.leo called::

    @data qt-gui-plugin-style-sheet

As usual, you will probably want to put this node in your myLeoSettings.leo file.
</t>
<t tx="ekr.20091111112709.6672">#########
Glossary
#########

.. Links
.. _`Customizing Leo`:              customizing.html
.. _`Writing plugins and hooks`:    writingPlugins.html
.. _`Leo's reference`:              directives.html
.. _`leo's tutorial`:               tutorial.html

This is a short glossary of important terms in Leo's world. For more information
about terms, look in the index for links to discussions in other places,
especially in `Leo's Tutorial`_ and `Leo's Reference`_.

.. glossary::
    :sorted:
</t>
<t tx="ekr.20091130111843.6787">@language rest
</t>
<t tx="ekr.20091130111843.6788">##############
Leo's Tutorial
##############

.. |br| raw:: html

   &lt;br /&gt;

.. index:: Leo's tutorial

.. _`Python`: http://www.python.org/

Leo looks like other outlining programs, but it is not. This tutorial
explains the difference.

This tutorial will get you using Leo quickly, acquainting you with its
key features in one or two hours. It has five parts: 

- (One hour) The first three parts are for all users.

- (One hour) The last two parts are only for computer programmers; |br|
  They assume some familiarity with `Python`_ programming. 
    
.. toctree::
    :maxdepth: 3
    
    tutorial-basics
    tutorial-pim
    tutorial-rst3
    tutorial-programming
    tutorial-scripting
</t>
<t tx="ekr.20100122073254.11655">This section describes the process of creating an importer for a new language.
There are a set of "importers" in leoImport.py, all based on the
baseScannerClass class. You can define your own importer by creating a subclass.
This shouldn't be too difficult: baseScannerClass is supposed to do almost all
the work. With luck, your subclass might be very simple, as with class cScanner.

**Important** As I write this, I realize that I remember very little about the
code, but I do remember its general organization and the process of creating a
new importer. The following should be all you need to write any importer.

This base class has three main parts:

1. The "parser" that recognizes where nodes begin and end.

2. The "code generator" the actually creates the imported nodes.

3. Checking code that ensures that the imported code is equivalent
   to the original code.

You should never have to change the code generators or the checking code.
Confine your attention to the parser.

The parser thinks it is looking for classes, and within classes,
method definitions.  Your job is to tell the parser how to do this.
Let's look at part of the ctor for baseScannerClass for clues::

   # May be overridden in subclasses.
   self.anonymousClasses = [] # For Delphi Pascal interfaces.
   self.blockCommentDelim1 = None
   self.blockCommentDelim2 = None
   self.blockCommentDelim1_2 = None
   self.blockCommentDelim2_2 = None
   self.blockDelim1 = '{'
   self.blockDelim2 = '}'
   self.blockDelim2Cruft = [] # Stuff that can follow .blockDelim2.
   self.classTags = ['class',] # tags that start a tag.
   self.functionTags = []
   self.hasClasses = True
   self.hasFunctions = True
   self.lineCommentDelim = None
   self.lineCommentDelim2 = None
   self.outerBlockDelim1 = None
   self.outerBlockDelim2 = None
   self.outerBlockEndsDecls = True
   self.sigHeadExtraTokens = [] # Extra tokens valid in head of signature.
   self.sigFailTokens = []
       # A list of strings that abort a signature when seen in a tail.
       # For example, ';' and '=' in C.
   self.strict = False # True if leading whitespace is very significant.

Naturally, this looks like gibberish at first. I do *not* remember what all
these things do in detail, although obviously the names mean something. What I
*do* remember is that these ivars control the operation of the startsFunction
and startsClass methods and their helpers (especially startsHelper) and
the methods that call them, scan and scanHelper. Most of these methods have a
trace var that will enable tracing during importing.

So the strategy is simple: study startsHelper in detail, set the ivars above to
make startsHelper do what you want, and trace until things work as you want.

There is one more detail. Sometimes the ivars above are not sufficient to get
the job done. In that case, subclasses will override various methods of the
parser, but *not* the code generator. If indentation is important, you will want
to look at the Python importer. Notice that it overrides skipCodeBlock, called
by startsHelper.

That's about it. It would be pointless to give you more details, because those
details would lead you *away* from the process you need to follow. Having said
that, feel free to ask further questions. I'll be glad to answer them.
</t>
<t tx="ekr.20100129054823.11924"></t>
<t tx="ekr.20100129054823.11928">- Leo now treats @file nodes just like it treats @thin nodes. This makes Leo
  much safer to use in cooperative environments that use source code control
  systems. As part of this change, Leo no longer supports @noref nodes.

- @auto-rst now works much more reliably.

- Leo now has a simple, robust, and extremely useful scheme to recover from
  clone conflicts, no matter how they may arise. This removes all the dread from
  "node changed" messages. It is easy to see what the changes were, and it is
  easy to choose what, if anything to do.

  When a clone conflict occurs, you will see a red message in the log pane and a
  "Recovered Nodes" node as the last top-level node. This node has one child per
  red message. Each of these children contains two nodes: an "old" node and a
  "new" node. Unless there are multiple conflicts for a single node, the "new"
  node will have "won": every clone contains the new node's headline and body
  text. All these nodes are plain nodes, *not* clones. It is up to you to change
  the corresponding clone nodes if you choose to do so.

- Leo minimizes unnecessary changes to .leo files. Leo writes outline-size and
  orientation to the cache in your .leo directory. This eliminates unnecessary
  changes to .leo files.

- Leo now creates temporary files in the systems standard temporary directory.
  This prevents Leo from over-writing user-generated .bak files.
</t>
<t tx="ekr.20100129054823.11931">- The ``--debug`` command-line option sets g.debug.

- The ``--version`` command-line option causes Leo
  to print it's version and exit.

</t>
<t tx="ekr.20100129054823.11934">The qt colorizer now supports font specifications in @font nodes.
</t>
<t tx="ekr.20100129054823.11935">Added options for vim plugin. The setting::

    @string vim_trigger_event = icondclick2

is the default. It opens vim when the user double-clicks the icon box.
Alternatives are::

    @string vim_trigger_event = iconclick2
    @string vim_trigger_event = select2

The former opens vim on single clicks in the icon bar.
The latter opens vim whenever a new node is selected in Leo.

</t>
<t tx="ekr.20100129054823.17680">Leo requires Python 2.6 or above, including Python 3.0 and above.
</t>
<t tx="ekr.20100211221936.7098">- The clear-cache and clear-all-caches commands.
</t>
<t tx="ekr.20100506062734.11593">The mod_scripting plugin runs @scripts before plugin initiation is complete.
Thus, such scripts can not directly modify plugins. Instead, a script can create
an event handler for the after-create-leo-frame that will modify the plugin.

For example, the following modifies the cleo.py plugin after Leo has completed loading it::

    def prikey(self, v):
        try:
            pa = int(self.getat(v, 'priority'))
        except ValueError:
            pa = -1

        if pa == 24:
            pa = -1
        if pa == 10:
            pa = -2

        return pa

    import types
    from leo.core import leoPlugins

    def on_create(tag, keywords):
        c.cleo.prikey = types.MethodType(prikey, c.cleo, c.cleo.__class__)

    leoPlugins.registerHandler("after-create-leo-frame",on_create)

Attempting to modify c.cleo.prikey immediately in the @script gives an
AttributeError as c has no .cleo when the @script is executed. Deferring it by
using registerHandler() avoids the problem.
</t>
<t tx="ekr.20100731112744.7274">If you are using Debian/Ubuntu, find and install the debian package. This
provides the best integration with your desktop (file associations, icons, launcher
item). Failing that, follow the instructions below.

You may download Leo's sources in one of three ways, as described at:
http://leoeditor.com/download.html If the sources are zipped, unzip them
into the **unpacked folder** in your home directory. The unpacked folder
will be called something like leo-4-11.

You now have two choices:

1. You can run Leo from your home directory.
   Just add  ~/leo-4-5 to your path.

2. You can install leo into /usr/local/lib and /usr/local/bin by running Leo's install script as follows::

    cd ~/leo-4-11-final # Change version as appropriate.
    chmod u+x install
    sudo ./install

The install script will instruct you to add /usr/local/bin to your path.
You can, instead, add the following link::

    sudo ln -s /usr/local/lib/leo/ /usr/local/lib/python2.6/site-packages/

That's it!  See `Running Leo`_ for how to run Leo after installing it.
</t>
<t tx="ekr.20100731112744.7275">**Important**: Installing Leo on MacOS is difficult and not recommended.
Furthermore, Leo does not work as well on MacOS as on other platforms.

Here is how to install Leo on MacOS 10.5 (Leopard):

1. MacOS 10.5 comes with Python pre-installed.

   See http://www.python.org/download/mac/ and
   http://wiki.python.org/moin/MacPython/Leopard
   for information about using the latest version of Python.

2. Download and install bzr:

   - Download bzr from http://bazaar-vcs.org/Download

   - Install bzr using the file just downloaded.

3. Get Leo's sources from Leo's trunk::

    cd ~
    mkdir leo.repo
    cd leo.repo
    bzr init
    bzr branch lp:leo-editor
    cd leo-editor

4. If you already have Qt and PyQt installed, you can run the qt version of Leo as follows::

    python launchLeo.py --gui=qt

5. If you don't have Qt or PyQt installed, you will have to install Qt and PyQt
    from sources. There does not seem to be any pre-built binaries.

    A: You may need to install XCode from http://developer.apple.com/mac/
       in order to get a development environment.

    B: Download and install the sip package, following the direction at
       http://www.riverbankcomputing.co.uk/software/sip/download

    C: Download the OpenSource Qt libraries for Mac from
       http://www.qtsoftware.com/downloads

    D: At various points along the way you will need to build the sources::

         python configure.py 
         make
         sudo make install
</t>
<t tx="ekr.20100731112744.7276">Install Python and Qt, as described above (`Installing Packages`_).

Now you have a choice.  You can use Leo's binary (single-click) installer
or download Leo's sources directly.
</t>
<t tx="ekr.20100804133903.7250">.. index::
    pair: @; Glossary

\@
    Starts a doc part. Doc parts continue until an \@c
    directive or the end of the body text.

.. index::
    pair: @@ convention for headlines; Glossary

\@@ convention for headlines
    Within \@asis trees only, if a headline starts with \@@, Leo
    writes everything in the headline following the \@@ just before the
    corresponding body text.

.. index::
    pair: @&lt;file&gt; node; Glossary

\@&lt;file&gt; node
    A node whose headline starts with
    @asis, @edit, @file, @nosent, @shadow, @thin, or their longer forms.
    We often refer to outline nodes by the directives they contain.
    For example, an @file node is a node whose headline starts with @file, etc.

.. index::
    pair:  @all; Glossary

\@all
    Copies the body text of all nodes in an @file tree to the external file.

.. index::
    pair: @asis; Glossary

\@asis &lt;filename&gt;
    Creates an external file containing no Leo sentinels directly from the @asis tree.

.. index::
    pair: @auto; Glossary

\@auto &lt;filename&gt;

    Imports an external file into the Leo outline, splitting the file into
    pieces if an importer exists for the give filetype. Importers presently
    exist for the following languages: C, C++, C#, HTML, INI files, Java, PHP,
    Pascal, Python and XML.

.. index::
    pair: @c; Glossary
    pair: @code; Glossary

\@c and \@code

    Ends a doc part and starts a code part.

.. index::
    pair: @chapter; Glossary
    pair: @chapters; Glossary

\@chapter and \@chapters

    An \@chapter tree represents a chapter. All @chapter nodes should be
    contained in an \@chapters node.

.. index::
    pair: @color; Glossary

\@color

    Enables syntax coloring in a node and its descendants until the next
    \@nocolor directive.

.. index::
    pair: @comment; Glossary

\@comment

    Sets the comment delimiters in \@thin, \@file and \@shadow files.

.. index::
    pair: @delims; Glossary

\@delims

  Sets the comment delimiters in \@thin, \@file and \@shadow files.

.. index::
    pair: @edit; Glossary

\@edit &lt;filename&gt;

    Reads an entire external file into a single node.

.. index::
    pair: @encoding; Glossary

\@encoding &lt;encoding&gt;

    Specifies the Unicode encoding for an external file.

.. index::
    pair: @end_raw; Glossary

\@end_raw

    Ends a section of 'raw' text.

.. index::
    pair: @file; Glossary

\@file &lt;filename&gt;

    Creates an external file containing sentinels. When writing \@file
    trees, Leo expands section references and \@all and \@others directives.

    **Important**: \@file is the recommended way to create and edit most files.
    Using \@file trees is **highly recommended** when sharing external files in
    a collaborative environment.

.. index::
    pair: @first; Glossary

\@first &lt;text&gt;

    The \@first directive allows you to place one or more lines at the very start of an
    external file, before the first sentinel. For example::

	    @first #! /usr/bin/env python

.. index::
    pair: @killcolor; Glossary

\@killcolor

    Completely disables syntax coloring in a node, regardless of other directives.

.. index::
    pair: @language; Glossary

\@language &lt;language name&gt;

    Specifies the source language, which affects syntax coloring and the
    comments delimiters used in external files and syntax coloring.

.. index::
    pair: @last; Glossary

\@last &lt;text&gt;

    Allows you to place lines at the very end of external files, after the last
    sentinel. For example::

        @first &lt;?php
        ...
        @last ?&gt;

.. index::
    pair: @lineending; Glossary

\@lineending cr/lf/nl/crlf

    Sets the line endings for external files.

.. index::
    pair: @nocolor; Glossary

\@nocolor

    Disables syntax coloring in a node and its descendants until the next \@color
    directive.

.. index::
    pair: @nocolor-node; Glossary

\@nocolor-node

    Completely disables coloring for one node. Descendant nodes are not affected.

.. index::
    pair: @nosent; Glossary

\@nosent

    Creates an external file containing no sentinels. Unlike \@asis, sections
    references and the @all and @others directives are valid in \@nosent trees.

.. index::
    pair: @nowrap; Glossary

\@nowrap

    Disables line wrapping the Leo's body pane.

.. index::
    pair: @others; Glossary

\@others

    Copies the body text of all nodes *except* section definition nodes in an
    \@file tree to the corresponding external file.

.. index::
    pair: @pagewidth; Glossary

\@pagewidth &lt;n&gt;

   Sets the page width used to break doc parts into lines.

.. index::
    pair: @path; Glossary

\@path &lt;path&gt;

  Sets the path prefix for relative filenames for descendant \@&lt;file&gt; directives.

.. index::
    pair: @raw; Glossary

\@raw
    Starts a section of "raw" text that ends *only* with the
    \@end_raw directive or the end of the body text.

.. index::
    pair: @tabwidth; Glossary

\@tabwidth &lt;n&gt;

    Sets the width of tabs. Negative tab widths cause Leo to convert tabs to
    spaces.

.. index::
    pair: @thin; Glossary

\@thin &lt;filename&gt;

    A synonym for @file.

.. index::
    pair: @wrap; Glossary

\@wrap

    Enables line wrapping in Leo's body pane.
</t>
<t tx="ekr.20100804133903.7251">.. index::
    pair: Body pane; Glossary

Body pane

    The pane containing the body text of the currently selected headline in the
    outline pane.

.. index::
    pair: Body text; Glossary

Body text

    The text in the body pane. That is, the contents of a node.

.. index::
    pair: Body text box; Glossary

Body text box

    A small blue box in the icon box indicating that the node contains body
    text.

.. index::
    pair: Child; Glossary

Child

    The direct descendant of a node.

.. index::
    pair: Clone; Glossary

Clone
    A copy of a tree that changes whenever the original changes.
    The original and all clones are treated equally:
    no special status is given to the "original" node.

.. index::
    pair: Clone arrow; Glossary

Clone arrow

    A small red arrow in the icon box indicating that the node is a clone.

.. index::
    pair: Code part; Glossary

Code part

    A part of a section definition that contains code. Code parts start with @c
    or @code directives and continue until the next doc part.

.. index::
    pair: Contract; Glossary

Contract:

    To hide all descendants of a node.
</t>
<t tx="ekr.20100804133903.7252">.. index::
    pair: Demote; Glossary

Demote
    To move all siblings that follow a node so that they become children of the node.

.. index::
    pair: Descendant; Glossary

Descendant
    An offspring of a node.  That is, a child, grandchild, etc. of a node.

.. index::
    pair: Directive; Glossary

Directive

    A keyword, preceded by an '@' sign, in body text that controls Leo's
    operation. The keyword is empty for the \@ directive.

.. index::
    pair: Doc part; Glossary

Doc part

    A part of a section definition that contains comments. Doc parts start with
    @ and continue until the @c directive or the end of the body text.

.. index::
    pair: Escape convention; Glossary

.. _`noweb`: http://www.eecs.harvard.edu/~nr/noweb/

Escape convention

    A convention for representing sequences of characters that would otherwise
    have special meaning. **Important**: Leo does not support escape conventions
    used by `noweb`_. Any line containing matched &lt;\&lt; and &gt;\&gt; is a section
    reference, regardless of context. To use &lt;\&lt; and &gt;\&gt; as ordinary characters,
    place them on separate lines.

.. index::
    pair: Expand; Glossary

Expand

    To make the children of a node visible.

.. index::
    pair: External file; Glossary

External file

    A file outside of Leo that is connected to Leo by an \@&lt;file&gt; node.

.. index::
    pair: Grandchild; Glossary

Grandchild

    The child of a child of a node.
</t>
<t tx="ekr.20100804133903.7253">.. index::
    pair: Headline; Glossary

Headline

    The headline text of a node.  The part of the node visible in the outline pane.

.. index::
    pair: Hoist; Glossary
    pair: Dehoist; Glossary

Hoist &amp; dehoist

    Hoisting a node redraws the screen that node and its descendants becomes the
    only visible part of the outline. Leo prevents the you from moving nodes
    outside the hoisted outline. Dehoisting a node restores the outline.
    Multiple hoists may be in effect: each dehoist undoes the effect of the
    immediately preceding hoist.

.. index::
    pair: Icon box; Glossary

Icon box

    An icon just to the left of headline text of a node indicating whether the
    node is cloned, marked or dirty, and indicating whether the node contains
    body text.

.. index::
    pair: Log pane; Glossary

Log Pane

    The part of Leo's main window that shows informational messages from Leo. It
    also contains the Find tab, the Spell tab, the autocompletion tab.
</t>
<t tx="ekr.20100804133903.7254">.. index::
    pair: Mark; Glossary

Mark

    A red vertical line in the icon box of a node.

.. index::
    pair: Node; Glossary

Node

    The organizational unit of an outline. The combination of headline text and
    body text. Sometimes used as a synonym for tree.

.. index::
    pair: Offspring; Glossary

Offspring

    A synonym for the descendants of a node.
    The children, grandchildren, etc. of a node.

.. index::
    pair: Organizer node; Glossary

Organizer node

    A node containing no body text. Organizing nodes may appear anywhere in an
    @file tree; they do not affect the external file in any way. In particular,
    organizing nodes do not affect indentation in external files.

.. index::
    pair: Orphan node; Glossary

Orphan node

    A node that would not be copied to a external file. Orphan nodes can arise
    because an @file tree has no @others or @all directives. Sections that are
    defined but not used also create orphan nodes.

    Leo issues a warning when attempting to write an @file tree containing
    orphan nodes, and does not save the external file. No information is lost;
    Leo saves the information in the @file tree in the .leo file. Leo will load
    the @file tree from the .leo file the next time Leo opens the .leo file.

.. index::
    pair: Outline; Glossary

Outline

    A node and its descendants. A tree. All the nodes of a .leo file.

.. index::
    pair: Outline order; Glossary

Outline order

    The order that nodes appear on the screen when all nodes are expanded.

.. index::
    pair: Outline pane; Glossary

Outline pane

    The pane containing a visual representation of the entire outline, or a part
    of the outline if the outline is hoisted.
</t>
<t tx="ekr.20100804133903.7255">.. index::
    pair: Parent; Glossary

Parent

    The node that directly contains a node.

.. index::
    pair: Plugin; Glossary

Plugin

    A way to modify and extend Leo without changing Leo's core code.
    See `Writing plugins and hooks`_.

.. index::
    pair: Promote; Glossary

Promote

    To move all children of a node in an outline so that they become siblings of
    the node.

.. index::
    pair: reStructuredText; Glossary
    pair: rST; Glossary

.. _`rST primer`: http://docutils.sourceforge.net/docs/user/rst/quickstart.html

reStructuredText (rST)

    A simple, yet powerful markup language for creating .html, or LaTeX output
    files. See the `rST primer`_.

.. index::
    pair: Root; Glossary

Root

    The first node of a .leo file, outline, suboutline or @&lt;file&gt; tree.
</t>
<t tx="ekr.20100804133903.7256">.. index::
    pair: Section; Glossary

Section

    A fragment of text that can be incorporated into external files.

.. index::
    pair: Section definition; Glossary

Section definition

    The body text of a section definition node.

.. index::
    pair: Section definition node; Glossary

Section definition node

    A node whose headline starts with a section name and whose body text defines
    a section.

.. index::
    pair: Section name; Glossary

Section name

    A name enclosed in &lt;\&lt; and &gt;\&gt;. Section names may contain any characters
    except newlines and "&gt;&gt;".

.. index::
    pair: Section reference; Glossary

Section reference

    A section name appearing in a code part. When writing to an external file,
    Leo replaces all references by their definitions.

.. index::
    pair: Sentinel; Glossary

Sentinel

    Comment lines in external files used to represent Leo's outline structure.
    Such lines start with an \@ following the opening comment delimiter.
    Sentinels embed outline structure into external files.

    **Do not alter sentinel lines**. Doing so can corrupt the outline structure.

.. index::
    pair: Setting; Glossary

Settings:

    Plugins and other parts of Leo can get options from @settings trees,
    outlines whose headline is @settings. When opening a .leo file, Leo looks
    for @settings trees in the outline being opened and also in various
    leoSettings.leo files. @settings trees allow plugins to get options without
    any further support from Leo's core code. For a full discussion of @settings
    trees, see `Customizing Leo`_.

.. index::
    pair: Sibling; Glossary

Sibling

    Nodes with the same parent. Siblings of the root node have the hidden root
    node as their parent.

.. index::
    pair: Target language; Glossary

Target language

    The language used to syntax color text. This determines the default comment
    delimiters used when writing external files.

.. index::
    pair: Tree; Glossary

Tree

    An outline. A node and its descendants.

.. index::
    pair: Underindented Line; Glossary

Underindent line

    A line of body text that is indented less then the starting line of the
    class, method or function in which it appears. Leo outlines can not
    represent such lines exactly: every line in an external file will have at
    least the indentation of any unindented line of the corresponding node in
    the outline.

.. index::
    pair: View node; Glossary

View node

    A node that represents a view of an outline. View nodes are typically
    ordinary, non-cloned nodes that contain cloned descendant nodes. The cloned
    descendant nodes comprise most of the data of the view. Other non-cloned
    nodes may add additional information to the view.
</t>
<t tx="ekr.20100804133903.7262">This section is a reference guide for all other Leo directives, organized
alphabetically.

Unless otherwise noted, all directives listed are valid only in body text,
and they must start at the leftmost column of the node.

.. glossary::
     :sorted:

.. index::
    pair: @; Reference
.. index::
    pair: @doc; Reference
.. index::
    pair: Doc part; Reference

\@ and \@doc

    These directives start a doc part. \@doc is a synonym for \@. Doc parts
    continue until an \@c directive or the end of the body text. For example::

        @ This is a comment in a doc part.
        Doc parts can span multiple lines.
        The next line ends the doc part
        @c

    When writing external files, Leo writes doc parts as comments.

    Leo does not recognize \@ or \@doc in \@asis trees or when the \@all or
    \@delims directives are in effect.

.. index::
    pair: @c; Reference
.. index::
    pair: @code; Reference

\@c and \@code

    Ends any doc part and starts a code part.

    \@code is a deprecated synonym for \@c.

    Leo does not recognize this directive in \@asis trees or when the
    \@all or \@raw directives are in effect.

.. index::
    pair: @chapter; Reference
.. index::
    pair: @chapters; Reference

\@chapter and \@chapters

    An \@chapter tree represents a chapter. All @chapter nodes should be
    contained in an \@chapters node.

    These directives are too complex to describe here. For full details, see
    `Using Chapters`_.

    These directives must appear in the node's headline.

.. index::
    pair: @encoding; Reference

\@encoding &lt;encoding&gt;

    Specifies the Unicode encoding for an external file. For example::

        @encoding iso-8859-1

    When reading external files, the encoding given must match the encoding
    actually used in the external file or "byte hash" will result.

.. index::
    pair: @first; Reference

\@first &lt;text&gt;

    Places lines at the very start of an external file, before any Leo
    sentinels. \@first lines must be the very first lines in an \@&lt;file&gt; node.
    More then one \@first lines may appear.

    This creates two first lines, a shebang line and a Python encoding line::

        @first #! /usr/bin/env python
        @first # -*- coding: utf-8 -*-

    Here is a perl example::

        @first #!/bin/sh -- # perl, to stop looping
        @first eval 'exec /usr/bin/perl -w -S $0 ${1+"$@"}'
        @first     if 0;

\@ignore

    Tells Leo to ignore the subtree in which it appears.

    In the body text of most top-level @&lt;file&gt; nodes, the \@ignore directive
    causes Leo not to write the tree. However, Leo ignores \@ignore directives
    in \@asis trees.

    Plugins and other parts of Leo sometimes @ignore for their own purposes. For
    example, Leo's unit testing commands will ignore trees containing @ignore.
    In such cases, the \@ignore directive may appear in the headline or body
    text.

.. index::
    pair: @language; Reference

\@language &lt;language name&gt;

    Specifies the language in effect, including comment delimiters.
    If no \@language directive is in effect, Leo uses the defaults specified
    by the \@string target-language setting.

    A node may contain at most one \@language directive.

    The valid language names are: actionscript, ada, autohotkey, batch, c, config,
    cpp, csharp, css, cweb, elisp, forth, fortran, fortran90, haskell, haxe,
    html, ini, java, javascript, kshell, latex, lua, noweb, pascal, perl,
    perlpod, php, plain, plsql, python, rapidq, rebol, rest, rst, ruby, shell,
    tcltk, tex, unknown, unknown_language, vim, vimoutline, xml, xslt.

    **Note**: Shell files have comments that start with #.

    Case is ignored in the language names. For example, the following are
    equivalent::

        @language html
        @language HTML

    The \@language directive also controls syntax coloring. For language x, the
    file leo/modes/x.py describes how to colorize the language. To see the
    languages presently supported, look in the leo/modes directory. There are
    over 100 such languages.

.. index::
    pair: @last; Reference

\@last &lt;text&gt;

    Places lines at the very end of external files.

    This directive must occur at the very end of top-level \@&lt;file&gt; nodes. More
    than one \@last directive may exist. For example::

        @first &lt;?php
        ...
        @last ?&gt;

    Leo does not recognize \@last directive in \@asis trees.

.. index::
    pair: @lineending; Reference

\@lineending cr/lf/nl/crlf

    Sets the line endings for external files.
    This directive overrides the \@string output_newline setting.

    The valid forms of the @lineending directive are:

    ========================   ======================================================
    \@lineending nl            The default, Linux.
    ------------------------   ------------------------------------------------------
    \@lineending cr            Mac
    ------------------------   ------------------------------------------------------
    \@lineending crlf          Windows
    ------------------------   ------------------------------------------------------
    \@lineending lf            Same as 'nl', not recommended
    ------------------------   ------------------------------------------------------
    \@lineending platform      Same as platform value for output_newline setting.
    ========================   ======================================================

.. index::
    pair: @nowrap; Reference

\@nowrap

    Disables line wrapping the Leo's body pane.

    Only the first \@wrap or \@nowrap directive in a node has any effect.

    \@nowrap may appear in either headlines or body text.

..  If \@others occurs multiple times in the same node, all non-section nodes
..  appear at the location of the first instance of the \@others directive; the
..  remainder are remembered as sentinels but have no other content.

.. index::
    pair: @pagewidth; Reference

\@pagewidth &lt;n&gt;

   Sets the page width used to break doc parts into lines.
   &lt;n&gt; should be a positive integer.  For example::

      @pagewidth 100

  The \@pagewidth directive overrides the \@int page_width setting.

.. index::
    pair: @path; Reference
.. index::
    pair: Absolute path; Reference
.. index::
    pair: Path prefix; Reference

\@path &lt;path&gt;

   Sets the **path prefix** for relative filenames for all \@&lt;file&gt; tree.

   This directive may appear in headlines or body text, and may
   appear in top-level \@&lt;file&gt; nodes.

   The path is an **absolute path** if it begins with c:\\ or /,
   otherwise the path is a **relative** paths.

   Multiple \@path directives may contribute to the path prefix.
   Absolute paths overrides any ancestor \@path directives.
   Relative paths add to the path prefix.

   If no \@path directives are in effect, the default path prefix is
   the directory containing the .leo file.

   Within @path and @&lt;file&gt; paths, {{exp}} gets evaluated with the following
   symbols known: c, g, p, os and sys.  For example::

       @file {{os.path.abspath(os.curdir)}}/abc.py

   refers to the file abc.py in (absolute path of) the current directory.

.. index::
    pair: @tabwidth; Reference
.. index::
    pair: Negative tab width; Reference

\@tabwidth &lt;n&gt;

  Sets the width of tabs.
  Negative tab widths cause Leo to convert tabs to spaces.

.. index::
    pair: @wrap; Reference

\@wrap

    Enables line wrapping in Leo's body pane.

    Only the first \@wrap or \@nowrap directive in a node has any effect.

    \@wrap may appear in either headlines or body text.
</t>
<t tx="ekr.20100805171546.4412">This section contains files used to generate Leo's web site,
including Leo's home page.</t>
<t tx="ekr.20100806170836.4392">.. index::
    pair: @&lt;file&gt;; Reference

This section discusses the \@&lt;file&gt; directives. These directives create or
import external files.

**Important**: Newcomers to Leo should create external files with \@auto or
\@file. Use \@auto if your external files must not contain sentinel lines. Use
\@file otherwise. In particular, \@file is **highly recommended** when sharing
external files in a collaborative environment.

**Note**: All these directive must appear in headlines.

The following table summarizes the various ways of creating external files.

+---------+------------+------------------+-----------------+
|         | Sentinels  | Sections and     | File data stored|
| Kind    | in external| @others expanded | in .leo file?   |
|         | file?      | on write?        |                 |
+---------+------------+------------------+-----------------+
| @asis   | no         | no               | yes             |
+---------+------------+------------------+-----------------+
| @auto   | no         | yes              | no              |
+---------+------------+------------------+-----------------+
| @edit   | no         | no               | no              |
+---------+------------+------------------+-----------------+
| @nosent | no         | yes              | yes             |
+---------+------------+------------------+-----------------+
| @shadow | Note 1     | yes              | no              |
+---------+------------+------------------+-----------------+
| @file   | yes        | yes              |                 |
| @thin   |            |                  | no              |
| Note 2  |            |                  |                 |
+---------+------------+------------------+-----------------+

**Note 1**: \@shadow nodes create two files, a **public** file without sentinels
and a **private** file with sentinels.

**Note 2**: \@file and \@thin nodes are synonyms.

Within @path and @&lt;file&gt; paths, {{exp}} gets evaluated with the following
symbols known: c, g, p, os and sys.  For example::

    @file {{os.path.abspath(os.curdir)}}/abc.py

refers to the file abc.py in (absolute path of) the current directory.

</t>
<t tx="ekr.20100806170836.4393">.. index::
    pair: @asis; Reference

The \@asis directive creates an external file without sentinels and without any
expansions.

Use this directive only when you must have complete control over every character
of the external file. When writing \@asis nodes, writes the body text of all
nodes in outline order. Leo writes the body text *as is*, without recognizing
section definitions, without expanding section references, and without treating
directives specially in any way. In particular, Leo copies all directives,
including \@ or \@c directives, to the external file as text.

.. index::
    pair: @@ convention in @asis trees; Reference

**The @@ convention**: Within \@asis trees only, if a headline starts with \@@,
Leo writes everything in the headline following the \@@ just before the
corresponding body text.

Files created from \@asis trees contain *nothing* not contained in body text (or
\@@ headlines). In particular, if body text does not end in a newline, the first
line from the next node will concatenated to the last line of the preceding
node.

Within \@asis trees, Leo writes no sentinels to the external file, so Leo can not update the outline
using changes to the external file. When reading .leo files, Leo does *not* read
external files created from \@asis nodes. Instead, all data in an \@asis tree is
stored in the .leo file.

Within \@asis trees, Leo recognizes the \@ignore directive only in the
*ancestors* of \@asis nodes. This allows you to use the \@ignore directive to
prevent Leo from writing \@asis trees.

**Note**: \@file-asis and \@silent are deprecated synonyms for \@asis.
</t>
<t tx="ekr.20100806170836.4395">.. index::
    pair: @edit; Reference

The \@edit directive imports an external file into a single node.

When reading \@edit nodes, Leo reads the entire file into the \@edit node. Lines
that look like sentinels will be read just as they are.

When writing \@edit nodes, \@edit nodes must not have children and section
references and @others are not allowed.
</t>
<t tx="ekr.20100806170836.4396">.. index::
    pair: @auto; Reference

The \@auto directive imports an external file into a tree of nodes. Using \@auto
is *highly recommended* when using external files that must not contain Leo
sentinels.

\@auto trees allow people to use Leo in collaborative environments without using
sentinels in external files. Even without sentinels, \@auto trees can change
when the corresponding external file changes outside of Leo.

.. index::
    pair: Importer; Reference

When reading \@auto nodes, Leo creates the \@auto tree using **importers**,
parsers that create an outline with nodes for each class, method and function in
the external file. Some importers create other kinds of nodes as well.

Importers presently exist for C, elisp, HTML, .ini files, Java, Javascript, Pascal, PHP,
Python and xml. Leo determines the language using the file's extension. If no
parser exists for a language, Leo copies the entire body of the external file
into the \@auto node.

.. index::
    pair: Organizer tag; Reference

**Note**: the \@data import_xml_tags setting specifies the **organizer tags**
that cause the HTML and XML importers to create outline nodes. By default, the
**organizer tags** are html, body, head, and div.

When writing \@auto nodes, Leo writes the external file without sentinels. This
allows you to use Leo in collaborative environments without disturbing colleagues.

When importing files into \@auto trees, Leo performs several checks to ensure
that writing the imported file will produce exactly the same file. These checks
can produces **errors** or **warnings**. Errors indicate a potentially serious
problem. Leo inserts an \@ignore directive in the \@auto tree if any error is
found. This prevents the \@auto tree from modifying the external file.

.. index::
    pair: Strict language; Reference

Before importing a file, Leo **regularizes** the leading whitespace of all
lines of the original source file. That is, Leo converts blanks to tabs or
tabs to blanks depending on the value of the \@tabwidth directive in effect
for the \@auto node. Leo also checks that the indentation of any non-blank
line is a multiple of the indentation specified by the \@tabwidth directive.
**Strict languages** are languages such as Python for which leading
whitespace must be preserved exactly as it appears in the original source
file. Problems during regularizing whitespace generate errors for strict
languages and warnings for non-strict languages.

After importing a file, Leo verifies that writing the \@auto node would create
the same file as the original file. Such file comparison mismatches
generate errors unless the problem involves only leading whitespace for
non-strict languages. Whenever a mismatch occurs the first non-matching line is
printed.

File comparison mismatches can arise for several reasons:

1. Bugs in the import parsers. Please report any such bugs immediately.

2. Underindented lines in classes, methods or function.

.. index::
    pair: Underindented line; Reference

An **underindented line** is a line of body text that is indented less then the
starting line of the class, method or function in which it appears. Leo outlines
can not represent such lines exactly: every line in an external file will have
at least the indentation of any unindented line of the corresponding node in the
outline. Leo will issue a warning (not an error) for underindented Python
comment lines. Such lines can not change the meaning of Python programs.
</t>
<t tx="ekr.20100806170836.4398">The \@color, \@killcolor, \@nocolor and \@nocolor-node directives control how
Leo colors text in the body pane.

.. index::
    pair: Ambiguous node; Reference

These directives typically affect the node in which they appear and all
descendant nodes. Exception: an **ambiguous node**, a node containing both
\@color and \@nocolor directives, has no effect on how Leo colors text in
descendant nodes.

.. glossary::
    :sorted:

.. index::
    pair: @color; Reference

\@color

    Enables syntax coloring until the next \@nocolor directive.

.. index::
    pair: @killcolor; Reference

\@killcolor

    Disables syntax coloring in a node, overriding all \@color, \@nocolor or
    \@nocolor-node directives in the same node.

.. index::
    pair: @nocolor; Reference

\@nocolor

    Disables syntax coloring until the next \@nocolor directive.

.. index::
    pair: @nocolor-node; Reference

\@nocolor-node

    Disables coloring for only the node containing it. The \@nocolor-node
    directive overrides the \@color and \@nocolor directives within the same
    node.
</t>
<t tx="ekr.20100806170836.4399">.. index::
    pair: @nosent; Reference

The \@nosent &lt;filename&gt; creates an external file without sentinel lines.

When writing an \@nosent tree, Leo expands section references, \@all and
\@others directives, but Leo writes no sentinels to the external file.
Thus, Leo can not update \@nosent trees from changes made to the external
file. However, \@nosent trees do have their uses: unlike \@auto trees,
cloned nodes *are* valid in \@nosent trees.

When reading an \@nosent node, Leo does *not* read the external file.
Instead, all the data in the \@nosent tree is stored in the .leo file.

**Note**: \@auto or \@shadow are usually better choices than \@nosent for
creating external files without sentinels.

**Note**: The \@bool force_newlines_in_at_nosent_bodies setting controls whether
Leo writes a trailing newline if non-empty body text does not end in a newline.
The default is True.
</t>
<t tx="ekr.20100806170836.4402">.. index::
    pair: @shadow; Reference
    pair: Private file; Reference
    pair: Public file; Reference

The \@shadow directive creates *two* external files, a **public** file without
sentinels, and a **private** file containing sentinels.

When reading an \@shadow node, Leo uses a brilliant algorithm devised by
Bernhard Mulder that compares the public and private files, and then updates the
outline based on changes to the *public* file. In this way, \@shadow provides
many of the benefits of \@file trees without writing sentinels in the (public)
external file.

Leo can do an initial import of \@shadow trees by parsing the corresponding
public file, exactly as is done for \@auto nodes.
</t>
<t tx="ekr.20100806170836.4403">.. index::
    pair: @file; Reference
    pair: @thin; Reference

The \@file directive creates an external file containing sentinels. When writing
\@file trees, Leo expands section references and \@all and \@others directives.

When reading external files created by \@file, the sentinels allow Leo to
recreate all aspects of the outline. In particular, Leo can update the
outline based on changes made to the file by another editor. 

**Important**: \@file is the recommended way to create and edit most files. In
particular, using \@file nodes is **highly recommended** when sharing external
files in a collaborative environment.

The \@thin directive is a synonym for \@file.

Prior to Leo 4.7, \@file worked differently from \@thin. This should not be
a problem: Leo 4.7 can read all external files written by Leo 4.6.
</t>
<t tx="ekr.20100806170836.4408">These directives alter how Leo represents data in external files. They are
**dangerous**--mistakes in using these sentinels can make it impossible for Leo
to read the resulting external file. Use them with care!

Nevertheless, these sentinels can be useful in special situations.

.. glossary::
    :sorted:

.. index::
    pair: @comment; Reference

\@comment &lt;1, 2 or three comment delims&gt;

    Sets the comment delimiters in \@file and \@shadow files.
    **Important**: Use \@comment for unusual situations only. In most cases, you
    should use the \@language directive to set comment delimiters.

    The \@comment directive may be followed by one, two or three delimiters,
    separated by whitespace. If one delimiter is given, it sets the delimiter
    used by single-line comments. If two delimiters are given, they set the
    block comment delimiter. If three delimiters are given, the first sets the
    single-line-comment delimiter, and the others set the block-comment
    delimiters.

    Within these delimiters, underscores represent a significant space, and
    double underscores represent a newline. Examples::

        @comment REM_
        @comment __=pod__ __=cut__

    The second line sets PerlPod comment delimiters.

    **Warning**: the \@comment and \@delims directives **must not** appear in
    the same node. Doing so may create a file that Leo can not read.

    **Note**: \@language and \@comment may appear in the same node, provided
    that \@comment appears *after* the \@language directive: \@comment overrides
    \@language.

    The \@comment directive must precede the first section name or \@c
    directive.

.. index::
    pair: @delims; Reference

\@delims &lt;1 or 2 comment delims&gt;

    Sets comment delimiters in external files containing sentinel lines.

    The \@delims directive requires one or two delimiters, separated by
    whitespace. If one delimiter is present it sets the single-line-comment
    delimiter. If two delimiters are present they set block comment delimiters.

    This directive is often used to place Javascript text inside XML or HTML
    files. Like this::

        @delims /* */
        Javascript stuff
        @delims &lt;-- --&gt;
        HTML stuff

    **Warning**: you **must** change back to previous delimiters using another
    \@delims directive. Failure to change back to the previous delimiters will
    thoroughly corrupt the external file as far as compilers, HTML renderers,
    etc. are concerned. Leo does not do this automatically at the end of a node.

    **Warning**: the \@comment and \@delims directives **must not** appear in
    the same node. Doing so may create a file that Leo can not read.

    **Note**: The \@delims directive can not be used to change the comment
    strings at the start of the external file, that is, the comment strings for
    the \@+leo sentinel and the initial \@+body and \@+node sentinels.

.. index::
    pair: @raw; Reference
    pair: @end_raw; Reference

\@raw and \@end_raw

    \@raw starts a section of "raw" text that ends *only* with the \@end_raw directive
    or the end of the body text containing the \@raw directive. Within this
    range, Leo ignores all section references and directives, and Leo generates
    no additional leading whitespace.
</t>
<t tx="ekr.20100806170836.4411">These control how Leo places text when writing external files.
They are two of the most important directives in Leo.

.. glossary::
    :sorted:

.. index::
    pair: @all; Reference

\@all

    Copies *all* descendant nodes to the external file. Use \@all to place
    unrelated data in an external file.

    The \@all directive is valid only in the body of \@file trees.

    Within the range of an \@all directive, Leo ignores the \@others directive
    and section references, so Leo will not complain about orphan nodes.

.. index::
    pair: @others; Reference

\@others

    Writes the body text of all unnamed descendant into the external file, in
    outline order.

    Whitespace appearing before \@others directive adds to the indentation of
    all nodes added by the \@others directive.

    A single node may contain only one \@others directive, but descendant nodes
    may have other \@others directives.
</t>
<t tx="ekr.20100809122216.4286">Here is a complete list of options for the rst3 and code-to-rst commands:

.. glossary::
    :sorted:

call_docutils (default: True):

    Call docutils to process the intermediate file.

default_path (default: '')

    The path to be prepended to filenames given in root nodes.

default_encoding (default: utf-8)

    The default encoding to be used for non-ascii (unicode characters).

encoding (default: the default_encoding setting)

    The encoding to be used for non-ascii (unicode) characters.
    **Important**: this option has effect only in @rst-options doc parts
    in root @rst nodes.

generate_rst (default: True)

    A master switch.
    True: generate rST markup for rST sections and rST code-blocks.
    False: generate plain text and ignore @ @rst-markup doc parts.

generate_rst_header_comment (default: True)

    True: Leo writes a comment line of the form::

        .. rst3: filename: &lt;filename&gt;

    at the start of intermediate files. This option has effect only if the
    generate_rst and write_intermediate_file options are both True.

publish-argv-for-missing-stylesheets (Default: '')

    The arguments to be passed to docutils.core.Publisher().publish() when no
    stylesheet is in effect. This is a string that represents a comma-separated
    list of strings: For example, the option::

        publish-argv-for-missing-stylesheets=--language=de,--documentclass=report,--use-latex-toc

    results in the call::

        publish(['--language=de','--documentclass=report','--use-latex-toc'])

show_headlines (default: True)

    True: automatically generate rST sections from headlines.
    False: ignore headlines.

    **Note**: The level of the node in the outline determines the level of the
    section underlining in the rST markup. Higher-level headlines in the outline
    correspond to higher-level section headings; lower-level headlines in the
    outline correspond to lower-level section headings.

show_organizer_nodes (default: True)

    True: generate rST sections for nodes that do not contain body text.

    **Note**: This option has no effect unless the rST section would otherwise be written.

show_sections (default: True)

    True: generate rST sections corresponding to headlines.
    False: don't generate sections.  Instead, generate lines of the form::

        **headline**

strip_at_file_prefixes (default: True)

    True: remove @auto, @file, @nosent and @thin from the start of headlines.

stylesheet_name (default: 'default.css')

    The name of the stylesheet passed to docutils.

stylesheet_path (default: '')

    The directory containing the stylesheet passed to docutils.

    **Note**: If the stylesheet_embed option is True, specify a path relative to
    the location of the Leo file. If the stylesheet_embed option is False,
    specify a path relative to the location of the HTML file.

stylesheet_embed (default: True)

    True: The content of the stylesheet file will be embedded in the HTML file.
    False: The HTML file will link to an external stylesheet file.

underline_characters (default: #=+*^~"'\`-:&gt;\_)

    The underlining characters to be used to specify rST sections.
    The first character is reserved so you can specify the top-level section explicitly.

verbose (default: True)

    True: write informational messages.

write_intermediate_file (default: False)

    **Important**: the rst3 command *always* creates an intermediate file.
    This option controls whether that file is an internal Python object
    or an actual file on the external file system.

    True: writes the intermediate file to the external file system. The name of
    the intermediate file has the name of the output file with .txt appended.
    This option has effect only if the generate_rst option is True.

    False: writes the intermediate file to an internal Python object.
</t>
<t tx="ekr.20100809162244.4289">This tutorial tells how to get started with Leo's rst3 command. The tutorial
covers only rst3's basic features. You can do a *lot* with these features--Leo's
documentation uses only the features described here!

Step-by-step, here is how to use the rst3 command:

1. Create an \@rst node. This node and its descendants will contain your
   document. The \@rst node itself is a good place to specify general
   information about your documentation, including its title, one or more
   external files created by the rst3 command, and global settings for the rst3
   command.

2. Write your documentation in the descendants of the \@rst node. Within the
   \@rst tree, **headlines represent section headings**. Body text contain your
   writing, including rST or Sphinx markup.

3. To create your documents, run the rst3 command on an outline containing one
   or more \@rst nodes. 

That's all there is to it! The organization of the \@rst tree *is* the organization
of your document. To reorganize your document, you just reorganize the nodes in
the \@rst tree!  When you are done writing, create your output using the rst3 command.

The next sections will discuss these three steps in more detail. As you will
see, after you set up the \@rst node, you can focus exclusively on writing and
organizing. Leo's rst3 command will take care of the rest.
</t>
<t tx="ekr.20100809162244.4292">The headline of the \@rst node has the form::

        @rst &lt;filename&gt;

Depending on options to be discussed later, the rst3 command will write one or two files:
the **output file** (&lt;filename&gt;), and the **intermediate file** (&lt;filename&gt;.txt).

For example, the rst3 command applied to \@rst abc.html will write
abc.html or abc.html.txt or both.

**Important**: The intermediate file *always* contains rST/Sphinx markup
*regardless* of the type of the final output files. When in doubt about the rst3
command, you can examine the intermediate file to see what rst3 has done.

Let's turn our attention to the the body of the \@rst node...
</t>
<t tx="ekr.20100809162244.4295">Now comes the "interesting" part--actually writing your novel, short story,
documentation or whatever.

As always with Leo, you organize your work with outlines. By default, (that is,
with the recommended options discussed in Step 1) the rst3 command will produce
the following output:

1. Each node becomes an rST/Sphinx section.

   The level of each section corresponds to the level of the node in the
   headline. Children of the @rst node create level 1 sections. Grandchildren of
   the \@rst node create level 2 sections, and so on.

2. The headline of each node becomes the section heading.

3. The body text of each node becomes the contents of the node's section.

   **Note**: The body text of any node in an \@rst tree contains plain text,
   with optional rST or Sphinx markup. Sphinx markup is a superset of rST
   markup. For more details on markup, see the `Sphinx`_ or `reStructuredText`_
   documentation.

That's all there is to it!

Well almost. There is one other feature you should know about. Headlines that
start with '\@rst-' control the rst3 command.  The three most useful are: 

.. glossary::

\@rst-no-head &lt;ignored-text&gt;

    Causes the rst3 command to copy just the body text of the node. In other
    words, the node's body text become part of the previous section. Leo's docs
    use such nodes for rST links and other "invisible" markup.

\@rst-ignore &lt;ignored-text&gt;

    The rst3 command ignores any \@rst-ignore node. Neither the headline nor the
    body text becomes part of the output. You can use such nodes for notes that
    you do not want to become part of the actual document.

\@rst-ignore-tree &lt;ignored-text&gt;

    The rst3 command ignores the \@rst-ignore-tree node and all its descendants.
</t>
<t tx="ekr.20100809162244.4296">This step is easy. Select an outline containing one or more \@rst trees. Now do
&lt;Alt-X&gt;rst3&lt;Return&gt;. You can use &lt;Ctrl-P&gt; (repeat-complex-command) instead if
the last minibuffer command was the rst3 command.

The rst3 command writes its output to either the output file or the intermediate
file, or both:

- With the recommended settings for docutils, the rst3 command will run docutils
  automatically, producing the output file as the result.

- With the recommended settings for Sphinx, the rst3 command will generate the
  intermediate file. You must then run Sphinx's make utility to turn the
  intermediate file into the final output file.
</t>
<t tx="ekr.20100809162244.4297">Next, set your document's title by putting something like this in the
body text of the \@rst node::

    #############
    War and Peace
    #############

**Important**: The rst3 command reserves the '#' character for the document
titles--don't use any other underlining character.

Sometimes I put the first words of a document in the \@rst node::

    Well, Prince, so Genoa and Lucca are now just family estates of the
    Buonapartes. But I warn you, if you don't tell me that this means war, if
    you still try to defend the infamies and horrors perpetrated by that
    Antichrist--I really believe he is Antichrist--I will have nothing more to
    do with you and you are no longer my friend, no longer my 'faithful slave,'
    as you call yourself! But how do you do? I see I have frightened you--sit
    down and tell me all the news.
</t>
<t tx="ekr.20100809162244.4298">The \@rst node is a good place for options that apply to the entire \@rst
tree. Typically, you will just set these options once and then completely forget
about them.

You set rst3 options in body parts like this::

    @ @rst-options
    rst3 options, one per line
    @c

This is a Leo doc part: the '@' must appear in the leftmost column. As usual,
the doc part ends with the \@c directive, or the end of the body text.

Here are the recommended options when using docutils::

    @ @rst-options
    call_docutils=True
    code_mode=False
    stylesheet_path=..\doc
    write_intermediate_file=True
    @c

And here are the recommended options when using Sphinx::

    @ @rst-options
    call_docutils=False
    code_mode=False
    stylesheet_path=..\doc
    write_intermediate_file=True
    @c

**Note 1**: It is good style to specify all these options explicitly, even if they are
the same as the standard default values. This ensures that the rst3 command
will produce the same results no matter where the \@rst node is located.

**Note 2**: You may have to change the stylesheet_path option so that the
generated output file can find the proper stylesheets.
</t>
<t tx="ekr.20100809162244.4301">You now know everything needed to get started with the rst3 command.
Some possible next steps are:

1. Look at Leo's own documentation in LeoDocs.leo. It's in the node "@rst
   html\rstplugin3.html". Discover how the nodes in this tree correspond to the
   documentation you see before you.

2. Create your own @rst nodes. Run the rst3 command on them and see what
   happens. If you get stuck, you please ask for help at
   `Leo's Google Group`_.
</t>
<t tx="ekr.20100810091118.4298">**Markup doc parts** have the following form::

    @ @rst-markup
    any rST markup
    @c

Markup doc parts inserts the markup directly into the output. Markup doc parts
are most useful when formatting an outline as code using the code-to-rst
command.
</t>
<t tx="ekr.20100810091118.4301">The following options have effect only in code mode.

.. glossary::
    :sorted:

number_code_lines (default: True)

    Controls whether to number code lines in code mode.
    This option has no effect in rst mode.

show_leo_directives (default: True)

    True: include Leo directives
    False: ignore Leo directives.

show_markup_doc_parts (default: False)

    True: include markup doc parts.
    False: ignore markup doc parts.

show_options_doc_parts (default: False)

    True: include options doc parts.
    False: ignore options doc parts.

show_doc_parts_as_paragraphs (default: False)

    True: Move doc parts outside of the code-block directive. False: Show doc
    parts in the code-block directive. **Cool**: Any rST markup in doc parts
    included as the result of this option will be rendered properly.

show_options_nodes (default: False)

    True: show @rst-options nodes.
    False: Ignore @
</t>
<t tx="ekr.20100810091118.4306">The following option has effect only in rst mode.

.. glossary::

show_doc_parts_in_rst_mode [True,False or class names] (default: True)

    This option is most useful for rst documents which are not computer code.
    It allows you to use doc parts to make comments on the draft document
    which are either excluded from the output or formatted in a way that highlights
    their nature as comments rather than content.  For example, you're writing a book, and
    you want to use a doc part at the top of a section to remind yourself "need
    to explain how Ted got to Sally's".    Note: you may need to add
    CSS to have them formatted differently.

    The option can be `True`, `False`, or one or more class names.

    **True**: Treat the entire doc part from the opening '@' to the closing '@c
    as normal markup.

    **False**: Remove the doc part.

    **class names**: Process the contents of the doc part as it if were in an rst
    `container` directive. For example::

         @ @rst-options
         show_doc_parts_in_rst_mode = notes literal
         @c

    would wrap the doc part contents in the output in a div with classes
    "container notes literal". Furthermore, if one of the class names is
    `literal`, then the doc part content will be output as a literal block
    wrapped in a container as described above. This allows you to use text which
    is not valid rst as rough notes for annotating a draft document.
</t>
<t tx="ekr.20100810203016.4296"></t>
<t tx="ekr.20100810203016.4298">By default, the rst3 command operates in **rst mode**. In rst mode, the rst3
command treats body text as rST (or Sphinx) markup. This is the mode of
operation discussed in the Tutorial.

In **code mode** the rst3 command treats body text as computer source code.
**Note**: both rST and Sphinx have markup designed to represent computer
programs. The rst3 command generates that markup automatically in code mode.

Code mode is inherently complex. As we shall see, there are *many* possible
options in code mode. This can hardly be helped--this is truly an advanced
topic!

In **doc_only_mode**, rst3 command outputs only regular doc parts and @
@rst-markup doc parts. Headlines create section in doc_only mode only if:

1. The node contains a doc part or

2. The show_organizer_nodes option is in effect.

The code_mode and doc_only_mode options determine the mode as follows:

- By default (code_mode=False; doc_only_mode=False), the rst3 command is in
  rst mode.

- Setting code_mode=True causes the rst3 command to enter code mode.

- Setting code_mode=False cause the rst3 command to enter rst mode.

- Setting doc_only_mode=True causes the rst3 command to enter doc_only mode.

</t>
<t tx="ekr.20100813075851.4296">This section discusses options--what they are, how to set them and how to set their defaults.
</t>
<t tx="ekr.20100813075851.4297"></t>
<t tx="ekr.20100817101952.4303">.. links

.. _`latest stable release`: http://sourceforge.net/projects/leo/files/Leo/4.10%20final/
.. _`SourceForge`: https://sourceforge.net
.. _`Leo's snapshots page`:     http://www.greygreen.org/leo/
.. _`nightly snapshot`:             http://www.greygreen.org/leo/
.. _`Leo's latest sources`: https://code.launchpad.net/leo-editor/
.. _`Launchpad`: https://code.launchpad.net/


Leo's core code is always being improved and developed. Unit-testing
ensures that the daily commits are as bug-free as possible. Almost all of
the time, downloading the most recent `nightly snapshot`_ of the
development code is going to give you code that is just as stable and much
more up-to-date than the most recent `latest stable release`_ which most
Leonistas would consider already outdated.

If you are just checking Leo out, feel free to use the `latest stable release`_
download if it makes you feel more secure, but once you've
decided to work with Leo on a regular basis, we highly recommend regularly
keeping your installation up to date with the most recent `nightly snapshot`_.

To summarize, you may get Leo in three ways:

1. Download the `latest stable release`_ from `SourceForge`_. This release
   contains an executable installer. This release will usually be a bit out
   of date.

2. Download a `nightly snapshot`_ from `Leo's snapshots page`_. This page
   contains .zip archives of Leo's code from 1, 2, 5, 10, 30 and 90 days
   ago.
   
3. Download `Leo's latest sources`_ from `Launchpad`_ using `bzr`_.
   Installing bzr is non-trivial, but once set up this is the easiest way
   to get the latest version of Leo's code.
</t>
<t tx="ekr.20100817101952.4306">

**Important**: This section tells how to set up bzr_ so that you can grab
the latest bzr sources using ``bzr pull``. However, you can get a nightly
snapshot of Leo's bzr repository (without installing bzr) from
http://www.greygreen.org/leo/

Many users will want to track the development version of Leo, in order to stay
on top of the latest features and bug fixes. Running the development version is
quite safe and easy, and it's also a requirement if you want to contribute to
Leo.

1. First, you need to get bzr_ (Bazaar) from http://bazaar-vcs.org. For windows
   users we recommend the standalone installer; the python installer may have
   problems pushing to Launchpad. Plain bzr installer only contains the command
   line version, so you might want to augment that with a friendly GUI - qbzr is
   recommended as it's the easiest one to install. It provides command like
   bzr qlog, bzr qannotate etc.

2. Get Leo from launchpad by doing::

     bzr branch lp:leo-editor

And that's it! You can run leo/core/leo.py directly. When you want to refresh the
code with latest modifications from Launchpad, run bzr pull.

If you make modifications to Leo (with the interest in sharing them with the Leo
community), you can check them in to your local branch by doing bzr checkin.
Now, to actually request your changes to be merged to Leo trunk, you need a
Launchpad account with RSA keys in place. There is showmedo video about how to
accomplish this in Windows using puttygen and pageant at
http://showmedo.com/videos/video?name=1510070&amp;fromSeriesID=151.

After your Launchpad account is set up, go to
https://launchpad.net/leo-editor, choose "Code" tab -&gt; Register Branch,
select Branch type "Hosted" and fill in descriptive details about the branch.
After that, go to the branch home page from Code tab again, and copy-paste the
push command line to terminal. For example, for branch::

    https://code.launchpad.net/~leo-editor-team/leo-editor/mod_rclick

The push command is::

    bzr push bzr+ssh://my_name@bazaar.launchpad.net/~leo-editor-team/leo-editor/mod_rclick    

You may wish to add --remember command line option to bzr push, to direct all
future pushes to that location. Then, you only need to execute bzr push.

After your branch is pushed, you can email the Leo mailing list and request it
to be reviewed and merged to trunk.
</t>
<t tx="ekr.20100821182153.4343">@ @rst-options
call_docutils=False
stylesheet_path=..\doc
write_intermediate_file = True
@c

######
Slides
######

This is the front page for various slide shows about Leo.

.. links
.. _`Clones and views`:         slides/clones-and-views/slide-001.html
.. _`External files`:           slides/external-files/slide-005.html
.. _`Installation`:             slides/installation/slide-001.html
.. _`Leo Basics Step By Step`:  slides/leo-basics-step-by-step/slide-001.html
.. _`Scripting Leo`:            slides/scripting-leo/slide-001.html
.. _`Using Leo's Minibuffer`:   slides/using-leos-minibuffer/slide-001.html

Basic slide shows
-----------------

`Installation`_  tells how to install Leo.

`Leo Basics Step By Step`_  explains the basics of Leo outlines.

`External Files`_ discusses creating external files with \@file, \@auto and \@edit.

`Clones and views`_ illustrates how clones work and show how they create views.

`Using Leo's Minibuffer`_ tells how to execute Leo's commands by name.

Intermediate slide shows
------------------------

`Scripting Leo`_ explains how to use Python scripting in Leo.
</t>
<t tx="ekr.20100907092300.4440"></t>
<t tx="ekr.20100907092300.4441">Path to inkscape template file
</t>
<t tx="ekr.20100907092300.4442">Path to Inkscape executable
</t>
<t tx="ekr.20101007100904.4372"></t>
<t tx="ekr.20101009114830.4723">@nocolor-node

Formerly, this had to be on because the expansion bits
of @screenshot trees were significant.

Happily, this is no longer true.

True (recommended):
    Write "E" attribute bits in &lt;v&gt; elements.
    Leo outlines will record the expansion state of all nodes.

False:
    (Good for files like unitTest.leo)
    Suppress "E" attribute bits in &lt;v&gt; elements.
    Only the ancestors of the presently selected node will
    be expanded when Leo opens an outline.
</t>
<t tx="ekr.20101009114830.4724"></t>
<t tx="ekr.20101009114830.4725"></t>
<t tx="ekr.20101025080245.5791">##################
What's New in Leo
##################

.. contents::
    :depth: 3
</t>
<t tx="ekr.20101025080245.5794"></t>
<t tx="ekr.20101025080245.5798"></t>
<t tx="ekr.20101025080245.5799" str_atime="1376411965.0"></t>
<t tx="ekr.20101025080245.5805"></t>
<t tx="ekr.20101025080245.5980">.. _`p.deletePositionsInList`: http://groups.google.com/group/leo-editor/browse_thread/thread/0aa8d9d17f6300b8#
.. _`g.findTestScript`: http://groups.google.com/group/leo-editor/browse_thread/thread/a108d70400b28dc9#

- The execute-script now calls execfile (or its equivalent when using Python 3k)
  when @bool write_script_file = True. This allows pdb (or pudb) to show the
  text of Leo scripts!

- Added `p.deletePositionsInList`_, an important new helper.

- Added `g.findTestScript`_, an important new pattern for sharing code in Leo
  scripts, including scripts in @test nodes.

    Suppose there is common code that I want to include in several unit tests::

        class Hello():
            def __init__(self,name='john'):
                self.name=name
                print('hello %s' % name)

    I put this in a node called 'Common test code'. Now the unit tests can "import"
    the code as follows::

        exec(g.findTestScript('Common test code'))

    After this exec statement completes the class Hello is available to the test
    code! This is something that I've wanted to do forever.
</t>
<t tx="ekr.20101025080245.5985">.. _`Reorganized`: http://groups.google.com/group/leo-editor/browse_thread/thread/d02df89c0b831a7c

- Several important improvements to Leo's installer for Windows.

- Leo doesn't create @chapter nodes for new files.

- Leo now uses PyEnchant to check spelling.

    This is much safer than the old Aspell wrapper.

- All \@auto nodes end with a newline.

- Leo now writes @edit nodes like @nosent nodes.

- Added legend for print-settings command.

- Improved the importer for elisp.

- Added an .ini importer.

- Created introductory slide shows.

- `Reorganized`_ the users guide.

- Improved the installation instructions.

- Added support for .nsi files.
</t>
<t tx="ekr.20101025080245.6006">- Leo can now open multiple files from the command line.

- You can now set a proportional font to use in all "@language plain" nodes.
   Specify fonts in @font nodes::

        @font plain null font

            plain_null_font_family = Times New Roman
            plain_null_font_size = 16
            plain_null_font_slant = roman
            plain_null_font_weight = bold

  That is, the actual font specs are in the body text.  Everything
  except \@font is ignored in the headline.

  Specify font colors with \@color nodes::

        @color plain null color = black

- Added support for minibuffer colors. Added the following options with the
  indicated defaults::

    @color minibuffer_background_color = lightblue
    @color minibuffer_warning_color = lightgrey

- Added support for \@string qt-toolbar-location = &lt;spot&gt;

    Valid values for &lt;spot&gt; are top,bottom,left,right

- Added support for \@bool write_expansion_bits_in_leo_files.

- The ``-screen-shot`` command-line argument tells Leo to take a screenshot and exit.

- The ``--window-size`` command-line argument specifies the initial size of the Leo
  window.  This is especially useful with the ``screen-shot`` command-line argument::

    --window-size=600x900  # &lt;height&gt; x &lt;width&gt;, in pixels.

- Added support for @bool at_auto_separate_non_def_nodes option.

    When true, the @auto file importers put inter-def code in their own node.
    The default (legacy mode) is False.
</t>
<t tx="ekr.20101025080245.6077">.. _`simplest possible`: http://groups.google.com/group/leo-editor/browse_thread/thread/8b659c96720afd53/628a09779ca9e8c6
.. _`org-mode`: http://orgmode.org/

Leo now writes \@file files with the `simplest possible`_ sentinel lines.

    - Eliminated \@-node sentinels.
    - Eliminated \@nl and \@nonl sentinels.
    - Simpler representation of \@doc and \@ in sentinels.
    - Simplified representation of \@others and section references.
    - Use a scheme much like Emacs `org-mode`_ to represent headline level.

The result is, provably, the simplest possible representation of Leo's outline
structure in external files.
</t>
<t tx="ekr.20101025080245.6078">The Qt Gui now supports drag and drop in Leo outlines.

You can drag files into Leo.  Leo will create \@file or \@auto nodes if appropriate.
</t>
<t tx="ekr.20101025080245.6079">When abbreviation mode is on (abbrev-mode toggles this mode) Leo will expand
abbreviations as you type. Type the name of an abbreviation, followed by a
space. As soon as you type the space, Leo will replace the name by the
abbreviations value. You can undo the replacement as usual.

Note that defining any abbreviation automatically turns on abbreviation
mode.

The add-global-abbreviation command (&lt;alt-x&gt;add-gl&lt;tab&gt;&lt;return&gt;) takes the
selected text as the replacement value of the abbreviation. The minibuffer
prompts you for the name of the abbreviation.

Three new settings apply to the abbreviation commands:

- @bool enable-abbreviations (default: False)

    When true, enables substitution of abbreviations.

- @data global-abbreviations

- @data abbreviations

      In both cases, body text contains lines of the form::

        name=value

      name is the abbreviation name, value is the substituted text. Whitespace
      is ignore around the name, but is significant in the value. Abbreviation
      names may contain only alphabetic characters, but may start with the '@'
      sign.

      By *convention* @data global-abbreviations setting should be defined in
      myLeoSettings.leo, while @data abbreviations should be defined in other
      .leo files. Regardless of where they are defined, abbreviations in @data
      abbreviation nodes will override settings (with the same name) in @data
      global-abbreviations nodes.
</t>
<t tx="ekr.20101025080245.6080">If the body text is non-empty, it is assumed to contain the URL.
This is a remarkably important improvement--it allows the
headline to contain a description of the url.
</t>
<t tx="ekr.20101025080245.6081">- The screenshots.py plugin helps make slide shows containing many screen shots.
</t>
<t tx="ekr.20101025080245.6084"></t>
<t tx="ekr.20101025080245.6085">Added support for @shadow files. This was a major breakthrough.
See the `Using @shadow`_ chapter for full details.
</t>
<t tx="ekr.20101025080245.6086">This version of Leo featured more significant improvements:

- Added support for the Qt gui.  This was a major project that
  significantly improves the look and feel of Leo.

- A file-caching scheme produced spectacular improvements in the
  speed of loading Leo outlines.

- Added support for @auto-rst nodes. These import reStructuredText (rST) files
  so that the files can be "round-tripped" without introducing extraneous
  changes. This makes Leo a superb environment for using rST.

- Added support for @edit nodes.
</t>
<t tx="ekr.20101025080245.6087">Leo 4.7 accomplishes something I long thought to be impossible: the unification
of vnodes and tnodes. tnodes no longer exist: vnodes contain all data. The Aha
that made this possible is that iterators and positions allow a single node to
appear in more than one place in a tree traversal.

This is one of the most significant developments in Leo's history. At last the
endless confusion between vnodes and tnodes is gone. At the most fundamental
level, Leo's data structures are as simple as possible. This makes them as
general and as powerful as possible!

This version successfully produced a common code base that can run on both
Python 2.x and Python 3.x.
</t>
<t tx="ekr.20101025080245.6088">Leo 4.7 accomplishes something I long thought to be impossible: the unification
of vnodes and tnodes. tnodes now longer exist: vnodes contain all data. The Aha
that made this possible is that iterators and positions allow a single node to
appear in more than one place in a tree traversal.
</t>
<t tx="ekr.20101025080245.6089">Leo 4.8 simplified Leo's sentinels as much as possible.
Leo's sentinel lines look very much like Emacs org-mode comment lines,
except for the addition of gnx's.

This version also produced a fundamentally important addition to Leo's error
recovery. Leo now shows "Resurrected" and "Recovered" nodes when loading an
outline. These nodes protect against data loss, and also implicitly warn when
unusual data-changing events occur. Creating this scheme is likely the final
chapter in the epic saga of error recovery in Leo.
</t>
<t tx="ekr.20101026082911.5536"></t>
<t tx="ekr.20101026082911.5538">.. .. _`here`: atShadow.html#aha-boundary-cases-don-t-matter

The \@shadow algorithm guarantees *only* that writing an updated \@shadow
outline will generate the updated **public** file. There is *no way* to
guarantee that the updated outline structure will be as expected. The
\@shadow algorithm can not guess between two or more ways of updating the
**private** file when each of the ways yields the same **public** file.

Happily, this "fact of life" about \@shadow is not serious. If you don't like
the "guesses" that the \@shadow algorithm has made, you can simply change the
\@shadow tree. After saving the outline, the *private* file will record your
choice. The next time you open the outline, you will see the choices *you* made,
not the guesses that the \@shadow algorithm made.
</t>
<t tx="ekr.20101104024804.4898">@language rest

- Select the node "Leo's Documentation"

- Run the make-sphinx command or click the make-sphinx button.


To generate these docs by hand:

    - From this file, run rst3 on desired tree.
    - cd leo\doc\html
    - make html

To create pdf (probably easiest on Linux, with necessary latex packages installed):

    - make latex
    - cd _build/latex
    - make all-pdf
    
Important files:

- doc\html\conf.py contains settings, including the name of the master toctree
  document: leo_toc.html.txt.

</t>
<t tx="ekr.20101104173324.5141">- Added code-to-rst command.

- Completed cascade-windows and minimize-all-windows commands.

- Created head-to-prev-node and tail-to-next-node commands.

- Removed mark-clones command.  It is useless in the one-node world.

- Added extract-python-method command.
</t>
<t tx="ekr.20101111175617.14683">def getDocString(self,p):

    '''Return the docstring of the @&lt;file&gt; node p.'''

    trace = False # p.h.find('@file rClick.py') &gt; -1
    if trace: g.trace('='*20)
    for p2 in p.self_and_subtree():
        s = p2.b
        if trace: g.trace(p2.h)
        for tag in ("'''",'"""'):
            i = s.find(tag)
            if i &gt; -1:
                j = s.find(tag,i+3)
                if j &gt; -1:
                    if trace: g.trace('**found**',p2.h,'\n',s)
                    return s[i+3:j]
    else:
        return ''
</t>
<t tx="ekr.20101111175617.24328">def openLeoPlugins(self):

    fn = g.os_path_finalize_join(
        g.app.loadDir,'..','plugins','leoPlugins.leo')

    ok,frame = g.openWithFileName(fn,
        old_c=self.c,enableLog=True,
        gui=None,readAtFileNodesFlag=True)

    if ok:
        return frame.c
    else:
        g.error('can not open leoPlugins.leo')
        return None
</t>
<t tx="ekr.20101111175617.5037" str_atime="1376412919.0">@language python

'''Creates an outline containing most docstrings from leoPlugins.leo.

Documentation for some docstings are suppressed.'''

@others

controller(c).run()
</t>
<t tx="ekr.20101111175617.56915" str_atime="1376412768.0">class controller:

    def __init__ (self,c):
        self.c = c
        self.trace = False

    @others
</t>
<t tx="ekr.20101111175617.5787">def run(self):

    c = self.c
    new_c = self.openLeoPlugins()
    if not new_c: return

    # Create the top-level output node.
    output = c.p.insertAfter()
    output.h = 'get-docstrings-output'
    output.b = '@language rest\n'

    # Scan the descendants of the Plugins node.
    root = g.findNodeAnywhere(new_c,'Plugins')
    if root:
        if self.trace: print('='*20)
        self.createSummary(output,root)
        self.createDocs(output,root)
        c.frame.bringToFront() # new_c.close()
        c.redraw()
    else:
        g.error('no Plugins node')



@language python

@language python

@language python
</t>
<t tx="ekr.20101112045055.13354">def createSummary (self,output,root):

    summary = output.insertAsLastChild()
    summary.h = 'Summary'
    result = []

    for p in root.children():
        if self.allowDir(p):
            for p2 in p.subtree():
                if self.allowFile(p2):
                    h = p2.anyAtFileNodeName()
                    s = self.getDocString(p2)
                    s = self.getFirstParagraph(s).rstrip()
                    if s:
                        if not s.endswith('.'): s = s + '.'
                        result.append('%s\n%s\n\n' % (h,s))

    # Sort by plugin name, ignoring case.
    def lower(s): return s.lower()
    result.sort(key=lower)
    summary.b = ''.join(result)
</t>
<t tx="ekr.20101112045055.13355">def createDocs (self,output,root):

     for p in root.children():
        if self.allowDir(p):
            if self.trace: print('\n**',p.h)
            child = output.insertAsLastChild()
            child.h = p.h
            for p2 in p.subtree():
                if self.allowFile(p2):
                    h = p2.anyAtFileNodeName()
                    s = self.getDocString(p2)
                    if self.trace: print('%5s %s' % (len(s),h))
                    child2 = child.insertAsLastChild()
                    child2.h = h
                    child2.b = "%s\n\n" % s.strip()
</t>
<t tx="ekr.20101112045055.13356">def allowDir (self,p):

    '''Return True if we should allow scan of directory p.'''

    aList = (
        # Suppressed directories.
        'Examples','Experimental',
        'Dyna plugins by e',
        'Gui plugins','Testing',
    )
    return p.h not in aList and not p.h.startswith('  ')
</t>
<t tx="ekr.20101112045055.13357">def getFirstParagraph (self,s):

    lines =  g.splitLines(s.strip())
    if not lines: return ''

    result = []
    for s in lines:
        if s.strip():
            result.append('   '+s)
        else:
            break

    return ''.join(result)
</t>
<t tx="ekr.20101112045055.5065" str_atime="1376412774.0">http://www.greygreen.org/tmp/plugins.html</t>
<t tx="ekr.20101112222250.5322">def allowFile (self,p):

    '''Return True if we should allow scan of a file at p.'''

    aList = (
        # Suppresssed files.
        '@file bookmarks.py',       # Replaced by better @url.
        '@file rst3.py',            # Replaced by core rst3 command.
        '@file stickynotes_plus.py', # Experimental version of stickynotes
        '@file testnode.py',        # Replaced by @edit.
        # These all depend on old plugins_manager.py.
        '@file autotrees.py', 
        '@file old_plugin_manager.py',
        '@file leoupdate.py',
        # These are used only by autotrees.py.
        r'@file trees\doc.py',
        r'@file trees\news.py',
        r'@file trees\remote.py',
        r'@file trees\rss.py',
        r'@file trees\test.py',
    )
    return p.h not in aList and p.isAnyAtFileNode() and p.h.endswith('.py')
</t>
<t tx="ekr.20101113063552.9398" str_atime="1376413523.0">.. |br| raw:: html

   &lt;br /&gt;

active_path.py |br|
   Synchronizes @path nodes with folders.

add_directives.py |br|
   Allows users to define new @directives.

at_folder.py |br|
   Synchronizes @folder nodes with folders.

at_produce.py |br|
   Executes commands in nodes whose body text starts with @produce.

at_view.py |br|
   Adds support for \@clip, \@view and \@strip nodes.

attrib_edit.py |br|
   Edits user attributes in a Qt frame.

backlink.py |br|
   Allows arbitrary links between nodes.

bibtex.py |br|
   Manages BibTeX files with Leo.

bzr_qcommands.py |br|
   Adds a context menu to each node containing all the commands in the bzr Qt
   interface. Bzr is invoked based on the path of the current node.

chapter_hoist.py |br|
   Creates hoist buttons.

colorize_headlines.py |br|
   Manipulates appearance of individual tree widget items.

contextmenu.py |br|
   Defines various useful actions for context menus (Qt only).

datenodes.py |br|
   Allows users to insert headlines containing dates.

debugger_pudb.py |br|
   Makes g.pdb() enter the Pudb debugger instead of pdb.

detect_urls.py |br|
   Colorizes URLs everywhere in a node's body on node selection or saving. Double
   click on any URL launches it in the default browser.

dtest.py |br|
   Sends code to the doctest module and reports the result.

dump_globals.py |br|
   Dumps Python globals at startup.

EditAttributes.py |br|
   Lets the user associate text with a specific node.

empty_leo_file.py |br|
   Allows Leo to open any empty file as a minimal .leo file.

enable_gc.py |br|
   Enables debugging and tracing for Python's garbage collector.

expfolder.py |br|
   Adds @expfolder nodes that represent folders in the file system.

FileActions.py |br|
   Defines actions taken when double-clicking on @&lt;file&gt; nodes and supports
   @file-ref nodes.

geotag.py |br|
   Tags nodes with latitude and longitude.

graphcanvas.py |br|
   Adds a graph layout for nodes in a tab.
   Requires Qt and the backlink.py plugin.

import_cisco_config.py |br|
   Allows the user to import Cisco configuration files.

initinclass.py |br|
   Modifies the Python @auto importer so that the importer
   puts the __init__ method (ctor) into the body of the class node.

interact.py |br|
   Adds buttons so Leo can interact with command line environments.

ipython.py |br|
   Creates a two-way communication (bridge) between Leo
   scripts and IPython running in the console from which Leo was launched.

leo_interface.py |br|
   Allows the user to browse XML documents in Leo.

leo_pdf.py |br|
   This NOT a Leo plugin: this is a docutils writer for .pdf files.

leo_to_html.py |br|
   Converts a leo outline to an html web page.**.

leo_to_rtf.py |br|
   Outputs a Leo outline as a numbered list to an RTF file. The RTF file can be
   loaded into Microsoft Word and formatted as a proper outline.

leocursor.py |br|
   Creates a LeoCursor object that can walk around a Leo outline and decode
   attributes from nodes.
   
leomylyn.py |br|
    Provides a "Mylyn" like experience for Leo.

leoremote.py |br|
   Remote control for Leo.

leoscreen.py |br|
   Allows interaction with shell apps via screen.

lineNumbers.py |br|
   Adds #line directives in perl and perlpod programs.

macros.py |br|
   Creates new nodes containing parameterized section references.

maximizeNewWindows.py |br|
   Maximizes all new windows.

mime.py |br|
   Opens files with their default platform program.

mod_autosave.py |br|
   Autosaves the Leo outline every so often.

mod_framesize.py |br|
   Sets a hard coded frame size.

mod_http.py |br|
   A minimal http plugin for LEO, based on AsyncHttpServer.py.

mod_read_dir_outline.py |br|
   Allows Leo to read a complete directory tree into a Leo outline. Converts
   directories into headlines and puts the list of file names into bodies.

mod_scripting.py |br|
   Creates script buttons and @button, @command, @plugin and @script
   nodes.

mod_tempfname.py |br|
   Replaces c.openWithTempFilePath to create alternate temporary
   directory paths.

mod_timestamp.py |br|
   Timestamps all save operations to show when they occur.

multifile.py |br|
   Allows Leo to write a file to multiple locations.

nav_qt.py |br|
   Adds "Back" and "Forward" buttons (Qt only).

niceNosent.py |br|
   Ensures that all descendants of @file-nosent nodes end
   with exactly one newline, replaces all tabs with spaces, and
   adds a newline before class and functions in the derived file.

nodeActions.py |br|
   Allows the definition of double-click actions.

open_shell.py |br|
   Creates an 'Extensions' menu containing two commands:
   Open Console Window and Open Explorer.

outline_export.py |br|
   Modifies the way exported outlines are written.

paste_as_headlines.py |br|
   Creates new headlines from clipboard text.

plugins_menu.py |br|
   Creates a Plugins menu and adds all actives plugins to it.

pretty_print.py |br|
   Customizes pretty printing.
   
printing.py |br|
    Supports printing for the Qt gui.

projectwizard.py |br|
   Creates a wizard that creates @auto nodes.

quickMove.py |br|
   Creates buttons to move nodes quickly to other nodes.

quicksearch.py |br|
   Adds a fast-to-use search widget, like the "Find in files" feature of many editors.

quit_leo.py |br|
   Shows how to force Leo to quit.

read_only_nodes.py |br|
   Creates and updates @read-only nodes.

redirect_to_log.py |br|
   Sends all output to the log pane.

run_nodes.py |br|
   Runs a program and interface Leos through its input/output/error streams.
   
screen_capture.py |br|
    Supports taking screen shots. See http://leo-editor.github.io/screen_capture.html

screenshots.py |br|
   Creates stand-alone slideshows containing screenshots.

script_io_to_body.py |br|
   Sends output from the Execute Script command to the end of the body pane.

scripts_menu.py |br|
   Creates a Scripts menu for LeoPy.leo.

scrolledmessage.py |br|
   Provides a Scrolled Message Dialog service for Qt.

setHomeDirectory.py |br|
   Sets g.app.homeDir to a hard-coded path.

slideshow.py |br|
   Support slideshows in Leo outlines.

spydershell.py |br|
   Launches the spyder environment with access to Leo instance.
   See http://packages.python.org/spyder/.

startfile.py |br|
   Launches (starts) a file given by a headline when double-clicking the icon.

stickynotes.py |br|
   Adds simple "sticky notes" feature (popout editors) for Qt gui.
   
timestamp.y
    Manages attributes containing node creation/modification/viewed times.

todo.py |br|
   Provides to-do list and simple task management for leo (Qt only).

tomboy_import.py |br|
   Allows imports of notes created in Tomboy / gnote.

trace_gc_plugin.py |br|
   Traces changes to Leo's objects at idle time.

trace_keys.py |br|
   Traces keystrokes in the outline and body panes.

trace_tags.py |br|
   Traces most common hooks, but not key, drag or idle hooks.

valuespace.py |br|
    Supports outline-based calculations similar to spreadsheets.

viewrendered.py |br|
   Creates a window for *live* rendering of rst, html, etc.
   This plugin uses docutils, http://docutils.sourceforge.net/,
   to do the rendering, so installing docutils is recommended.

vim.py |br|
   Enables two-way communication with VIM.

word_count.py |br|
   Counts characters, words, lines, and paragraphs in the body pane.

word_export.py |br|
   Adds the Plugins\:Word Export\:Export menu item to format and export
   the selected outline to a Word document, starting Word if necessary.

xemacs.py |br|
   Allows you to edit nodes in emacs/xemacs.

xsltWithNodes.py |br|
   Adds the Outline:XSLT menu containing XSLT-related commands.

zenity_file_dialogs.py |br|
   Replaces Leo's file dialogs on Linux with external
   calls to the zenity gtk dialog package.
</t>
<t tx="ekr.20101113063552.9399" str_atime="1376413520.0"></t>
<t tx="ekr.20101113063552.9400">Edits user attributes in a Qt frame.

This plugin creates a frame for editing attributes similar to::

    Name:   Fred Blogs
    Home:   555-555-5555
    Work:   555-555-5556

``attrib_edit`` is also intended to provide attribute editing for
other plugins, see below.

The attributes can be stored in different ways, three modes are implemented
currently:

v.u mode
  These attributes are stored in the "unknownAttributes" (uA) data for
  each node, accessed via v.u.

Field:
  Attributes are lines starting (no whitespace) with "AttributeName:" in
  the body text.

@Child
  Attributes are the head strings of child nodes when the head string
  starts with '@AttributeName' where the first letter (second character)
  must be capitalized.

The plugin defines the following commands, available either in the
plugin's sub-menu in the Plugins menu, or as ``Alt-X attrib-edit-*``.

attrib-edit-modes
    Select which attribute setting / getting modes to use.  More than one mode
    can be used at the same time.

    You can also control which modes are active by listing them 
    with the @data attrib_edit_active_modes setting.  For example::

        Field:
        @Child
        # v.u mode

    would cause only the "Field:" and "@Child" modes to be active be default.

attrib-edit-manage
    Select which attributes, from all attributes seen so
    far in this outline, to include on the current node.

attrib-edit-scan
    Scan the entire outline for attributes so ``attrib-edit-manage``
    has the complete list.

attrib-edit-create
    Create a new attribute on the current node.  If Field: or \@Child modes
    are active, they simply remind you how to create an attribute in the log pane.
    If the "v.u mode" mode is active, you're prompted for a path for the attribute.
    For example::

        addressbook First

    to store the attribute in v.u['addressbook']['_edit']['First']

    As a convenience, entering a path like::

        todo metadata created|creator|revised

    would create::

        v.u.['todo']['metadata']['_edit']['created']
        v.u.['todo']['metadata']['_edit']['creator']
        v.u.['todo']['metadata']['_edit']['revised']


**Technical details**

See the source for complete documentation for use with other
plugins. Here are some points of interest:

- In addition to ``v.u['addressbook']['_edit']['first']``, paths
  like ``v.u['addressbook']['_edit']['_int']['age']`` may be used
  to identify type, although currently there's no difference in
  the edit widget.

- In the future the plugin may allow other plugins to register
  to provide attribute path information, instead of just
  scanning for ['_edit'] entries in v.u.

- Currently there's no sorting of the attributes in "v.u mode", which is
  a problem for some applications.  It's unclear where the
  desired order would be stored, without even more repetition
  in v.u.  When other plugins can register to manipulate the
  attribute list each plugin could address this, with unordered
  presentation in the absence of the client plugin.

- There's code to have the editor appear in a tab instead
  of its own area under the body editor, but (a) this is
  always being buried by output in the log window, and
  (b) there's a bug which leaves some (harmless) ghost 
  widgets in the background.  Enable by @setting
  ``attrib_edit_placement`` to 'tab'.

</t>
<t tx="ekr.20101113063552.9401">Manipulates appearance of individual tree widget items.

This plugin is mostly an example of how to change the appearance of headlines.
As such, it does a relatively mundane chore of highlighting @thin, @auto,
@shadow nodes in bold.
</t>
<t tx="ekr.20101113063552.9402">Defines various useful actions for context menus (Qt only).

Examples are:

- Edit in $EDITOR
- Edit @thin node in $EDITOR (remember to do "refresh" after this!)
- Refresh @thin node from disk (e.g. after editing it in external editor)
- Go to clone

Here's an example on how to implement your own context menu items 
in your plugins::

    def nextclone_rclick(c,p, menu):
        """ Go to next clone """

        # only show the item if you are on a clone
        # this is what makes this "context sensitive"
        if not p.isCloned():
            return    

        def nextclone_rclick_cb():
            c.goToNextClone()

        # 'menu' is a QMenu instance that was created by Leo 
        # in response to right click on tree item

        action = menu.addAction("Go to clone")
        action.connect(action, QtCore.SIGNAL("triggered()"), nextclone_rclick_cb)

And call this in your plugin *once*::

    g.tree_popup_handlers.append(nextclone_rclick)

</t>
<t tx="ekr.20101113063552.9403">Adds "Back" and "Forward" buttons (Qt only).

Creates "back" and "forward" buttons on button bar. These navigate
the node history.

This plugin does not need specific setup. If the plugin is loaded, the buttons 
will be available. The buttons use the icon specified in the active Qt style

</t>
<t tx="ekr.20101113063552.9404">Creates a wizard that creates @auto nodes.

Opens a file dialog and recursively creates @auto &amp; @path nodes from the path
where the selected file is (the selected file itself doesn't matter.)

</t>
<t tx="ekr.20101113063552.9405">Adds a fast-to-use search widget, like the "Find in files" feature of many editors.

Just load the plugin, activate "Nav" tab, enter search text and press enter.

The pattern to search for is, by default, a case *insensitive* fnmatch pattern
(e.g. foo*bar), because they are typically easier to type than regexps. If you
want to search for a regexp, use 'r:' prefix, e.g. r:foo.*bar.

Regexp matching is case sensitive; if you want to do a case-insensitive regular
expression search (or any kind of case-sensitive search in the first place), do it
by searching for "r:(?i)Foo". (?i) is a standard feature of Python regular expression
syntax, as documented in 

http://docs.python.org/library/re.html#regular-expression-syntax

</t>
<t tx="ekr.20101113063552.9406">Provides a Scrolled Message Dialog service for Qt.

The plugin can display messages supplied as plain text or formatted as html. In
addition the plugin can accept messages in rst format and convert them to be
displayed as html.

The displayed format can be controlled by the user via check boxes, so rst
messages may be viewed either as text or as html. Html messages can also be
viewed as raw text, which will be a good debug feature when creating complex
dynamically generated html messages.

The user interface is provided by a ScrolledMessage.ui file which is dynamically
loaded each time a new dialog is loaded.

The dialog is not modal and many dialogs can exist at one time. Dialogs can be
named and output directed to a dialog with a specific name.

The plugin is invoked like this::

    g.doHook('scrolledMessage', c=c, msg='message', title='title',  ...etc    )

or::

    g.app.gui.runScrolledMessageDialog(c=c, ...etc)

All parameters are optional except c.

**Parameters**

msg:
    The text to be displayed (html, rst, plain).

    If the text starts with 'rst:' it is assumed to be rst text and
    is converted to html for display after the rst: prefix has been removed.
    If the text starts with '&lt;' it is assumed to be html.
    These auto detection features can be overridden by 'flags'.

label:
    The text to appear in a label above the display. If it is '', the label is hidden.

title:
    The title to appear on the window or dock.

flags:
    Says what kind of message: 'rst', 'text', 'html'. This overrides auto-detection.

    Flags can be combined, for example, 'rst html' causes the message to be interpreted as rst and
    displayed as html.

..  To Do
..  - Add parameters to control position, size, closing, hiding etc.
..  - Save or print files from the dialog.
..  - Add an option to put the dialog in leo's log notebook.
..  - Add \@settings to control default behavior
..  - Provide a menu of plugins that allows their docstring to be displayed.
..  - Provide a menu of @rst nodes in the current outline, automatically track changes
..    if it is set to display any of these nodes.
</t>
<t tx="ekr.20101113063552.9407">Launches the spyder environment with access to Leo instance.
See http://packages.python.org/spyder/

Execute alt-x spyder-launch to start spyder. Execute alt-x spyder-update to pass
current c,p,g to spyder interactive session. spyder-update also shows the window
if it was closed before.

</t>
<t tx="ekr.20101113063552.9408">Adds simple "sticky notes" feature (popout editors) for Qt gui.

Adds the following (``Alt-X``) commands:

``stickynote``
  pop out current node as a sticky note
``stickynoter``
  pop out current node as a rich text note
``stickynoteenc``
  pop out current node as an encrypted note
``stickynoteenckey``
  enter a new en/decryption key
``tabula``
  add the current node to the stickynotes in the `Tabula`
  sticky note dock window, and show the window
``tabula-show``
  show the`Tabula` sticky note dock window
  (without adding the current node)
``tabula-marked``
  add all marked nodes to the stickynotes in the `Tabula`
  sticky note dock window, and show the window

Sticky notes are synchronized (both ways) with their parent Leo node.

Encrypted mode requires the python-crypto module.

The first time you open a note in encrypted mode you'll be asked for a pass
phrase. That phrase will be used for the rest of the session, you can change it
with ``Alt-X`` ``stickynoteenckey``, but probably won't need to.

The encrypted note is stored in base64 encoded *encrypted* text in the parent
Leo node, if you forget the pass phrase there's no way to un-encrypt it again.
Also, you must not edit the text in the Leo node.

When **creating an encrypted note**, you should **start with an empty node**.
If you want to encrypt text that already exists in a node, select-all cut it to
empty the node, then paste it into the note.

</t>
<t tx="ekr.20101113063552.9409">Provides to-do list and simple task management for leo (Qt only).

This plugin adds time required, progress and priority settings for nodes. With
the @project tag a branch can display progress and time required with dynamic
hierarchical updates.

For full documentation see:

  - http://leo.zwiki.org/ToDo 
  - http://leo.zwiki.org/tododoc.html

</t>
<t tx="ekr.20101113063552.9410">Creates a window for *live* rendering of rst, html, etc.  Qt only.

viewrendered.py creates a single ``Alt-X`` style command, ``viewrendered``,
which opens a new window where the current body text is rendered as HTML
(if it starts with '&lt;'), or otherwise reStructuredText.  reStructuredText
errors and warnings may be shown.  For example, both::

    Heading
    -------

    `This` is **really** a line of text.

and::

    &lt;h1&gt;Heading&lt;h1&gt;

    &lt;tt&gt;This&lt;/tt&gt; is &lt;b&gt;really&lt;/b&gt; a line of text.

will look something like:

**Heading**

`This` is **really** a line of text.

</t>
<t tx="ekr.20101113063552.9411">Adds a graph layout for nodes in a tab.
Requires Qt and the backlink.py plugin.

</t>
<t tx="ekr.20101113063552.9412"></t>
<t tx="ekr.20101113063552.9413">Allows users to define new @direcives.

</t>
<t tx="ekr.20101113063552.9414">Adds a context menu to each node containing all the commands in the bzr Qt
interface. Bzr is invoked based on the path of the current node.

**Requires contextmenu.py.**

</t>
<t tx="ekr.20101113063552.9415">Allows Leo to open any empty file as a minimal .leo file.

</t>
<t tx="ekr.20101113063552.9416">Allows the user to import Cisco configuration files.

Adds the "File:Import:Import Cisco Configuration" menu item. The plugin will:

1)  Create a new node, under the current node, where the configuration will be
    written. This node will typically have references to several sections (see below).

2)  Create sections (child nodes) for the indented blocks present in the original
    config file. These child nodes will have sub-nodes grouping similar blocks (e.g.
    there will be an 'interface' child node, with as many sub-nodes as there are real
    interfaces in the configuration file).

3)  Create sections for the custom keywords specified in the customBlocks[] list in
    importCiscoConfig(). You can modify this list to specify different keywords. DO
    NOT put keywords that are followed by indented blocks (these are taken care of by
    point 2 above). The negated form of the keywords (for example, if the keyword is
    'service', the negated form is 'no service') is also included in the sections.


4)  Not display consecutive empty comment lines (lines with only a '!').

All created sections are alphabetically ordered.

</t>
<t tx="ekr.20101113063552.9417">Modifies the Python @auto importer so that the importer
puts the __init__ method (ctor) into the body of the class node.

This makes it easier to keep the instance variable docs in the class
docstring in sync. with the ivars as manipulated by __init__, saves
repeating explanations in both places.

Note that this is done *after* the consistency checks by the @auto
import code, so using this plugin is at your own risk.  It will change
the order of declarations if other methods are declared before __init__.

</t>
<t tx="ekr.20101113063552.9418">Allows the user to browse XML documents in Leo.

This file implements an interface to XML generation,
so that the resulting file can be processed by leo.

..  class file represents the whole leo file.
..  class leo_node has a headline and body text.

..  If you encounter the first of a set of clones, create a leo_node. If you
..  encounter the same set of clones later, create a leo_clone node and refer back
..  to the first element.

</t>
<t tx="ekr.20101113063552.9419">Adds #line directives in perl and perlpod programs.

Over-rides two methods in leoAtFile.py to write #line directives after node
sentinels. This allows compilers to give locations of errors in relation to the
node name rather than the filename. Currently supports only perl and perlpod.

</t>
<t tx="ekr.20101113063552.9420">Creates new nodes containing parameterized section reference.

.. No longer available: http://sourceforge.net/forum/message.php?msg_id=2444117

This plugin adds nodes under the currently selected tree that are to act as
section references. To do so, go the Outline menu and select the
'Parameterize Section Reference' command. This plugin looks for a top level node called
'Parameterized Nodes'. If it finds a headline that matches the section reference
it adds a node/nodes to the current tree.

To see this in action, do the following:

0. **Important**: in the examples below, type &lt;&lt; instead of &lt; &lt; and
   type &gt;&gt; instead of &gt; &gt;.  Docstrings can not contain section references!

1. Create a node called 'Parameterized Nodes', with a sub-node called  &lt; &lt; Meow \&gt;\&gt;.
   The body of &lt; &lt; Meow &gt; &gt; should have the text::

        I mmmm sooo happy I could  &lt; &lt; 1$  &gt; &gt;.
        But I don't know if I have all the  &lt; &lt; 2$  &gt; &gt;
        money in the world.

2. In a node called A, type::

        &lt; &lt; meow( purrrrrr, zzooot )  &gt; &gt;
        (leave the cursor at the end of the line)

3. In a node called B, type::

         &lt; &lt; meow ( spit or puke, blinkin  )  &gt; &gt;
        (leave the cursor at the end of the line)

4. Leave the cursor in Node A at the designated point.

5. Go to Outline and select Parameterize Section Reference.

The plugin searches the outline, goes to level one and finds a Node with the Headline,
"Parameterized Nodes". It looks for nodes under that headline with the the headline
&lt;\&lt; meow &gt;\&gt;. It then creates this node structure under Node A::

        &lt; &lt; meow ( purrrrrr, zzooot ) &gt; &gt;
            &lt; &lt;2$&gt; &gt;
            &lt; &lt;1$&gt; &gt;

6. Examine the new subnodes of Node A:  

        &lt; &lt; meow ( purrrrrr, zzooot ) &gt; &gt; contains the body text of the &lt; &lt; meow &gt; &gt; node.
        &lt; &lt; 1$ &gt; &gt; contains the word purrrrrr.
        &lt; &lt; 2$ &gt; &gt; contains the word zzooot.

7. Go to Node B, and leave the cursor at the designated point.

Go to Outline Menu and select Parameterize Section Reference command.

8. Examine the new subnodes of Node B.

It's a lot easier to use than to explain!

</t>
<t tx="ekr.20101113063552.9421">Autosaves the Leo outline every so often.

The time between saves is given by the setting, with default as shown::

    @int mod_autosave_interval = 300

This plugin is active only if::

    @bool mod_autosave_active = True

</t>
<t tx="ekr.20101113063552.9422">Allows Leo to read a complete directory tree into a Leo outline. Converts
directories into headlines and puts the list of file names into bodies.

Ce plug-in permet de traduire l'arborescence d'un répertoire en une arborescence
Leo : Chaque dossier est converti en noeud dans Leo ; son nom est placé dans
l'entête du noeud et chaque nom de fichier qu'il contient est listé dans son
contenu.

Feedback on this plugin can be sent to::

    Frédéric Momméja
    &lt;frederic [point] mommeja [at] laposte [point] net&gt;

</t>
<t tx="ekr.20101113063552.9423">Timestamps all save operations to show when they occur.

</t>
<t tx="ekr.20101113063552.9425">Modifies the way exported outlines are written.

</t>
<t tx="ekr.20101113063552.9426">Creates new headlines from clipboard text.

If the pasted text would be greater than 50 characters in length, the plugin
truncates the headline to 50 characters and pastes the entire line into the body
text of that node. Creates a "Paste as Headlines" option the Edit menu directly
under the existing Paste option.

</t>
<t tx="ekr.20101113063552.9427">Customizes pretty printing.

The plugin creates a do-nothing subclass of the default pretty printer. To
customize, simply override in this file the methods of the base prettyPrinter
class in leoCommands.py. You would typically want to override putNormalToken or
its allies. Templates for these methods have been provided. You may, however,
override any methods you like. You could even define your own class entirely,
provided you implement the prettyPrintNode method.

</t>
<t tx="ekr.20101113063552.9428">Creates buttons to move nodes quickly to other nodes.

Quickly move/copy/clone nodes from around the tree to one or more target nodes.
It can also create bookmark and tagging functionality in an outline (see `Set
Parent Notes` below).

Adds `Move/Clone/Copy To Last Child Button` and `Move/Clone/Copy To First Child Button`,
`Link To/From` and `Jump To` commands to the Move sub-menu on the
Outline menu, and each node's context menu, if the `contextmenu` plugin is enabled.

Select a node ``Foo`` and then use the `Move To Last Child Button` command.
This adds a 'to Foo' button to the button bar. Now select another node and click
the 'to Foo' button. The selected node will be moved to the last child
of the node 'Foo'.

`To First Child Button` works the same way, except that moved nodes are inserted
as the first child of the target node.

`Clone` and `Copy` variants are like `Move`, but clone or copy instead of moving.

`Link` works in conjunction with the `backlink` plugin (and also the
`graphcanvas` plugin) creating a link to/from the target and current nodes.

`Jump` buttons act as bookmarks, taking you to the target node.

You can right click on any of these buttons to access their context menu:

  Goto Target
    takes you to the target node (like a `Jump` button).
  Make Permanent
    makes the button permanent, it will reappear
    when the file is saved / closed / re-opened.
  Set Parent
    allows you to move buttons to sub-menu items of other
    `quickMove` buttons.  This implicitly makes the moved button
    permanent.  It also causes the moved button to lose its context menu.
  Remove Button
    comes from the `mod_scripting` plugin, and just
    removes the button for the rest of the current session.

Set Parent Notes
  `Set Parent` doesn't allow you to do anything with `quickMove` you couldn't
  do with a long strip of separate buttons, but it collects quickMove buttons
  as sub-menu items of one quickMove button, saving a lot of toolbar space.

Bookmarks 
  Create somewhere out of the way in your outline a node called
  `Bookmarks`. Use the quickMove menu to make it a `Jump To` button, and use its
  context menu to make it permanent. There is no particular reason to jump to
  it, but it needs to be a `quickMove` button of some kind.

  Now, when you want to bookmark a node, first use the quickMove menu to make
  the node a `Jump To` button, and then use the context menu on the button to
  set its parent to your `Bookmarks` button.  It becomes a sub-menu item
  of the `Bookmarks` button.

Tags
  In conjunction with the `backlinks` plugin you can use `quickMove` to
  tag nodes.   The `backlinks` plugin adds a `Links` tab to the `Log pane`.

  Create somewhere in your outline a node called `Tags`. Use the quickMove menu
  to make it a `Jump To` button, and use its context menu to make it permanent.
  Clicking on it will jump you to your tag list. Now create a node under the
  `Tags` node for each tag you want. The node's name will be the tag name, and
  can be changed later. Then use the quickMove menu to make each of these nodes
  a `Link To` button, and then use the context menu on the button to set its
  parent to your `Tags` button. It becomes a sub-menu item of the `Tags` button.

  To see the tags on a node, you need to be looking at the `Links` tab in the
  `Log pane`.  To see all the nodes with a particular tag, click on the `Tags`
  button to jump to the tag list, and select the node which names the tag of
  interest.  The nodes with that tag will be listed in th `Links` tab in the
  `Log pane`.

</t>
<t tx="ekr.20101113063552.9429">Sets g.app.homeDir to a hard-coded path.

</t>
<t tx="ekr.20101113063552.9430">Counts characters, words, lines, and paragraphs in the body pane.

It adds a "Word Count..." option to the bottom of the Edit menu that will
activate the command.

</t>
<t tx="ekr.20101113063552.9431"></t>
<t tx="ekr.20101113063552.9432">Makes g.pdb() enter the Pudb debugger instead of pdb.

Pudb is a full-screen Python debugger:
http://pypi.python.org/pypi/pudb

</t>
<t tx="ekr.20101113063552.9433">Dumps Python globals at startup.

</t>
<t tx="ekr.20101113063552.9434">Enables debugging and tracing for Python's garbage collector.

</t>
<t tx="ekr.20101113063552.9435">Shows how to force Leo to quit.

</t>
<t tx="ekr.20101113063552.9436" str_atime="1376412861.0">Traces changes to Leo's objects at idle time.

</t>
<t tx="ekr.20101113063552.9437">Traces keystrokes in the outline and body panes.

</t>
<t tx="ekr.20101113063552.9438">Traces most common hooks, but not key, drag or idle hooks.

</t>
<t tx="ekr.20101113063552.9439"></t>
<t tx="ekr.20101113063552.9440">Creates a two-way communication (bridge) between Leo
scripts and IPython running in the console from which Leo was launched.

Using this bridge, scripts running in Leo can affect IPython, and vice versa.
In particular, scripts running in IPython can alter Leo outlines!

For full details, see Leo Users Guide:
http://leoeditor.com/IPythonBridge.html

</t>
<t tx="ekr.20101113063552.9441">Replaces c.openWithTempFilePath to create alternate temporary
directory paths.

Two alternates are supported. The default method creates temporary files with a
filename that begins with the headline text, and located in a "username_Leo"
subdirectory of the temporary directory. The "LeoTemp" prefix is omitted. If
'open_with_clean_filenames' is set to true then subdirectories mirror the node's
hierarchy in Leo. Either method makes it easier to see which temporary file is
related to which outline node.

</t>
<t tx="ekr.20101113063552.9442">Creates an 'Extensions' menu containing two commands:
Open Console Window and Open Explorer.

The Open Console Window command opens xterm on Linux.
The Open Explorer command Opens a Windows explorer window.

This allows quick navigation to facilitate testing and navigating large systems
with complex directories.

Please submit bugs / feature requests to etaekema@earthlink.net

Current limitations:
- Not tested on Mac OS X ...
- On Linux, xterm must be in your path.

</t>
<t tx="ekr.20101113063552.9443">Allows imports of notes created in Tomboy / gnote.

Usage:

* Create a node with the headline 'tomboy'
* Select the node, and do alt+x act-on-node    
* The notes will appear as children of 'tomboy' node
* The next time you do act-on-node, existing notes will be updated (they don't need to 
  be under 'tomboy' node anymore) and new notes added.

</t>
<t tx="ekr.20101113063552.9444">Enables two-way communication with VIM.

It's recommended that you have gvim installed--the basic console vim is not recommended.

When properly installed, this plugin does the following:

- By default, the plugin opens nodes on icondclick2 events.
  (double click in the icon box)

- The setting::

    @string vim_trigger_event = icondclick2

  controls when nodes are opened in vim.  The default, shown above,
  opens a node in vim on double clicks in Leo's icon box.
  A typical alternative would be::

      @string vim_trigger_event = iconclick2

  to open nodes on single clicks in the icon box.
  You could also set:

      @string vim_trigger_event = select2

  to open a node in vim whenever the selected node changes for any reason.

- Leo will put Vim cursor at same location as Leo cursor in file if 'vim_plugin_positions_cursor' set to True.

- Leo will put node in a Vim tab card if 'vim_plugin_uses_tab_feature' set to True.

- Leo will update the node in the outline when you save the file in VIM.

To install this plugin do the following:

1. On Windows, set the vim_cmd and vim_exe settings to the path to vim or gvim
   as shown in leoSettings.leo. Alternatively, you can ensure that gvim.exe is
   on your PATH.

1. If you are using Python 2.4 or above, that's all you need to do. Jim
   Sizelove's new code will start vim automatically using Python's subprocess
   module. The subprocess module comes standard with Python 2.4. For Linux
   systems, Leo will use subprocess.py in Leo's extensions folder if necessary.
</t>
<t tx="ekr.20101113063552.9445">Allows you to edit nodes in emacs/xemacs.

Depending on your preference, selecting or double-clicking a node will pass the
body text of that node to emacs. You may edit the node in the emacs buffer and
changes will appear in Leo.

</t>
<t tx="ekr.20101113063552.9446">Adds the Plugins\:Word Export\:Export menu item to format and export
the selected outline to a Word document, starting Word if necessary.

</t>
<t tx="ekr.20101113063552.9447"></t>
<t tx="ekr.20101113063552.9448">Synchronizes @path nodes with folders.

If a node is named '@path path_to_folder', the content (file and folder names)
of the folder and the children of that node will synchronized whenever the
node's status-iconbox is double clicked.

For files not previously seen in a folder a new node will appear on top of the
children list (with a mark).

Folders appear in the list as /foldername/. If you double click on the icon-box
of the folder node, it will have children added to it based on the contents of
the folder on disk. These folders have the '@path' directive as the first line
of their body text.

When files are deleted from the folder and the list is updated by double
clicking the files will appear in the list as *filename* (or */foldername/*).

You can describe files and directories in the body of the nodes.

You can organize files and directories with organizer nodes, an organizer node
name cannot contain with '/'.

Files and folders can be created by entering a node with the required name as
its headline (must start and/or end with "/" for a folder) and then double
clicking on the node's status-iconbox.

\@auto nodes can be set up for existing files can be loaded by
double clicking on the node's status-iconbox. If you prefer
\@shadow or something else use the "active_path_attype" setting,
without the "@".

There are commands on the Plugins active_path submenu:

- show path - show the current path
- set absolute path - changes a node "/dirname/" to "@path /absolute/path/to/dirname".
- purge vanished (recursive) - remove *entries*
- update recursive - recursive load of directories, use with caution on large
  file systems

If you want to use an input other than double clicking a node's status-iconbox
set active_path_event to a value like 'iconrclick1' or 'iconclick1'.

There are @settings for ignoring directory entries and automatically loading files.  ``re.search`` is used, rather than ``re.match``, so patterns need only match part of the filename, not the whole filename.

The body of the @setting ``@data active_path_ignore`` is a list of regex
patterns, one per line.  Directory entries matching any pattern in the list will be ignored.  The names of directories used for matching will have forward slashes around them ('/dirname/'), so patterns can use this to distinguish between directories and files.

The body of the @setting ``@data active_path_autoload`` is a list of regex
patterns, one per line.  File entries matching any pattern in the list will be loaded automatically.  This works only with files, not directories (but you can load directories recursively anyway).

Set ``@bool active_path_load_docstring = True`` to have active_path load the docstring
of .py files automatically.  These nodes start with the special string::

    @language rest # AUTOLOADED DOCSTRING

which must be left intact if you want active path to be able to double-click load
the file later.

\@float active_path_timeout_seconds (default 10.) controls the maximum
time active_path will spend on a recursive operation.

\@int active_path_max_size (default 1000000) controls the maximum
size file active_path will open without query.

active_path is a rewrite of the at_directory plugin to use \@path directives
(which influence \@auto and other \@file type directives), and to handle
sub-folders more automatically.

</t>
<t tx="ekr.20101113063552.9449">Synchronizes @folder nodes with folders.

If a node is named '@folder path_to_folder', the content (filenames) of the
folder and the children of that node will be sync. Whenever a new file is put
there, a new node will appear on top of the children list (with mark). So that
I can put my description (i.e. annotation) as the content of that node. In this
way, I can find any files much easier from leo.

Moreover, I add another feature to allow you to group files(in leo) into
children of another group. This will help when there are many files in that
folder. You can logically group it in leo (or even clone it to many groups),
while keep every files in a flat/single directory on your computer.

</t>
<t tx="ekr.20101113063552.9450">Executes commands in nodes whose body text starts with @produce.

To use, put in the body text of a node::

    @produce javac -verbose Test.java

To execute, you goto Outline and look at Produce.  Choose Execute All Produce
or Execute Tree Produce.  The Tree does the current Tree, All does the whole
Outline.  Executing will fire javac, or whatever your using.  @produce functions
as a directive.  After executing, a log file/node is created at the top of the
Outline.  Any output, even error messages, should be there.

It executes in a hierarchal manner.  Nodes that come before that contain @produce
go first.

I'm hoping that this orthogonal to @run nodes and anything like that.  Its not
intended as a replacement for make or Ant, but as a simple substitute when that
machinery is overkill.

WARNING: trying to execute a non-existent command will hang Leo.

</t>
<t tx="ekr.20101113063552.9451">Adds support for \@clip, \@view and \@strip nodes.

- Selecting a headline containing \@clip appends the contents of the clipboard to
  the end of the body pane.

- Double clicking the icon box of a node whose headline contains \@view
  *&lt;path-to-file&gt;* places the contents of the file in the body pane.

- Double clicking the icon box of a node whose headline contains \@strip
  *&lt;path-to-file&gt;* places the contents of the file in the body pane, with all
  sentinels removed.

This plugin also accumulates the effect of all \@path nodes.

</t>
<t tx="ekr.20101113063552.9452">Allows arbitrary links between nodes.

</t>
<t tx="ekr.20101113063552.9453">Allows users to insert headlines containing dates.

'Date nodes' are nodes that have dates in their headlines. They may be added to
the outline one at a time, a month's-worth at a time, or a year's-worth at a
time. The format of the labels (headlines) is configurable.

There are options to omit Saturdays and Sundays.

An 'Insert Date Nodes ...' submenu will be created (by default) in the 'Outline'
menu.  This menu can be suppressed by using either of the following settings:

    - @bool suppress-datenodes-menus
    - @bool suppress-all-plugins-menus

The following commands are available for use via the minibuffer or in
@menu/@popup settings.

    - datenodes-today
    - datenodes-this-month
    - datenodes-this-year

</t>
<t tx="ekr.20101113063552.9454">Adds @expfolder nodes that represent folders in the file system.

Double clicking on the icon of an @expfolder heading reads the files in the
directory at the path specified and creates child nodes for each file in the
subfolder. Subdirectories are made into child @expfolder nodes so the tree can
be easily traversed. If files have extensions specified in the expfolder.ini
file they are made into @text nodes so the content of the files can be easily
loaded into leo and edited. Double clicking a second time will delete all child
nodes and refresh the directory listing. If there are any changed @text nodes
contained inside you will be prompted about saving them.

The textextensions field on the expfolder Properties page contains a list of
extensions which will be made into @text nodes, separated by spaces.

For the @text and @expfolder nodes to interact correctly, the textnode plugin
must load before the expfolder plugin. This can be set using the Plugin
Manager's Plugin Load Order pane.

</t>
<t tx="ekr.20101113063552.9455">Defines actions taken when double-clicking on @&lt;file&gt; nodes and supports
@file-ref nodes.

Double-clicking any kind of @&lt;file&gt; node writes out the file if changes have
been made since the last save, and then runs a script on it, which is retrieved
from the outline.

Scripts are located in a node whose headline is FileActions. This node can be
anywhere in the outline. If there is more than one such node, the first one in
outline order is used.

The children of that node are expected to contain a file pattern in the headline
and the script to be executed in the body. The file name is matched against the
patterns (which are Unix-style shell patterns), and the first matching node is
selected. If the filename is a path, only the last item is matched.

Execution of the scripts is similar to the "Execute Script"
command in Leo. The main difference is that the namespace
in which the scripts are run contains these elements:

- 'c' and 'g' and 'p': as in the regular execute script command.

- 'filename': the filename from the @file directive.

- 'shellScriptInWindow', a utility function that runs a shell script in an
   external windows, thus permitting programs to be called that require user
   interaction

File actions are implemented for all kinds @&lt;file&gt; nodes. There is also a new
node type @file-ref for referring to files purely for the purpose of file
actions, Leo does not do anything with or to such files.

</t>
<t tx="ekr.20101113063552.9456">Tags nodes with latitude and longitude.

</t>
<t tx="ekr.20101113063552.9457">Creates a LeoCursor object that can walk around a Leo outline and decode
attributes from nodes.

Node names can be used through . (dot) notation so ``cursor.Data.Name._B`` for
example returns the body text of the Name node which is a child of the Data node
which is a child of the cursors current location.

See .../plugins/examples/leocursorexample.leo for application.

</t>
<t tx="ekr.20101113063552.9458">Opens files with their default platform program.

Double-clicking @mime nodes will attempt to open the named file as if opened
from a file manager. \@path parent nodes are used to find the full filename
path.  Fore example::

    @mime foodir/document.pdf

The string setting 'mime_open_cmd' allows specifying a program to handle opening
files::

    @settings
        @string mime_open_cmd = see
        .. or ..
        @string mime_open_cmd = see %s

Where '%s' is replaced with the full pathname.

**Note**: This plugin terminates handling of the 'icondclick1' event by returning
True. If another plugin using this event (e.g. vim.py) is also enabled, the
order in @enabled-plugins matters. For example: if vim.py is enabled before
mime.py, double-clicking on an @mime node will both open the body text in [g]vim
AND call the mime_open_cmd.

This plugin is complementary to the UNL.py plugin's @url nodes. Use @url for
opening either URLs or Uniform Node Locators in "\*.leo" files and use @mime
nodes for opening files on the local file system. It also replaces the
startfile.py plugin, where here the headline must start with @mime to activate
this plugin.

For other sys.platform's, add an elif case to the section "guess file
association handler" and either define a default _mime_open_cmd string, where
"%s" will be replaced with the filename, or define a function taking the
filename string as its only argument and set as open_func.

</t>
<t tx="ekr.20101113063552.9459">Allows Leo to write a file to multiple locations.

This plugin acts as a post-write mechanism, a file must be written to the
file system for it to work. At this point it is not a replacement for @path or an
absolute path, it works in tandem with them.

To use, place @multipath at the start of a line in the root node or an ancestor
of the node. The format is (On Unix-like systems)::

    @multipath /machine/unit/:/machine/robot/:/machine/

New in version 0.6 of this plugin: the separator used above is ';' not ':',
for example::

    @multipath c:\prog\test;c:\prog\unittest

It will places copy of the written file in each of these directories.

There is an additional directive that simplifies common paths, it is called
@multiprefix. By typing @multiprefix with a path following it, before a
@multipath directive you set the beginning of the paths in the @multipath
directive. For example::

    #@multiprefix /leo #@multipath /plugins 

or::

    #@multiprefix /leo/
    #@multipath plugins: fungus : drain

copies a file to /leo/plugins /leo/fungus /leo/drain.

Note I put # in front of the directives here because I
don't want someone browsing this file to accidentally save multiple copies of
this file to their system :) )

The @multiprefix stays in effect for the entire tree until reset with another
@multiprefix directive. @multipath is cumulative, in that for each @multipath in
an ancestor a copy of the file is created. These directives must at the
beginning of the line and by themselves.

</t>
<t tx="ekr.20101113063552.9460">Ensures that all descendants of @file-nosent nodes end
with exactly one newline, replaces all tabs with spaces, and
adds a newline before class and functions in the derived file.

</t>
<t tx="ekr.20101113063552.9461">Creates and updates @read-only nodes.

Here's my first attempt at customizing leo. I wanted to have the ability to
import files in "read-only" mode, that is, in a mode where files could only
be read by leo (not tangled), and also kept in sync with the content on the
drive.

The reason for this is for example that I have external programs that generate
resource files. I want these files to be part of a leo outline, but I don't
want leo to tangle or in any way modify them. At the same time, I want them
to be up-to-date in the leo outline.

So I coded the directive plugin. It has the following characteristics:

- It reads the specified file and puts it into the node content.

- If the @read-only directive was in the leo outline already, and the file content
  on disk has changed from what is stored in the outline, it marks the node as
  changed and prints a "changed" message to the log window; if, on the other hand,
  the file content has _not_ changed, the file is simply read and the node is
  not marked as changed.

- When you write a @read-only directive, the file content is added to the node
  immediately, i.e. as soon as you press Enter (no need to call a menu
  entry to import the content).

- If you want to refresh/update the content of the file, just edit the headline
  and press Enter. The file is reloaded, and if in the meantime it has changed,
  a "change" message is sent to the log window.

- The body text of a @read-only file cannot be modified in leo.

The syntax to access files in @read-only via ftp/http is the following::

    @read-only http://www.ietf.org/rfc/rfc0791.txt
    @read-only ftp://ftp.someserver.org/filepath

If FTP authentication (username/password) is required, it can be specified as follows::

    @read-only ftp://username:password@ftp.someserver.org/filepath

For more details, see the doc string for the class FTPurl.

Davide Salomoni

</t>
<t tx="ekr.20101113063552.9462">Runs a program and interface Leos through its input/output/error streams.

Double clicking the icon box whose headlines are @run 'cmd args' will execute
the command. There are several other features, including @arg and @input nodes.

The run_nodes.py plugin introduce two new nodes that transform leo into a
terminal. It was mostly intended to run compilers and debuggers while having the
possibility to send messages to the program.

Double clicking on the icon of an node whose headline is @run &lt;command&gt; &lt;args&gt;
will launch &lt;command&gt; with the given arguments. It will also mark the node. #
Terminates the argument list. @run # &lt;comment&gt; is also valid.

@in nodes are used to send input to the running process. Double clicking on
the icon of an @in &lt;message&gt; node will append a "\n" to &lt;message&gt; and write it
to the program, no matter where the node is placed. If no @run node is active,
nothing happens.

The body text of every child, in which the headlines do not begin with '@run'
or '@in', will be appended to &lt;command&gt;, allowing you to add an unlimited number
of arguments to &lt;command&gt;.

The output of the program is written in the log pane (Error output in red).
When the program exit the node is set unmarked and the return value is
displayed... When the enter key is pressed in the body pane of an active @run
node the content of it body pane is written to the program and then emptied
ready for another line of input. If the node have @run nodes in its descendants,
they will be launched successively. (Unless one returned an exit code other
than 0, then it will stop there)

By Alexis Gendron Paquette. Please send comments to the Leo forums.

</t>
<t tx="ekr.20101113063552.9463">Support slideshows in Leo outlines.

This plugin defines four new commands:

- next-slide-show:  move to the start of the next slide show,
  or the first slide show if no slide show has been seen yet.
- prev-slide-show:  move to the start of the previous slide show,
  or the first slide show if no slide show has been seen yet.
- next-slide: move to the next slide of a present slide show.
- prev-slide: move to the previous slide of the present slide show.

Slides shows consist of a root @slideshow node with descendant @slide nodes.
@slide nodes may be organized via non-@slide nodes that do not appear in the slideshow.

All these commands ignore @ignore trees.

</t>
<t tx="ekr.20101113063552.9464">Launches (starts) a file given by a headline when double-clicking the icon.

This plugin ignores headlines starting with an '@'. Uses the @folder path if the
headline is under an @folder headline. Otherwise the path is relative to the Leo
file.

</t>
<t tx="ekr.20101113063552.9466">Adds the Outline:XSLT menu containing XSLT-related commands.

This menu contains the following items:

- Set StyleSheet Node:
    - Selects the current node as the xsl stylesheet the plugin will use.

- Process Node with Stylesheet Node:
    - Processes the current node as an xml document,
      resolving section references and Leo directives.
    - Creates a sibling containing the results.

Requires 4Suite 1.0a3 or better, downloadable from http://4Suite.org.

</t>
<t tx="ekr.20101113063552.9467"></t>
<t tx="ekr.20101113063552.9468">Allows interaction with shell apps via screen.

Analysis environments like SQL, R, scipy, ipython, etc. can be
used by pasting sections of text from an editor (Leo) and a
shell window.  Results can be pasted back into the editor.

This plugin streamlines the process by communicating with ``screen``,
the shell multiplexer

**Commands**

leoscreen-run-text
  Send the text selected in Leo's body text to the shell app.
  Selects the next line for your convenience.

leoscreen-get-line
  Insert a line of the last result from the shell into Leo's body text
  at the current insert point.  Lines are pulled one at a time starting
  from the end of the output.  Can be used repeatedly to get the
  output you want into Leo.

leoscreen-get-all
  Insert all of the last result from the shell into Leo's body text
  at the current insert point.

leoscreen-get-note
  Insert all of the last result from the shell into a new child node of
  the current node.

leoscreen-show-all
  Show the output from the last result from the shell in a temporary
  read only window. **Important**: The output is not stored.

leoscreen-show-note
  Insert all of the last result from the shell into a new child node of
  the current node and display that node a a stickynote (requires stickynote
  plugin).

leoscreen-next
  Switch screen session to next window.

leoscreen-prev
  Switch screen session to preceding window.

leoscreen-other
  Switch screen session to last window displayed.

leoscreen-get-prefix
  Interactively get prefix for inserting text into body (#, --, //, etc/)
  Can also set using::

      c.leo_screen.get_line_prefix = '#'

leoscreen-more-prompt
  Skip one less line at the end of output when fetching output into Leo.
  Adjusts lines skipped to avoid pulling in the applications prompt line.

leoscreen-less-prompt
  Skip one more line at the end of output when fetching output into Leo
  Adjusts lines skipped to avoid pulling in the applications prompt line.

**Settings**

leoscreen_prefix
  Prepended to output pulled in to Leo. The substring SPACE in this
  setting will be replaced with a space character, to allow for trailing
  spaces.

leoscreen_time_fmt
  time.strftime format for note type output headings.

**Theory of operation**

leoscreen creates a instance at c.leo_screen which has some methods which might
be useful in ``@button`` and other Leo contexts.

**Example SQL setup**

In a Leo file full of interactive SQL analysis, I have::

    @settings
        @string leoscreen_prefix = --SPACE
    @button rollback
        import time
        c.leo_screen.run_text('ROLLBACK;  -- %s\n' % time.asctime())
    @button commit
        import time
        cmd = 'COMMIT;  -- %s' % time.asctime()
        c.leo_screen.run_text(cmd)
        c.leo_screen.insert_line(cmd)

which creates a button to rollback messed up queries, another to commit
(requiring additional action to supply the newline as a safeguard) and
sets the prefix to "-- " for text pulled back from the SQL session into
Leo.

**Implementation note**: screen behave's differently if screen -X is executed
with the same stdout as the target screen, vs. a different stdout. Although
stdout is ignored, Popen() needs to ensure it's not just inherited.

</t>
<t tx="ekr.20101113063552.9469">Creates script buttons and @button, @command, @plugin and @script
nodes.

This plugin puts buttons in the icon area. Depending on settings the plugin will
create the 'Run Script', the 'Script Button' and the 'Debug Script' buttons.

The 'Run Script' button is simply another way of doing the Execute Script
command: it executes the selected text of the presently selected node, or the
entire text if no text is selected.

The 'Script Button' button creates *another* button in the icon area every time
you push it. The name of the button is the headline of the presently selected
node. Hitting this *newly created* button executes the button's script.

For example, to run a script on any part of an outline do the following:

1.  Select the node containing the script.
2.  Press the scriptButton button.  This will create a new button.
3.  Select the node on which you want to run the script.
4.  Push the *new* button.

That's all.

For every @button node, this plugin creates two new minibuffer commands: x and
delete-x-button, where x is the 'cleaned' name of the button. The 'x' command is
equivalent to pushing the script button.

You can specify **global buttons** in leoSettings.leo or myLeoSettings.leo by
putting \@button nodes as children of an @buttons node in an \@settings trees.
Such buttons are included in all open .leo (in a slightly different color).
Actually, you can specify global buttons in any .leo file, but \@buttons nodes
affect all later opened .leo files so usually you would define global buttons in
leoSettings.leo or myLeoSettings.leo.

The cleaned name of an @button node is the headline text of the button with:

- Leading @button or @command removed,
- @key and all following text removed,
- @args and all following text removed,
- all non-alphanumeric characters converted to a single '-' characters.

Thus, cleaning headline text converts it to a valid minibuffer command name.

You can delete a script button by right-clicking on it, or by
executing the delete-x-button command.

The 'Debug Script' button runs a script using an external debugger.

This plugin optionally scans for @button nodes, @command, @plugin nodes and
@script nodes whenever a .leo file is opened.

- @button nodes create script buttons.
- @command nodes create minibuffer commands.
- @plugin nodes cause plugins to be loaded.
- @script nodes cause a script to be executed when opening a .leo file.

Such nodes may be security risks. This plugin scans for such nodes only if the
corresponding atButtonNodes, atPluginNodes, and atScriptNodes constants are set
to True in this plugin.

You can specify the following options in leoSettings.leo.  See the node:
@settings--&gt;Plugins--&gt;scripting plugin.  Recommended defaults are shown::

    @bool scripting-at-button-nodes = True
    True: adds a button for every @button node.

    @bool scripting-at-commands-nodes = True
    True: define a minibuffer command for every @command node.

    @bool scripting-at-plugin-nodes = False
    True: dynamically loads plugins in @plugins nodes when a window is created.

    @bool scripting-at-script-nodes = False
    True: dynamically executes script in @script nodes when a window is created.
    This is dangerous!

    @bool scripting-create-debug-button = False
    True: create Debug Script button.

    @bool scripting-create-run-script-button = False
    True: create Run Script button.
    Note: The plugin creates the press-run-script-button regardless of this setting.

    @bool scripting-create-script-button-button = True
    True: create Script Button button in icon area.
    Note: The plugin creates the press-script-button-button regardless of this setting.

    @int scripting-max-button-size = 18
    The maximum length of button names: longer names are truncated.

You can bind key shortcuts to @button and @command nodes as follows.

@button name @key=shortcut

    Binds the shortcut to the script in the script button. The button's name is
    'name', but you can see the full headline in the status line when you move the
    mouse over the button.

@command name @key=shortcut

    Creates a new minibuffer command and binds shortcut to it. As with @buffer
    nodes, the name of the command is the cleaned name of the headline.

This plugin is based on ideas from e's dynabutton plugin, quite possibly the
most brilliant idea in Leo's history.

You can run the script with sys.argv initialized to string values using @args.
For example:

@button test-args @args = a,b,c

will set sys.argv to [u'a',u'b',u'c']

</t>
<t tx="ekr.20101113063552.9470">Sends output from the Execute Script command to the end of the body pane.

</t>
<t tx="ekr.20101113063552.9471"></t>
<t tx="ekr.20101113063552.9472">Remote control for Leo.

Example client::

    from leo.external import lproto
    import os


    addr = open(os.path.expanduser('~/.leo/leoserv_sockname')).read()
    print("will connect to",addr)
    pc  = lproto.LProtoClient(addr)
    pc.send("""
        g.es("hello world from remote") 
        c = g.app.commanders()[0]
    """)

    # note how c persists between calls
    pc.send("""c.k.simulateCommand('stickynote')""")

</t>
<t tx="ekr.20101113063552.9473">A minimal http plugin for LEO, based on AsyncHttpServer.py.

Use this plugin is as follows:

1. Start Leo with the plugin enabled. You will see a purple message that says
   something like::

    "http serving enabled on port 8080, version 0.91"

2. Start a web browser, and enter the following url: http://localhost:8080/

You will see a a "top" level page containing one link for every open .leo file.
Start clicking :-)

You can use the browser's refresh button to update the top-level view in the
browser after you have opened or closed files.

To enable this plugin put this into your file::

    @settings
        @bool http_active = True
        @int  port = 8080
        @string rst_http_attributename = 'rst_http_attribute'

**Note**: the browser_encoding constant (defined in the top node of this file)
must match the character encoding used in the browser. If it does not, non-ascii
characters will look strange.

</t>
<t tx="ekr.20101113063552.9474"></t>
<t tx="ekr.20101113063552.9475">Creates stand-alone slideshows containing screenshots.

This plugin defines five commands. The
**apropos-slides** command prints this message to
Leo's log pane. The **slide-show-info** command
prints the settings in effect.

The **make-slide** and **make-slide-show**
commands, collectively called **slide commands**,
create collections of slides from **@slideshow**
trees containing **@slide** nodes.

Slides may link to screenshots. The slide commands
can generate screenshots from **@screenshot-tree**
nodes, but this feature has proven to be clumsy
and inflexible. It is usually more convenient to
use screenshots taken with a program such as Wink.
The **meld-slides** command creates references to
externally-generated screenshots within @slide
nodes.

\@slide nodes may contain **@url nodes**. These @url
nodes serve two purposes. First, they allow you to
see various files (slides, initial screenshots,
working files and final screenshots). Second,
these @url nodes guide the meld script and the
four commands defined by this plugin (see below).
By inserting or deleting these @url nodes you (or
your scripts) can customize how the commands (and
meld) work. In effect, the @url nodes become
per-slide settings.

**Prerequisites**

Inkscape (Required)
  An SVG editor: http://www.inkscape.org/
  Allows the user to edit screenshots.
  Required to create final output (PNG) files.

PIL (Optional but highly recommended)
  The Python Imaging Library,
  http://www.pythonware.com/products/pil/

Wink (Optional)
  A program that creates slideshows and slides.
  http://www.debugmode.com/wink/

**Summary**

@slideshow &lt;slideshow-name&gt;
  Creates the folder:
  &lt;sphinx_path&gt;/slides/&lt;slideshow-name&gt;

@slide &lt;ignored text&gt;
  Creates slide-&lt;slide-number&gt;.html
  (in the sphinx _build directory).
  **Note**: the plugin skips any @slide nodes
  with empty body text.

@screenshot
  Specifies the contents of the screenshot.

**Options** are child nodes of @slideshow or
\@slide nodes that control the make-slide and
make-slide-show commands. See the Options section
below.

The make-slide and make-slide-show commands
create the following @url nodes as children
of each @slide node:

@url built slide
  Contains the absolute path to the final slide in
  the _build/html subfolder of the slideshow
  folder. If present, this @url node completely
  disables rebuilding the slide.

@url screenshot
  Contains the absolute path to the original
  screenshot file. If present, this @url node
  inhibits taking the screenshot.

@url working file
  Contains the absolute path to the working file.
  If present, this @url node disables taking the
  screenshot, creating the working file. The final
  output file will be regenerated if the working
  file is newer than the final output file.

@url final output file
  Contains the absolute path to the final output
  file.

Thus, to completely recreate an @slide node, you
must delete any of the following nodes that appear
as its children::

    @url screenshot
    @url working file
    @url built slide

**Making slides**

For each slide, the make-slide and make-slide-show
commands do the following:

1. Create a slide.

  If the @slide node contains an @screenshot tree,
  the plugin appends an ``.. image::`` directive
  referring to the screenshot to the body text of
  the @slide node. The plugin also creates a child
  @image node referring to the screenshot.

2. (Optional) Create a screenshot.

  The plugin creates a screenshot for an @slide
  node only if the @slide node contains an
  @screenshot node as a direct child.

  **Important**: this step has largely been
  superseded by the ``@button meld`` script in
  LeoDocs.leo.

  Taking a screenshot involves the following steps:

  A. Create the **target outline**: screenshot-setup.leo.

    The target outline contains consists of all
    the children (and their descendants) of the
    @screenshot node.

  B. Create the **screenshot**, a bitmap (PNG) file.

    The slide commands take a screen shot of the
    target outline. The @pause option opens the
    target outline but does *not* take the
    screenshot. The user must take the screenshot
    manually. For more details, see the the
    options section below.

  C. Convert the screenshot file to a **work file**.

    The work file is an SVG (Scalable Vector
    Graphics) file: http://www.w3.org/Graphics/SVG/.

  D. (Optional) Edit the work file.

    If the @slide node has a child @edit node, the
    plugin opens Inkscape so that the user can
    edit the work file.

  E. Render the **final output file**.

    The plugin calls Inkscape non-interactively to
    render the final output file (a PNG image)
    from the work file. If the Python Imaging
    Library (PIL) is available, this step will use
    PIL to improve the quality of the final output
    file.

3. Build the slide using Sphinx.

  After making all files, the plugins runs Sphinx
  by running 'make html' in the slideshow folder.
  This command creates the final .html files in the
  _build/html subfolder of the slideshow folder.

4. Create url nodes.

  Depending on options, and already-existing @url
  nodes, the make-slide and make-slide-show
  commands may create one or more of the following
  \@url nodes::

    @url built slide
    @url screenshot
    @url working file 
    @url final output file

**Options and settings**

You specify options in the headlines of nodes.
**Global options** appear as direct children of
\@slideshow nodes and apply to all @slide nodes
unless overridden by a local option. **Local
options** appear as direct children of an @slide
node and apply to only to that @slide node.

**Global options nodes**

The following nodes may appear *either* as a
direct child of the @slideshow node or as the
direct child of an @slide node.

@sphinx_path = &lt;path&gt;
  This directory contains the slides directory,
  and the following files: 'conf.py',
  'Leo4-80-border.jpg', 'Makefile' and 'make.bat'.

@screenshot_height = &lt;int&gt;
  The height in pixels of screenshots.

@screenshot_width = &lt;int&gt;
  The height in pixels of screenshots.

@template_fn = &lt;path&gt;
  The absolute path to inkscape-template.svg

@title = &lt;any text&gt;
  The title to use for one slide or the entire
  slideshow.

@title_pattern = &lt;pattern&gt;
  The pattern used to generate patterns for one
  slide or the entire slideshow. The title is
  computed as follows::

    d = {
        'slideshow_name':slideshow_name,
        'slide_name':    slide_name,
        'slide_number':  sc.slide_number,
    }
    title = (pattern % (d)).title()

  If neither an @title or @title_pattern option
  node applies, the title is the headline of the
  \@slide node. If this is empty, the default
  pattern is::

    '%(slideshow_name)s:%(slide_number)s'

\@verbose = True/False
  True (or true or 1):  generate informational message.
  False (or false or 0): suppress informational messages.

\@wink_path = &lt;path&gt;
  This path contains screenshots created by wink.
  This is used only by the meld-slides command.

**Local options nodes**

The following nodes are valid only as the direct
child of an @slide node.

@callout &lt;any text&gt;
  Generates a text callout in the working .svg file.
  An @slide node may have several @callout children.

@edit = True/False
  If True (or true or 1) the plugin enters
  Inkscape interactively after taking a
  screenshot.

@markers = &lt;list of integers&gt;
  Generates 'numbered balls' in the working .svg file.

@pause = True/False
  If True (or true or 1) the user must take the
  screenshot manually. Otherwise, the plugin takes
  the screenshot automatically.

  If the slide node contains an @pause node as one
  of its directive children, the slide commands
  open the target node, but do *not* take a screen
  shot.

  The user may adjust the screen as desired, for
  example by selecting menus or showing dialogs.
  The *user* must then take the screen shot
  manually. **Important**: the screenshot need not
  be of Leo--it could be a screenshot of anything
  on the screen.

  As soon as the user closes the target
  outline, the slide commands look for the screen
  shot on the clipboard. If found, the slide
  commands save the screenshot to the screenshot
  file.

@screenshot
  The root of a tree that becomes the entire
  contents of screenshot. No screenshot is taken
  if this node does not exist.

@select &lt;headline&gt;
  Causes the given headline in the @screenshot
  outline to be selected before taking the screenshot.

**Settings**

@string screenshot-bin = &lt;path to inkscape.exe&gt;
  The full path to the Inkscape program.   

**File names**

Suppose the @slide node is the n'th @slide node in
the @slideshow tree whose sanitized name is
'name'. The following files will be created in
(relative to) the slideshow directory::

    slide-n.html.txt:   the slide's rST source.
    screenshot-n.png:   the original screenshot.
    screenshot-n.svg:   the working file.
    slide-n.png:        the final output file.
    _build/html/slide-n.html: the final slide.

</t>
<t tx="ekr.20101113063552.9476"></t>
<t tx="ekr.20101113063552.9477">Manages BibTeX files with Leo.

Create a bibliographic database by
putting '@bibtex filename' in a headline. Entries are added as nodes, with
'@entrytype key' as the headline, and the contents of the entry in body text.
The plugin will automatically insert a template for the entry in the body pane
when a new entry is created (hooked to pressing enter when typing the headline
text). The templates are defined in dictionary 'templates' in the \&lt;\&lt;globals\&gt;\&gt;
section, by default containing all required fields for every entry.

The file is written by double-clicking the node. Thus the following outline::

    -@bibtex biblio.bib
     +@book key
      author = {A. Uthor},
      year = 1999

will be written in the file 'biblio.bib' as::

    @book{key,
    author = {A. Uthor},
    year= 1999}

Strings are defined in @string nodes and they can contain multiple entries.
All @string nodes are written at the start of the file. Thus the following
outline::

    -@bibtext biblio.bib
     +@string
      j1 = {Journal1}
     +@article AUj1
      author = {A. Uthor},
      journal = j1
     +@string
      j2 = {Journal2}
      j3 = {Journal3}

Will be written as::

    @string{j1 = {Journal1}}
    @string{j2 = {Journal2}}
    @string{j3 = {Journal3}}

    @article{AUj1,
    author = {A. Uthor},
    journal = j1}

No error checking is made on the syntax. The entries can be organized under
nodes --- if the headline doesn't start with '@', the headline and body text are
ignored, but the child nodes are parsed as usual.

BibTeX files can be imported by creating an empty node with '@bibtex filename'
in the headline. Double-clicking it will read the file 'filename' and parse it
into a @bibtex tree. No syntax checking is made, 'filename' is expected to be a
valid BibTeX file.

</t>
<t tx="ekr.20101113063552.9478">Sends code to the doctest module and reports the result.

When the Dtest plugin is enabled, the ``dtest`` command is active.
Typing:: 

    Alt-X dtest

will run doctest on a file consisting of the current node and it's children.
If text is selected only the selection is tested.

From Wikipedia::

    'Doctest' is a module included in the Python programming language's 
    standard library that allows for easy generation of tests based on 
    output from the standard Python interpreter.

http://tinyurl.com/cqh53 - Python.org doctest page    

http://tinyurl.com/pxhlq - Jim Fulton's presentation::

    Literate Testing:
    Automated Testing with doctest

</t>
<t tx="ekr.20101113063552.9480">Outputs a Leo outline as a numbered list to an RTF file. The RTF file can be
loaded into Microsoft Word and formatted as a proper outline.

If this plug-in loads properly, you should have an "Outline to Microsoft RTF"
option added to your File &gt; Export... menu in Leo.

Settings such as outputting just the headlines (vs. headlines &amp; body text) and whether
to include or ignore the contents of @file nodes are stored in the rtf_export.ini file
in your Leo\plugins folder.

The default export path is also stored in the INI file. By default, it's set to c:\ so
you may need to modify it depending on your system.

</t>
<t tx="ekr.20101113063552.9482"></t>
<t tx="ekr.20101113063552.9483">Supports Uniform Node Locators (UNL's) for linking to nodes in any Leo file.

UNL's specify nodes within any Leo file. You can use them to create
cross-Leo-file links! UNL

This plugin consists of two parts:

1) Selecting a node shows the UNL in the status line at the bottom of the Leo
   window. You can copy from the status line and paste it into headlines, emails,
   whatever. 

2) Double-clicking @url nodes containing UNL's select the node specified in the
   UNL. If the UNL species in another Leo file, the other file will be opened.

Format of UNL's:

UNL's referring to nodes within the present outline have the form::

    headline1--&gt;headline2--&gt;...--&gt;headlineN

headline1 is the headline of a top-level node, and each successive headline is
the headline of a child node.

UNL's of the form::

    file:&lt;path&gt;#headline1--&gt;...--&gt;headlineN

refer to a node specified in &lt;path&gt; For example, double clicking the following
headline will take you to Chapter 8 of Leo's Users Guide::

    @url file:c:/prog/leoCvs/leo/doc/leoDocs.leo#Users Guide--&gt;Chapter 8: Customizing Leo

For example, suppose you want to email someone with comments about a Leo file.
Create a comments.leo file containing @url UNL nodes. That is, headlines are
@url followed by a UNL. The body text contains your comments about the nodes in
the _other_ Leo file! Send the comments.leo to your friend, who can use the
comments.leo file to quickly navigate to the various nodes you are talking
about. As another example, you can copy UNL's into emails. The recipient can
navigate to the nodes 'by hand' by following the arrows in the UNL.

**Notes**:

- At present, UNL's refer to nodes by their position in the outline. Moving a
  node will break the link.

- Don't refer to nodes that contain UNL's in the headline. Instead, refer to the
  parent or child of such nodes.

- You don't have to replace spaces in URL's or UNL's by '%20'.

</t>
<t tx="ekr.20101113063552.9484">Creates hoist buttons.

This plugin puts two buttons in the icon area: a button called 'Save Hoist' and
a button called 'Dehoist'. The 'Save Hoist' button hoists the presently selected
node and creates a button which can later rehoist the same node. The 'Dehoist'
button performs one level of dehoisting

Requires at least version 0.19 of mod_scripting.

</t>
<t tx="ekr.20101113063552.9485">Colorizes URLs everywhere in node's body on node selection or saving. Double
click on any URL launches it in default browser.

URL regex:  (http|https|file|ftp)://[^\s'"]+[\w=/]

Related plugins:  color_markup.py; rClick.py

</t>
<t tx="ekr.20101113063552.9486">Lets the user to associate text with a specific node.

Summon it by pressing button-2 or button-3 on an icon Box in the outline. This
will create an attribute editor where the user can add, remove and edit
attributes. Since attributes use the underlying tnode, clones will share the
attributes of one another.

</t>
<t tx="ekr.20101113063552.9487">Adds buttons so Leo can interact with command line environments.

:20100226: see also leoscreen.py for a simpler approach.

Currently implements `bash` shell and `psql` (postresql SQL db shell).

Single-line commands can be entered in the headline with a blank body,
multi-line commands can be entered in the body with a descriptive
title in the headline.  Press the `bash` or `psql` button to send
the command to the appropriate interpreter.

The output from the command is **always** stored in a new node added
as the first child of the command node.  For multi-line commands
this new node is selected.  For single-line command this new node
is not shown, instead the body text of the command node is updated
to reflect the most recent output.  Comment delimiter magic is used
to allow single-line and multi-line commands to maintain their
single-line and multi-line flavors.

Both the new child nodes and the updated body text of single-line
commands are timestamped.

For the `bash` button the execution directory is either the directory
containing the `.leo` file, or any other path as specified by ancestor
`@path` nodes.

Currently the `psql` button just connects to the default database.  ";"
is required at the end of SQL statements.

Requires `pexpect` module.

</t>
<t tx="ekr.20101113063552.9488">Maximizes all new windows.

</t>
<t tx="ekr.20101113063552.9489">Sets a hard coded frame size.

Prevents Leo from setting custom frame size (e.g. from an external .leo
document)

</t>
<t tx="ekr.20101113063552.9491">Sends all output to the log pane.

</t>
<t tx="ekr.20101113063552.9492">Creates a Scripts menu for LeoPy.leo.

</t>
<t tx="ekr.20101113063552.9493">Replaces the gui file dialogs on Linux with external
calls to the zenity gtk dialog package.

This plugin is more a proof of concept demo than
a useful tool.  The dialogs presented do not take
filters and starting folders can not be specified.

Despite this, some Linux users might prefer it to the
gui dialogs.

</t>
<t tx="ekr.20101113063552.9528" str_atime="1376413521.0"></t>
<t tx="ekr.20101113063552.9794" str_atime="1376412861.0">Creates a Plugins menu and adds all actives plugins to it.

Selecting these menu items will bring up a short **About Plugin** dialog
with the details of the plugin. In some circumstances a submenu will be created
instead and an 'About' menu entry will be created in this.

**INI files and the Properties Dialog**

If a file exists in the plugins directory with the same file name as the plugin
but with a .ini extension instead of .py, then a **Properties** item will be
created in a submenu. Selecting this item will pop up a Properties Dialog which
will allow the contents of this file to be edited.

The .ini file should be formated for use by the python ConfigParser class.

**Special Methods**

Certain methods defined at the top level are considered special.

cmd_XZY
    If a method is defined at the module level with a name of the form
    **cmd_XZY** then a menu item **XZY** will be created which will invoke
    **cmd_XZY** when it is selected. These menus will appear in a sub menu.

applyConfiguration

topLevelMenu
    This method, if it exists, will be called when the user clicks on the plugin
    name in the plugins menu (or the **About** item in its submenu), but only if
    the plugin was loaded properly and registered with g.plugin_signon.

**Special Variable Names**

Some names defined at the top level have special significance.

__plugin_name__
    This will be used to define the name of the plugin and will be used
    as a label for its menu entry.

__plugin_priority__
    Plugins can also attempt to select the order they will appear in the menu by
    defining a __plugin_prioriy__. The menu will be created with the highest
    priority items first. This behavior is not guaranteed since other plugins
    can define any priority. This priority does not affect the order of calling
    handlers.
    To change the order select a number outside the range 0-200 since this range
    is used internally for sorting alphabetically. Properties and INI files.

</t>
<t tx="ekr.20101113063552.9798">Allows the definition of double-click actions.

When the user double-clicks a node this plugin checks for a match of the clicked
node's headline text with a list of patterns. If a match occurs, the plugin
executes the associated script.

**nodeAction** nodes may be located anywhere in the outline. Such nodes should
contain one or more **pattern nodes** as children. The headline of each pattern
node contains the pattern; the body text contains the script to be executed when
the pattern matches the double-clicked node.

For example, the "nodeActions" node containing a "launch URL" pattern node
and a "pre-process python code" node could be placed under an "@settings"
node::

   @settings
   |
   +- nodeActions
      |
      +- http:\\*
      |
      +- @file *.py

**Configuration**

The nodeActions plugin supports the following global configurations using
Leo's support for setting global variables within an @settings node's
sub-nodes in the leoSettings.leo, myLeoSettings.leo, and the project Leo
file:

@bool nodeActions_save_atFile_nodes = False

  :True:
     Double-click on an @file type node will save the file to disk
     before executing the script.

  :False:
     Double-click on an @file type node will **not** save the file to disk
     before executing the script. (default)

@int nodeActions_message_level = 1

  Specifies the type of messages to be sent to the log pane.  Specifying a
  higher message level will display that level and all lower levels.
  The following integer values are supported::

    0 no messages
    1 Plugin triggered and the patterns that were matched (default)
    2 Double-click event passed or not to next plugin
    3 Patterns that did not match
    4 Code debugging messages

**Patterns**

Pattern matching is performed using python's support for Unix
shell-style patterns unless overwritten by the "X" pattern directive.
The following pattern elements are supported::

    *           matches everything
    ?           matches any single character
    [&lt;seq&gt;]     matches any character in &lt;seq&gt;
    [!&lt;seq&gt;]    matches any character **not** in &lt;seq&gt;

Unix shell-style pattern matching is case insensitive and always starts from
the beginning of the headline.  For example:

     ======= =========== ==============
     Pattern   Matches   Does not match
     ======= =========== ==============
     \*.py   Abc_Test.py
     .py     .py - Test  Abc_Test.py
     test*   Test_Abc.py Abc_Test.py
     ======= =========== ==============

To enable a script to run on any type of @file node (@thin, @shadow, ...),
the pattern can start with "@files" to match on any
external file type.  For example, the pattern "@files \*.py" will
match a node with the headline "@file abcd.py".

The headline of the double-clicked node is matched against the patterns
starting from the first sub-node under the "nodeActions" node to the last
sub-node.

Only the script associated with the first matching pattern is
invoked unless overwritten by the "V" pattern directive.

Using the "V" pattern directive allows a broad pattern such
as "@files \*.py" to be invoked, and then, by placing a more restrictive
pattern above it, such as "@files \*_test.py", a different script can be
executed for those files requiring pre-processing::

  +- nodeActions
     |
     +- @files *_test.py
     |
     +- @files *.py

**Note**: To prevent Leo from trying to save patterns that begin with a derived
file directive (@file, @auto, ...) to disk, such as "@file \*.py", place the
"@ignore" directive in the body of the "nodeActions" node.

Pattern nodes can be placed at any level under the "nodeActions" node.
Only nodes with no child nodes are considered pattern nodes.
This allows patterns that are to be used in multiple Leo files to be read
from a file.  For example, the following structure reads the pattern
definition from the "C:\\Leo\\nodeActions_Patterns.txt" file::

    +- nodeActions
    |
    +- @files C:\\Leo\\nodeActions_Patterns.txt
        |
        +- http:\\*
        |
        +- @file *.py

**Pattern directives**

The following pattern specific directives can be appended to the end of a
pattern (do not include the ':'):

:[X]:
  Use python's regular expression type patterns instead of the Unix
  shell-style pattern syntax.

  For example, the following patterns will match the same headline string::

     Unix shell-style pattern:
        @files *.py

     Regular Expression pattern:
        ^@files .*\.py$ [X]

:[V]:
  Matching the pattern will not block the double-click event from
  being passed to the remaining patterns.
  The "V" represents a down arrow that symbolizes the passing of the event
  to the next pattern below it.

  For example, adding the "[V]" directive to the "@files \*_test.py" in
  the Patterns section above, changes its script from being 'an
  alternate to' to being 'a pre-processor for' the "@files \*.py" script::

     +- nodeActions
        |
        +- @files *_test.py [V]
        |
        +- @files *.py

:[&gt;]:
  Matching the pattern will not block the double-click event from being
  passed to other plugins.
  The "&gt;" represents a right arrow that
  symbolizes the passing of the event to the next plugin.

  If the headline matched more than one headline,
  the double-click event will be passed to the next plugin if the
  directive is associated with any of the matched patterns.

The directive(s) for a pattern must be contained within a single set of
brackets, separated from the pattern by a space, with or without a comma
separator.  For example, the following specifies all three directives::

  ^@files .*\.py$ [X,V&gt;]

**Scripts**

The script for a pattern is located in the body of the pattern's node.
The following global variables are available to the script::

    c
    g
    pClicked - node position of the double-clicked node
    pScript - node position of the invoked script

**Examples**

Double-clicking on a node with a "http:\\\\www.google.com" headline
will invoke the script associated with the
"http:\\\\\*" pattern.  The following script in the body of the pattern's
node displays the URL in a browser::

     import webbrowser
     hClicked = pClicked.h     #Clicked node's Headline text
     webbrowser.open(hClicked) #Invoke browser

The following script can be placed in the body of a pattern's node to
execute a command in the first line of the body of a double-clicked node::

     g.os.system('"Start /b ' + pClicked.bodyString() + '"')
</t>
<t tx="ekr.20101113063552.9800">Converts a leo outline to an html web page.

This plugin takes an outline stored in LEO and converts it to html which is then
either saved in a file or shown in a browser. It is based on the original
leoToHTML 1.0 plugin by Dan Rahmel which had bullet list code by Mike Crowe.

The outline can be represented as a bullet list, a numbered list or using html
&lt;h?&gt; type headings. Optionally, the body text may be included in the output.

If desired, only the current node will be included in the output rather than
the entire outline.

An xhtml header may be included in the output, in which case the code will be
valid XHTML 1.0 Strict.

The plugin is fully scriptable as all its functionality is available through a
Leo_to_HTML object which can be imported and used in scripts.

**Menu items and @settings**

If this plugin loads properly, the following menu items should appear in
your File &gt; Export... menu in Leo::

    Save Outline as HTML  (equivalent to export-html)
    Save Node as HTML     (equivalent to export-html-node)
    Show Outline as HTML  (equivalent to show-html)
    Show Node as HTML     (equivalent to show-html-node)

*Unless* the following appears in an @setting tree::

    @bool leo_to_html_no_menus = True

in which case the menus will **not** be created. This is so that the user can
use @menu and @item to decide which commands will appear in the menu and where.

**Commands**

Several commands will also be made available

export-html
  will export to a file according to current settings.
export-html-*
  will export to a file using bullet type '*' which can be
  **number**, **bullet** or **head**.

The following commands will start a browser showing the html.

show-html
  will show the outline according to current settings.

show-html-*
  will show the outline using bullet type '*' which can be
  **number**, **bullet** or **head**.

The following commands are the same as above except only the current node is converted::

    export-html-node
    export-html-node-*
    show-html-node
    show-html-node-*

**Properties**

There are several settings that can appear in the leo_to_html.ini properties
file in leo's plugins folder or be set via the Plugins &gt; leo_to_html &gt;
Properties... menu. These are:

exportpath:
    The path to the folder where you want to store the generated html file.
    Default: c:\\

flagjustheadlines:
    Default: 'Yes' to include only headlines in the output.

flagignorefiles:
    Default: 'Yes' to ignore @file nodes.

use_xhtml:
    Yes to include xhtml doctype declarations and make the file valid XHTML 1.0 Strict.
    Otherwise only a simple &lt;html&gt; tag is used although the output will be xhtml
    compliant otherwise. Default: Yes

bullet_type:
    If this is 'bullet' then the output will be in the form of a bulleted list.
    If this is 'number' then the output will be in the form of a numbered list.
    If this is 'heading' then the output will use &lt;h?&gt; style headers.

    Anything else will result in &lt;h?&gt; type tags being used where '?' will be a
    digit starting at 1 and increasing up to a maximum of six depending on depth
    of nesting. Default: number

browser_command:
    Set this to the command needed to launch a browser on your system or leave it blank
    to use your systems default browser.

    If this is an empty string or the browser can not be launched using this command then
    python's `webbrowser` module will be tried. Using a bad command here will slow down the
    launch of the default browser, better to leave it blank.
    Default: empty string

**Configuration**

At present, the file leo/plugins/leo_to_html.ini contains configuration
settings. In particular, the default export path, "c:\" must be changed for \*nix
systems.

</t>
<t tx="ekr.20101115152915.4937">@nocolor-node

{{Infobox software
| name = Leo: Leonine Editor with Outlines
| screenshot = [http://sourceforge.net/project/screenshots.php?group_id=3458&amp;ssid=22298 Screenshots]
| caption =
| developer = Edward K. Ream
| latest_release_version = 4.8 release candidate 1
| latest_release_date = {{release date and age|2010|11|15}}
| operating_system = [[Cross-platform]]
| genre = [[Text editor]], [[Outliner]], [[Integrated development environment|IDE]]
| license = [[Python (programming language)|Python]] License
| website = http://leoeditor.com
}}

'''Leo''' ('''L'''eonine '''E'''ditor with '''O'''utlines) is a [[text editor]]
that features [[outliner|outlines]] with clones as its central tool of
organization, navigation, customization and scripting.

==Language==

Leo is written in [[Python (programming language)|Python]] and uses the [[Qt
(toolkit)|Qt]]. It is fully scriptable using Python and can be extended with
plugins. In Leo, outlines are hierarchical data structures that people use to
work with and manage text files—including code.

==Trees, clones and views==

Leo is an [[outliner]]. Leo's outline pane shows a [[tree (data structure)]] of data nodes.
Nodes contain headlines, body text, and other information.
Headlines naturally serve as descriptions of the body text.
For example, @file nodes are nodes whose headline starts with @file.

Leo trees are in fact [[directed acyclic graph|directed acyclic graphs]];
nodes may have more than one parent.
Leo calls such nodes clones.
Clones appear in several places in the outline pane.

Views are simply nodes whose children contain clones. A single outline may contain
arbitrarily many views of the nodes contained therein.
Views and clones turn Leo into a supremely flexible filing cabinet: any node may be filed
in arbitrarily many places.
&lt;ref&gt;[http://leoeditor.com/nutshell.html Leo documentation: Leo in a Nutshell]&lt;/ref&gt;

==External files==

@file nodes represent external files, files on the computer's file system.
When saving an outline Leo automatically writes all changed @file
trees back to the external files.
Comments, called sentinel lines, in external files represent the outline structure.
When reading an outline, these comments allows Leo to recreate
@file trees using only the data in the external file.

@auto nodes represent external files without using sentinel comments.
When reading @auto nodes, Leo uses the program structure of the external file
to create the @auto tree.

==Scripting==

Leo's scripting environment takes full advantage of outline structure:

* The body text of any node may contain a Leo script, a Python script executed in the context of a Leo outline.

* A simple [[API]] &lt;ref&gt;[http://leoeditor.com/scripting.html Leo documentation: Scripting Leo with Python]&lt;/ref&gt; gives Leo scripts full access to all data in loaded outlines, as well as full access to Leo's own source code. The API includes Python [[iterators]] that allow scripts to traverse outlines easily.

* Scripts may be composed of any tree of nodes.
  A [[markup language]] similar to [[noweb]] &lt;ref&gt;[http://leoeditor.com/tutorial.html#section-references Leo documentation: Tutorial]&lt;/ref&gt; tells Leo how to create scripts from (parts of) an outline.

* Headlines naturally control and guide scripts.

** @test nodes represent unit tests. Leo can execute the body of an @test node as unit test, without the body having to create an explicit subclass of Python's UnitTest.TestCase class. &lt;ref&gt;[

** @button nodes contain scripts that can be applied to other nodes.  In effect, @button nodes create user-defined commands. &lt;ref&gt;

==External links==
{{Portal|Free software}}
*[http://leoeditor.com Leo's homepage]
*[http://sourceforge.net/projects/leo/ Leo at SourceForge],[http://sourceforge.net/project/screenshots.php?group_id=3458&amp;ssid=22298 screenshots]
*[http://groups.google.com/group/leo-editor leo-editor Google Group]
*{{cite web | title=Literate Programming and Leo | publisher = [[Slashdot]] | date=2002-08-28 | url=http://developers.slashdot.org/article.pl?sid=02/08/28/1655207 }}
*{{cite web |author=[[James Tauber]] |title=Using the Leo Outliner as a PIM | date=2004-05-15 |url=http://jtauber.com/blog/2004/05/15/using_the_leo_outliner_as_a_pim/ }}
*{{cite book | author = Vreda Pieterse, Derrick G. Kourie, Andrew Boake | title=ACM International Conference Proceeding Series; Vol. 75. Proceedings of the 2004 annual research conference of the South African institute of computer scientists and information technologists on IT research in developing countries | chapter=A case for contemporary literate programming | editor=[[Association for Computing Machinery|ACM]] | pages=2–9 | url=http://portal.acm.org/citation.cfm?id=1035054}} (cited in references)

==References==
&lt;references/&gt;

{{DEFAULTSORT:Leo (Text Editor)}}
[[Category:Free text editors]]
[[Category:Free software programmed in Python]]
[[Category:Outliners]]
</t>
<t tx="ekr.20101124083644.5052">Autocompletion reminds you of all members (functions, methods, ivars, etc.)
contained in objects in Leo's source code, and in Python's standard library
modules.

Alt-1 (toggle-autocompleter) enables and disables autocompletion. **Note**:
Autocompletion can be enabled only when @language python is in effect.

For example, typing just "c.atF" (in the body pane, with autocompletion
enabled) automatically inserts "c.atFileCommands" into the body pane,
because "c.atFileCommands" is the only possible completion of "c.atF".

As another example, typing "at.writeA" will show (in an autocompleter tab in the Log pane)
all of the write commands in leoAtFile.py::

    writeAll:method
    writeAllHelper:method
    writeAtAutoNodes:method
    writeAtAutoNodesHelper:method
    writeAtShadowNodes:method
    writeAtShadowNodesHelper:method

When a single completion is shown, typing '?' will show the docstring for a method::
For example, "c.atFileCommands.write?" shows::

    Write a 4.x derived file.
    root is the position of an @&lt;file&gt; node
</t>
<t tx="ekr.20101125062332.5090">Leo requires the `Python`_ and `PyQt_` package.
The `PyEnchant`_ package is optional. 

**Python**: Leo will work on any platform that supports Python 2.6 or
above, including Python 3.0 and above. To install Python, see
http://python.org.

**PyQt**: PyQt provides Leo's widgets. To install PyQt, get the binary
package from: http://www.riverbankcomputing.co.uk/software/pyqt/download
The PyQt version must match your installed Python version. Remember that
Leo requires Python 2.6 or later, or Python 3.0 or later. Now run the
binary PyQt installer.

**PyEnchant**: You must install the PyEnchant package if you want to use
Leo's Spell tab. Download and install the PyEnchant package from
http://pythonhosted.org/pyenchant/download.html There is an executable
installer for Windows users.

</t>
<t tx="ekr.20110521135104.18151">@language rest 

Cross-file clones are cloned nodes in one outline that refer to data in another
outline. This is a frequently requested feature. For example::

    I would absolutely love to have the leo files in different project
    directories, and a "master" leo file to rule them all.

However, cross-file clones will never be a part of Leo. Indeed, cross-file
clones would violate the principle that data should be defined and managed in
exactly one place. Just as human managers would not willingly accept shared
responsibility for even a single line of code, every piece of Leonine data
should be the responsibility of one and *only* one .leo file.

The problem fundamental. If the *same* (cloned) data were "owned" by two
different Leo files we would have a classic "multiple update problem" for the
data. Each outline could change the data in incompatible ways, and whichever
outline changed the data last would "win."

To make such a scheme workable and safe, one would have to devise a scheme that
would keep the data in "component" .leo files consistent even when the component
.leo files changed "randomly", without the "master" .leo file being in *any* way
in "control" of the changes. Good luck :-)

Let us be clear: it's no good having a scheme that works *most* of the time, it
must work *all* the time, even with unexpected or even pathological file
updates. If it doesn't you are asking for, and will eventually get, catastrophic
data loss, without being aware of the loss for an arbitrarily long period of
time. Even with a source code control system this would be an intolerable
situation.
</t>
<t tx="ekr.20110531155858.20559">.. _`This FAQ entry`: FAQ.html#how-can-i-use-leo-to-develop-leo-itself

Here is the workflow I use to develop Leo. The intention is to help
present and potential developers use Leo effectively.

Overview
========

- Develop in an outline containing all of Leo's source files. Close this outline
  rarely: this keeps the code I am using stable while I'm hacking the code.

- Test in a *separate* .leo file, say test.leo. In fact, I often test in a
  private file, ekr.leo, so that test.leo doesn't get continually updated on bzr
  with trivial changes.

These two points are covered in a bit more detail in `This FAQ entry`_.

Additional tips
===============

A. Avoid using the mouse whenever possible. For example, use alt-tab to switch
between windows.

B. Always develop Leo in a console. This allows you to see the output of g.trace.

Speaking of g.trace, I hardly ever use 'print' because g.trace prints the name
of the function or method in which it appears. The typical pattern for enabling
traces is::

    trace = True and not g.unitTesting
    if trace: g.trace(whatever)

This pattern is especially useful when a method contains multiple calls to
g.trace.

C. I use scripts to open particular Leo files. These are batch files on Windows,
   and aliases on Linux, but invoking them is the same on either platform::

    all:     opens all my main development files using the qt-tabs gui.
    t:       opens test.leo.
    e:       opens ekr.leo.  I use this file for private testing.
    d:       opens LeoDocs.leo.
    s:       opens LeoPy.leo.
    plugins: opens leoPlugins.leo.
    gui:     opens leoGui.leo.
    u:       opens unitTest.leo.

  These run Leo with Python 3.x. There are similar scripts, ending in 2, that run
  Leo with Python 2.x. For example, u2 opens unitTest.leo with Python 2.x.
  Thus, to run a test, I alt-tab to an available console window, then type 'e' or
  't' or 'u' or, if I want Python 2.x, 'e2' or 't2' or 'u2'.

D. Use clones to focus attention on the task at hand.
   For more details, see the tutorial's introduction to `clones`_.

E. For thousand of example of my programming style, see leoPy.leo and
   leoGuiPlugins.leo. The projects section in leoPy.leo contains many examples
   of using clones to create view nodes. I typically delete the clones in the
   views shortly before a release.

Writing documentation
=====================

- Use postings as pre-writing for documentation.

  I don't mind blabbing on and on about Leo because all my posts become
  pre-writing for Leo's documentation. I simply copy posts to nodes in the
  "documentation to-do" section. At release time, I edit these nodes and put
  them in Leo's main documentation or the release notes. This posting is an
  example.
  
- Use the vr command to debug reStructuredText documentation. The viewrendered
   pane updates as you type. This makes Leo a killer app for rST.
   
Administrative tips
===================

- Never rely on memory.

   A project like this contains thousands and thousands of details. Everything
   eventually goes into a Leo node somewhere. If it doesn't it surely *will* be
   forgotten.

- Do easy items first.
   
   This keeps to-do lists short, which keeps energy high.

Tips for using bzr
==================

I use the following batch files related to bzr::

    b:      short for bzr
    b c:    short for bzr commit
    bs:     short for bzr status
    tr:     short for cd &lt;path to trunk&gt;
    main:   short for cd &lt;path to copy of trunk&gt;

The "main" (copy) of the trunk is purely for handling bzr conflicts.
If one happens I do this::

    main
    b pull
    b merge ../trunk
    b c -m "my commit message"
    b push

If the merge goes well (it usually does), I do this to resolve the conflict::

    tr
    b pull
</t>
<t tx="ekr.20110531155858.20563">The following script will create a minimal Leo outline::

    if 1:
        # Create a visible frame.
        c2 = g.app.newCommander(fileName=None)
    else:
        # Create an invisible frame.
        c2 = g.app.newCommander(fileName=None,gui=g.app.nullGui)

    c2.frame.createFirstTreeNode()
    c2.redraw()
    
    # Test that the script works.
    for p in c2.all_positions():
        g.es(p.h)
</t>
<t tx="ekr.20110531155858.20564">You set most colors in the following settings node::

    @data qt-gui-plugin-style-sheet
    
However, settings for colors that can change during Leo's execution
are found in the node::

    Body pane colors
    
These settings are as follows, with the defaults as shown::
    

    \@color body_cursor_background_color = None
    \@color body_cursor_foreground_color = None
    \@color body_insertion_cursor_color = None
    \@color body_text_background_color = None
    \@color body_text_foreground_color = None
    \@color command_mode_bg_color = #f2fdff&lt;/vh&gt;&lt;/v&gt;
    \@color command_mode_fg_color = None&lt;/vh&gt;&lt;/v&gt;
    \@color insert_mode_bg_color = #fdf5f5&lt;/vh&gt;&lt;/v&gt;
    \@color insert_mode_fg_color = black&lt;/vh&gt;&lt;/v&gt;
    \@color overwrite_mode_bg_color = azure2&lt;/vh&gt;&lt;/v&gt;
    \@color overwrite_mode_fg_color = black&lt;/vh&gt;&lt;/v&gt;
    \@color unselected_body_bg_color = #ffffef&lt;/vh&gt;&lt;/v&gt;
    \@color unselected_body_fg_color = black&lt;/vh&gt;&lt;/v&gt;
</t>
<t tx="ekr.20110601105631.19349">@language rest

</t>
<t tx="ekr.20110601105631.19360">- Fixed an important bug involving orphan nodes. Leo now never saves an external
  file containing orphan nodes. This ensures that all the information in the
  external file will, in fact, be saved in the .leo file.

- Almost 40 minor bugs have been fixed. For details, see the release notes.

- Fixed mod_http plugin
  
</t>
<t tx="ekr.20110601105631.19434"></t>
<t tx="ekr.20110601105631.19435">- Support multiple @language directives in a single node
  As with @color directives, only unambiguous @language directives affect the
  default coloring of descendant nodes.

- Colorize url's in the body text. You can open url's by control-clicking on
  them, or by using the open-url command.

- Added support for cython colorizing

- Leo ignores (and does not color) @language directive for unknown languages.

- Leo completely recolors nodes when you change @language directives by typing.
</t>
<t tx="ekr.20110601105631.19441">- If you type a *plain* up/down arrow key while editing a headline, Leo will act
  as if you had typed the corresponding *alt*- arrow key. That is, Leo will end
  editing of the headline and go to the next previous node. Leo will end editing
  even if there is no next/ previous node, which is convenient.

- A single click on an already-selected tree node edits the headline

  Enabled only if @bool single_click_auto_edits_headline = True.

- Added a splash screen

  The --no-splash command-line option suppresses the splash screen. In addition,
  Leo puts up no splash screen when the --silent or --script command-line
  options are given. To change the splash screen, replace
  leo\Icons\SplashScreen.jpg with another image.

- The apropos commands now print in a separate area if possible. The commands use
  the scrolledmessage plugin if possible, which in turn uses the viewrendered
  plugin by default. This makes the apropos messages much more visible.

- Handle click events like alt-x or ctrl-g Clicking in the minibuffer now is
  equivalent to alt-x, provided that the minibuffer is not in use. Clicking most
  places outside the minibuffer is equivalent to ctrl-g. Catching clicks is much
  safer than catching focus events.

- The first loaded file sets tabbed gui size

- Enter insert mode after ctrl-h.  This is a vim-related improvement.

- Disabled find/change text areas in find panel.  This reduces confusion.
</t>
<t tx="ekr.20110601105631.19463">- Added the replace-current-character command. It replaces the character to the
  left of the cursor, or replaces the selection range if there is one.

- Added toggle-case-region command.

- Added save-all command. It saves all changed windows.

- Added insert-hard/soft-tab commands.

- Added commands to manage uA's::

    clear-all-uas
    clear-node-uas
    print-all-uas
    print-node-uas
    set-ua
    
- Renamed the 'abbrev-mode' to 'toggle-abbrev-mode'.
</t>
<t tx="ekr.20110601105631.19464">- Added namespace and Leo comment lines to .leo files

- Leo opens leoSettings.leo only once

- Fixed Bug 745824: @doc duplicates comment delims in html files
  https://bugs.launchpad.net/leo-editor/+bug/745824e
  
- Leo no longer wraps @doc lines. This ensures that Leo does not change files
  unnecessarily.
</t>
<t tx="ekr.20110601105631.19473">.. _`Runwith class`: http://groups.google.com/group/leo-editor/browse_thread/thread/b8e8fbf6d97fa9f2/a4537fafaf2442ba

- Added namespace arg in c.executeScript

- Put Kent Tenney's `Runwith class`_ in scripts.leo and contrib.

  Kent writes, "I've had endless problems with interpreter versioning, leading
  me create the Runwith class. It writes a file to disk, makes it executable,
  runs it, captures exitcode, err and output, removes the files, provides
  reports. This provides complete decoupling from Leo."

- Call os.chdir when executing scripts.
</t>
<t tx="ekr.20110601105631.19480">- The --no-splash command-line option suppresses the splash screen.
  Leo puts up no splash screen when the --silent
  or --script command-line options are given.

- Added @bool view-rendered-auto-create setting.
    
- Added @bool use_qcompleter setting.

- Added auto_tab_complete setting.

- Removed @bool use_codewise setting.

- You now may set icon button colors in the Qt stylesheet.

</t>
<t tx="ekr.20110601105631.19481">- Support multiple @language directives in a single node
  As with @color directives, only unambiguous @language directives affect the
  default coloring of descendant nodes.

- Colorize url's in the body text. You can open url's by control-clicking on
  them, or by using the open-url command.

- Use @file extension by default if there is no @language directive in effect.
  This is oh so useful.

- Unified extract commands.  This command creates a child node from the selected
  body text as follows:
    
    1. If the selection starts with a section reference, the section name become the
       child's headline. All following lines become the child's body text. The
       section reference line remains in the original body text.
       
    2. If the selection looks like a Python class or definition line, the
       class/function/method name becomes child's headline and all selected lines
       become the child's body text.
       
    3. Otherwise, the first line becomes the child's headline, and all selected
       lines become the child's body text.

    Note that the extract-section-names command remains.
    The extract-section and extract-python-method commands are gone.

- The import-file commands replaces all the following commands::
    
    import-at-file                    
    import-cweb-files         
    import-derived-file       
    import-flattened-outline      
    import-noweb-files
    
  Leo chooses one of the above commands as follows.  First, if the file looks
  like an external file that Leo wrote, the command works like
  import-derived-file command.  Otherwise, the file's extension determines the
  importer::
        
        .cw, .cweb:     import-cweb-files
        .nw, .noweb:    import-noweb-files
        .txt:           import-flattened-outline
        all others:     import-at-file
    
  The import-at-root command is no longer supported.
</t>
<t tx="ekr.20110601105631.19482">- Improved the clone-find-all command. The descendants of previously found
  (cloned) nodes don't get added again. The clone-find-all pattern now defaults
  to find text.

- Improved the forward and backward by sentences commands Leo's sentence related
  functions now stop at empty lines, skip periods within words, stop at
  sentences ending in non-periods and stop at the end or beginning of the
  buffer.

- Improved the print-bindings command; it now shows were bindings came from.

- Improved the reformat-paragraph command. The command detects paragraphs more
  reliably. The next line is now visible, which is a big improvement.

- Added patch to g.wrap_lines from José Rojas Echenique
  It regularizes the number of spaces after periods.

- Improved expansion of abbreviations. Abbreviations are checked any time a
  non-word character is typed. In particular, newlines trigger abbreviations,
  which I find very helpful, although I did then have to remove newlines from my
  abbreviations. Control sequences do not trigger expansions.

- Improved handling of @url nodes. The new rule is simple: if the body text
  contains any text the first line of the body text is taken to be the url.
  There is no longer any need to put '--' in the headline. More importantly, you
  can put anything you like in the body text following the first line. Other
  url's, notes, even .. graphics:: directives for the viewrendered plugin.

- Improved the clean-all-lines command. It is now much faster and has better
  feedback.
</t>
<t tx="ekr.20110601105631.19484">- Leo no longer supports the Tk gui. The Qt gui now does everything
  the Tk gui did and better.

- Removed show/hide/toggle minibuffer commands. The minibuffer is an essential
  part of Leo.
  
- These settings are no longer used::
    
    @string selected-background-color
    @string selected-command-background-color
    
- The import-at-root command is no longer supported.
</t>
<t tx="ekr.20110602091552.16898">The viewrendered plugin creates a window for *live* rendering of images, movies,
sounds, rst, html, etc. 

Commands
========

viewrendered.py creates the following (``Alt-X``) commands:

``viewrendered (abbreviated vr)``
    Opens a new rendering window.
    
    By default, the rendering pane renders body text as reStructuredText, with
    all Leo directives removed. However, if the body text starts with ``&lt;``
    (after removing directives), the body text is rendered as html.
    
    **Important**: The default rendering just described does not apply to nodes
    whose headlines begin with @image, @html, @movie, @networkx, @svg and @url.
    See the section called **Special Renderings** below.

    Rendering sets the process current directory (os.chdir()) to the path
    to the node being rendered, to allow relative paths to work in ``.. image::`` directives.

``hide-rendering-pane``
    Makes the rendering pane invisible, but does not destroy it.

``lock-unlock-rendering-pane``
    Toggles the locked state of the rendering pane. When unlocked (the initial
    state), the rendering pane renders the contents of the presently selected
    node. When locked, the rendering pane does not change when other nodes are
    selected. This is useful for playing movies in the rendering pane.
    
``pause-play-movie``
    This command has effect only if the rendering pane is presently showing a movie.
    It pauses the movie if playing, or resumes the movie if paused.

``show-rendering-pane``
    Makes the rendering pane visible.

``toggle-rendering-pane``
    Shows the rendering pane if invisible, otherwise hides it.
    
``update-rendering-pane``
    Forces an update of the rendering pane. This is especially useful for
    @graphics-script nodes: such nodes are update automatically only when
    selected, not when the body text changes.
    
Rendering reStructuredText
==========================

For example, both::

    Heading
    -------

    `This` is **really** a line of text.

and::

    &lt;h1&gt;Heading&lt;h1&gt;

    &lt;tt&gt;This&lt;/tt&gt; is &lt;b&gt;really&lt;/b&gt; a line of text.

will look something like:

    **Heading**

    `This` is **really** a line of text.
    
**Important**: reStructuredText errors and warnings will appear in red in the rendering pane.

Special renderings
===================

This plugin renders @image, @html, @movie, @networkx, @svg and @url nodes in
special ways.

For @image, @movie and @svg nodes, either the headline or the first line of body
text may contain a filename.  If relative, the filename is resolved relative to
Leo's load directory. 

- ``@graphics-script`` executes the script in the body text in a context containing
  two predefined variables:
      
    - gs is the QGraphicsScene for the rendering pane.
    - gv is the QGraphicsView for the rendering pane.
    
  Using these variables, the script in the body text may create graphics to the
  rendering pane.

- ``@image`` renders the file as an image.


- ``@html`` renders the body text as html.


- ``@movie`` plays the file as a movie.  @movie also works for music files.

- ``@networkx`` is non-functional at present.  It is intended to
  render the body text as a networkx graph.
  See http://networkx.lanl.gov/


- ``@svg`` renders the file as a (possibly animated!) svg (Scalable Vector Image).
  See http://en.wikipedia.org/wiki/Scalable_Vector_Graphics
  **Note**: if the first character of the body text is ``&lt;`` after removing Leo directives,
  the contents of body pane is taken to be an svg image.

- ``@url`` is non-functional at present.

Settings
========

- ``@color rendering-pane-background-color = white``
  The background color the rendering pane when rendering text.

- ``@bool view-rendered-auto-create = False``
  When True, show the rendering pane when Leo opens an outline.
  
- ``@bool view-rendered-auto-hide = False``
  When True, hide the rendering pane for text-only renderings.

- ``@string view-rendered-default-kind = rst``
  The default kind of rendering.  One of (big,rst,html)

- ``@bool scrolledmessage_use_viewrendered = True``
  When True the scrolledmessage dialog will use the rendering pane,
  creating it as needed.  In particular, the plugins_menu plugin
  will show plugin docstrings in the rendering pane.
  
Acknowledgment
==============

Terry Brown created this initial version of this plugin,
and the free_layout and NestedSplitter plugins used by viewrendered.
</t>
<t tx="ekr.20110602091552.16899">Terminology: the *legacy* (aka tabbed) autocompleter shows completions in Leo's
tabbed pane. The *new* (aka qcompleter) autocompleter shows completions in or
near the body pane.

Appearance
==========

There is little change to the legacy completer, except that no text is
highlighted in the body pane during completion. This is calmer than before.
Furthermore, there is no longer any need for highlighting, because when the user
types a backspace the legacy completer now simply deletes a single character
instead of the highlighted text.

One minor change: the legacy completer now *does* insert characters that do
not match the start of any possible completion. This is an experimental feature,
but it might play well with using codewise completions as a fallback to
leo-related completions.

Function and design
===================

Both the legacy and new completer now work *exactly* the same way, because they
both use the AutoCompleterClass to compute the list of completions.

The strict "stateless" requirement means that the "intermediate" completions
must be entered into the body pane while completion is active. It works well as
a visual cue when using the tabbed completer: indeed, the tabbed completer would
be difficult to use without this cue.

The situation is slightly different with the qcompleter. Adding code before the
user accepts the completion might be considered an "advanced" feature. However,
it does have two important advantages, especially when "chaining" across
periods: it indicates the status of the chaining and it limits what must appear
in the qcompleter window.

Codewise completions
====================

The codewise-oriented completions appear to work well. In large part,
this is due to adding the global "self." completions to all class-related
completions (kind == 'class' in ac.get_codewise_completions). This looks like a
really good hack, and it eliminates the need for the ContextSniffer class.

Performance
===========

Performance of leo-related completions is *much* better than before. The old
code used Python's inspect module and was horribly complex. The new code uses
eval and is perfectly straightforward.

The present codewise-related code caches completions for all previously-seen
prefixes. This dramatically speeds up backspacing. Global caching is possible
because completions depend *only* one the present prefix, *not* on the presently
selected node. If ContextSniffer were used, completions would depend on the
selected node and caching would likely be impractical. Despite these
improvements, the performance of codewise-oriented completions is noticeably
slower than leo-related completions.

Performance notes
=================

The ac.get_cached_options cuts back the prefix until it finds a cached prefix.
ac.compute_completion_list then uses this (perhaps-way-too-long-list) as a
starting point, and computes the final completion list by calling
g.itemsMatchingPrefixInList.

This may not be absolutely the fastest way, but it is much simpler and more
robust than attempting to do "prefix AI" based on comparing old and new
prefixes. Furthermore, this scheme is completely independent of the how
completions are actually computed. The autocompleter now caches options lists,
regardless of whether using eval or codewise.

In most cases the scheme is extremely fast: calls to get_completions replace
calls to g.itemsMatchingPrefixInList. However, for short prefixes, the list that
g.g.itemsMatchingPrefixInList scans can have thousands of items. Scanning large
lists can't be helped in any case for short prefixes.

Happily, the new scheme is still *completely* stateless: the completionDict does
*not* define state (it is valid everywhere) and no state variables had to be
added. In short, the new caching scheme is much better than before, and it
probably is close to optimal in most situations.
</t>
<t tx="ekr.20110604105805.16766">- Double-clicking a headline now colorizers the headline exactly the same way as
  when editing the headline with ctrl-H. This was a serious problem for those
  with dark window-color schemes.
  
- The distribution script now ensures that leo\plugins\spellpyx.txt contains
  Linux-style newlines. This prevents crashes in the PyEnchant spell checker.
  
- Leo imports .cfg files just like .ini files.

- Fixed crasher in graphcanvas plugin caused by a bug in CommandChainDispatcher.add.
</t>
<t tx="ekr.20110611085637.5009"></t>
<t tx="ekr.20110611085637.5010">- Fixed ancient, major bug: F3 now makes sure to save headline changes

- Fixed old bug: set-find-x commands no longer abort find commands

  The commands that switch find scope, set-find-xxx, no longer terminate the
  find command, if one is active.  This is an old bug, and it's good to fix it. 

- Fixed recent bugs in the viewrendered and scrolledmessage plugins

  An earlier rev fixed a bug that effectively destroyed the viewrendered plugin.
  It was caused by the new convention that alleviates the need for many
  \@language directives. The fix was simply to enable the update_rst method if
  the massaged p.b is not empty.

  ScrolledMessageDialog.convertMessage now renders rst by default, unless
  *either* the html or text button is pressed.  There really should be three
  radio buttons: text, html or rST, but that's a tiny interface glitch.  The
  actual bug however, was much more serious: rst was never being rendered. 

- Fixed chapters problems

    http://groups.google.com/group/leo-editor/browse_thread/thread/3f15a855ca38b26e
    
    The new code is more relaxed about where @chapter nodes may reside.  They
    are always *created* as the last child of the first @chapters node in the
    outline (the @chapters, plural, node is created as needed).  However, you may
    move them while in the "main" chapter, with no ill effects.  In fact, you could
    swap @chapter nodes with the same name: when you select a chapter, Leo will use
    (show) the first node it finds. 
    
    The new code is now both more careful and more tolerant of @chapter nodes
    deleted by hand.  The chapter will still appear in the dropdown list: if you
    select it you will give a polite warning.  That's all.  In particular, the
    deleted chapter will *remain* in the dropdown list until you use the proper
    chapter-remove command.  That's about the only sane alternative: it allows you
    to resurrect the chapter, by hand or with an undo. 
    
    This is all made possible because the new code is almost completely stateless.
    The only exception is the saved position used to select a node when selecting a
    chapter. The old position-based findPositionInChapter method has been simplified
    to make it work more reliably. It first looks for a "perfect" match using
    positions, and then degrades to looking for a vnode match. In practice, most
    matches are, in fact, perfect. The "imperfect" case typically happens when the
    user alters nodes in @chapter trees by hand in the "main" chapters.
    
    Technical highlights:
        
    - The check for c.positionExists(p) in c.setCurrentPosition continues to fail
      when deleting @chapter nodes. However, the code now simply falls back to
      c.rootPosition, without any apparent harm.
      
    - The chapterController and chapter classes are now completely stateless, except
      for chapter.p.
      
        A. chapter.findPositionInChapter has been simplified and generalized. It now
           falls back to a reasonable value, based on p.v, if chapter.p does not
           exist.
           
        B. All chapterController code now recomputes the location of @chapters and
           @chapter nodes whenever those locations are needed.
           
        C. All chapter commands are unchanged in their actual workings, but all contain
           a care "preamble" of checking code.
           
- Added unit test for all chapter commands.  All interactive commands now have
  an xByName helper for use by unit tests.
  
- Added lockout to leoQtTreeTab.  This prevents flash during the rename chapter command.

- Rewrote chapter.chapterSelectHelper.  This reduces, but does not eliminate, the
  number of warnings given by c.setCurrentPosition.


- Fixed recent bug: handle 'Escape' character properly

  The fix was a last-minute adjustment in leoQtEventFilter.create_key_event.


- Fixed caps-lock problem

  The fix was yet another last-minute fix leoQtEventFiler.create_key_event.

- Made sure all keys contribute to lossage
</t>
<t tx="ekr.20110611085637.5012">- Simplified Leo's key handling, an important improvement to Leo's core.

- Changed names of commands so they have common prefixes

    Any custom key bindings (none are bound by default) will have to change.
    
    The new prefixes are::
    
        abbrev-     abbreviation commands
        buffer-     buffer command
        directory-  director commands
        file-       file commands
        gc-         garbage collection
        macro-      macro expansion
        rectangle-  rectangle commands
        register    register commands
        
    The already existing prefixes are::
    
        apropos-    help
        ddabrev-    dynamic abbreviations
        find-       find commands
        isearch-    incremental search
        print-      print information
        run-        run unit tests
        toggle-     toggle settings
        yank-       yank
        

- Finished macros

    The macro-load and macro-save are as simple as possible.

    No further work will be done on macros unless somebody really wants these commands.


- Added support for word-only option for regular expressions

When the word-only option is in effect, Leo ensures that the search pattern
begins and ends with the '\b' anchor.

- Leo's startup code now forces the qt gui: it changes qttabs to qt.

- Added support for expanded sections in plugin.  Added three new options:

    expand_noweb_references
    
       True: Replace references by definitions.
       Definitions must be descendants of the referencing node.
    
    ignore_noweb_definitions
    
        True: ignore section definition nodes.
    
    expand_noweb_recursively
    
        True: recursively expand definitions by expanding any
        references found in definitions.
</t>
<t tx="ekr.20110612104631.16414">@language rest

**New in Leo 4.9**: The following three options allow you
to expand noweb section references, much like Leo itself does.

**expand_noweb_references**

   True: Replace references by definitions.
   Definitions must be descendants of the referencing node.

**ignore_noweb_definitions**

    True: ignore section definition nodes.

**expand_noweb_recursively**

    True: recursively expand definitions by expanding any
    references found in definitions.
        
Notes:

- This is an experimental feature: all aspects might changed. The defaults for
  all these options ensure that the rst3 command works as it has always.

- The rst3 command ensures that unbounded expansions can not happen. While
  expanding any section, the rst3 will not expand again any sections that have
  already occurred in the expansion.
</t>
<t tx="ekr.20110613172008.15106">- Running all unit tests leaves all files unchanged. This was a major annoyance.

- Leo now does a keyboard-quit when deactivating a window.

- Fixed an ancient bug: everything after @all was put in the wrong node!

- Fixed an ancient bug: wrap-around search now restarts when find pattern changes.

- Fixed an ancient bug: F-keys end incremental searches.

- Fixed a serious recent problem with commands dispatched from menus The Shift
  modifier was deleted from all commands executed by selecting an item in menus!
  A new unit test checks that menus behave as expected.

- Dismiss splash screen before putting up the dialog that asks for an ID.
</t>
<t tx="ekr.20110616100929.14851">- When running on MacOS, Leo uses the qt gui when the qttabs gui is requested.

- Leo now looks in home/.leo/Icons directory for icons before looking in the
  leo/Icons directory.
  http://groups.google.com/group/leo-editor/browse_thread/thread/80163aec96b8ea45/4f58418924172252

- Fixed bug 797470: File data sometimes silently erased when the tangler fails.
  https://bugs.launchpad.net/leo-editor/+bug/797470 This was a serious bug, but
  it could happen only when saving an erroneous file twice.

- Fixed bug 798194: --maximized has no effect
  https://bugs.launchpad.net/leo-editor/+bug/798194

- Added the @bool forbid_invalid_completions setting.

- Non-plain keys, such as Ctrl-s, abort auto-completion and are interpreted as
  usual.

- Don't mark the .leo file as changed when setting orphan bit. There is no need:
  the orphan bits will ensure errors get reported if the file is saved.

- Disabled the open-compare-window command. It is/was a Tk only command.

- The open-python-window command fails more gracefully It issues a message
  instead of crashing if idlelib does not exist.
</t>
<t tx="ekr.20111017085134.16158"></t>
<t tx="ekr.20111017085134.16159">'''
Copy the @screenshot node (a child of this node)
to all @slide nodes under p, (an @slideshow node),
that do not contain an @screenshot node.
'''

error = None
# Find this node:
h = '@button copy-@screenshot-node'
p2 = g.findNodeAnywhere(c,h)
if not p2:
    error = 'Can not find',p.h
# Find the @screenshot tree and the optional @select node.
if not error:
    select,template = None,None
    for child in p2.children():
        if g.match_word(child.h,0,'@screenshot'):
            template = child.copy()
        if g.match_word(child.h,0,'@select'):
            select = child.copy()
    if not template:
        error = 'No template @slideshow node in %s' % p2.h
if not error:
    if not g.match_word(p.h,0,'@slideshow'):
        error = 'not an @slideshow node',p.h
if error:
    g.error(error)
else:
    c.selectPosition(template)
    c.copyOutline()
    changed = False
    b = c.undoer.beforeChangeTree(p)
    for child in p.children():
        if not g.match_word(child.h,0,'@slide'):
            continue
        for grandChild in child.children():
            if g.match_word(grandChild.h,0,'@screenshot'):
                break
        else:
            changed = True
            p3 = child.insertAsLastChild()
            c.selectPosition(p3)
            c.pasteOutline()
            g.note('copied @screenshot to %s' % child.h)
            if select:
                c.selectPosition(p3)
                p4 = child.insertAsLastChild()
                p4.h = select.h
                g.note('copied %s to %s' % (select.h,child.h))
            c.selectPosition(p3)
            c.deleteOutline(p3)
            child.contract()
    if changed:
        c.undoer.afterChangeTree(p,'copy-@screenshot',b)
    c.redraw()
</t>
<t tx="ekr.20111017085134.16160"></t>
<t tx="ekr.20111017085134.16161">My to-do list.
</t>
<t tx="ekr.20111017085134.16162">1. Make Leo tutorials.  The world is waiting.
2. Pay phone bill or the world will never know.
</t>
<t tx="ekr.20111017085134.16163"></t>
<t tx="ekr.20111017085134.16164"></t>
<t tx="ekr.20111017085134.16165"></t>
<t tx="ekr.20111017085134.16166"></t>
<t tx="ekr.20111017085134.16167">@language rest

This is my diary.
</t>
<t tx="ekr.20111017085134.16168">July 1
    Started writing in my diary.
July 2
    Wrote another sentence in my diary.
July 3
    Keeping my diary very regularly.
July 5
    Oops...Yesterday I forgot towrite in my diary.
</t>
<t tx="ekr.20111017085134.16169"></t>
<t tx="ekr.20111017085134.16170"></t>
<t tx="ekr.20111017085134.16171"></t>
<t tx="ekr.20111017085134.16172"></t>
<t tx="ekr.20111017085134.16173"></t>
<t tx="ekr.20111017085134.16174"></t>
<t tx="ekr.20111017085134.16175"></t>
<t tx="ekr.20111017085134.16176">'''Create @slide nodes under p, an @slideshow node.'''

n = 23 # Number of last slide to be created.

existing = [z.copy().h for z in p.children() 
    if g.match_word(z.h,0,'@slide')]

if g.match_word(p.h,0,'@slideshow'):
    b = c.undoer.beforeChangeTree(p)
    changed = False
    for n in range(1,n+1):
        h = '@slide %03d' % n
        if h not in existing:
            changed = True
            child = p.insertAsLastChild()
            child.h = h
            g.note('created %s' % h)
    if changed:
        c.undoer.afterChangeTree(p,'ins-@slide-nodes',b)
    else:
        g.note('no @slide nodes inserted')
    c.redraw()
else:
    g.error('not an @slideshow node',p.h)
</t>
<t tx="ekr.20111017085134.16177" str_atime="1376412901.0">m = g.loadOnePlugin('screenshots')
m.make_slide_command(event={'c':c})
</t>
<t tx="ekr.20111017085134.16178">m = g.loadOnePlugin('screenshots')
m.make_slide_show_command(event={'c':c})
</t>
<t tx="ekr.20111017085134.16179">'''Meld Wink slides into an @slideshow folder.

   Copy screenshot files from the wink_dir to slideshow_dir, numbering
   the destination files to reflect "holes" created by @no-screenshot
   nodes.

   This script carefully checks that the number of screenshot files
   matches the number of screenshots referenced by the @slide nodes.
   No copying takes place if the numbers are not as expected.'''

@language python

import glob
import os
import shutil

slideshow_dir = 'C:/leo.repo/trunk/leo/doc/html/slides/leo-basics-step-by-step'

wink_dir = 'C:/leo.repo/trunk/leo/doc/html/slides/leo-basics-step-by-step/_files'
    # The directory containing the wink screenshots.
    # This will usually be &lt;slideshow_dir&gt;/_files.
    # **Important** You generate these screenshots using Wink's 
    # Export As Html command (!)

@others

mc = MeldController(c,p,slideshow_dir,wink_dir)
mc.run()
</t>
<t tx="ekr.20111017085134.16180">class MeldController:

    def __init__ (self,c,p,slideshow_dir,wink_dir):

        self.c = c
        self.slideshow_dir = slideshow_dir
        self.slideshow_node = p
        self.wink_dir = wink_dir

    @others
</t>
<t tx="ekr.20111017085134.16181"></t>
<t tx="ekr.20111017085134.16182">def fix (self,fn):
    return os.path.normcase(fn).replace('\\','/')

def finalize (self,fn):
    return self.fix(g.os_path_finalize_join(self.slideshow_dir,fn))
</t>
<t tx="ekr.20111017085134.16183">def has_at_no_screenshot_node (self,p):

    for p in p.children():
        if self.match(p,'@no-screenshot'):
            return True
    else:
        return False
</t>
<t tx="ekr.20111017085134.16184">def match (self,p,pattern):

    '''Return True if p.h matches the pattern.'''

    return g.match_word(p.h,0,pattern)
</t>
<t tx="ekr.20111017085134.16185">def run (self):

    print('='*20)

    aList = self.get_wink_screenshots()
    if not aList:
        return

    if not self.check(aList):
        return

    # Pass 1: copy files for @slide nodes w/o @no-screenshot nodes.
    self.copy_files(aList)

    # Pass 2: adjust children of @slide nodes.
    self.adjust_slideshow()

    print('meld done')
</t>
<t tx="ekr.20111017085134.16186">def adjust_slideshow(self):

    '''Adjust all @slide nodes in the slideshow.'''

    # Traverse the tree as in the screenshot plugin.
    # That is, ignore @ignore trees and nested @slide nodes.
    # This ensures that the slide number, n, is correct.
    p = self.slideshow_node
    after = p.nodeAfterTree()
    p = p.firstChild()
    n = 1
    while p and p != after:
        if self.match(p,'@slide'):
            self.adjust_slide_node(p,n)
            n += 1
            p.moveToNodeAfterTree()
        elif self.match(p,'@ignore'):
            p.moveToNodeAfterTree()
        else:
            p.moveToThreadNext()
</t>
<t tx="ekr.20111017085134.16187">def adjust_slide_node (self,p,slide_number):

    '''Adjust p, an @slide node.'''

    trace = True

    # Delete the first "@url built slide" node.
    self.delete_at_url_built_slide_node(p)

    # Do nothing more if there is an @no-screenshot node.
    if self.has_at_no_screenshot_node(p):
        return

    # Add or update the "@url final output file" node.
    p2 = self.add_at_url_final_output_file(p,slide_number)

    # Add the .. image:: directive.
    self.add_image_directive(p,slide_number)
</t>
<t tx="ekr.20111017085134.16188">def add_at_url_final_output_file (self,p,slide_number):

    '''Create or update the "@url final output file" node.'''

    trace = True
    tag ='@url final output file'

    for child in p.children():
        if self.match(child,tag):
            p2 = child ; break
    else:
        if trace: g.es('add %s' % tag)
        p2 = p.insertAsLastChild()
        p2.h = tag

    p2.b = self.finalize(
        'slide-%03d.png' % (slide_number))

    return p2
</t>
<t tx="ekr.20111017085134.16189">def add_image_directive (self,p,slide_number):

    '''Add an image directive in p if it is not there.'''

    s = '.. image:: slide-%03d.png' % (slide_number)

    if p.b.find(s) == -1:
        p.b = p.b.rstrip() + '\n\n%s\n\n' % (s)
</t>
<t tx="ekr.20111017085134.16190">def delete_at_url_built_slide_node (self,p):

    '''Delete any "@url built slide" node in p's children.'''

    trace = True
    tag = '@url built slide'

    for child in p.children():
        if self.match(child,tag):
            if trace: g.es('del %s in %s' % (tag,p.h))
            child.doDelete()
            break
</t>
<t tx="ekr.20111017085134.16191">def check (self,aList):

    '''
    Check that len(aList) matches the number of @slide nodes in the
    slideshow. Don't count @slide nodes containing an @no-screenshot node.
    '''

    p = self.slideshow_node
    n1 = len(aList)
    n2,n3 = self.count_slide_nodes()

    if not self.check_dir(self.wink_dir):
        return False
    if not self.check_dir(self.slideshow_dir):
        return False
    if not self.match(p,'@slideshow'):
        return g.error('not a @slideshow node: %s',p.h)

    if n1 != (n2-n3):
        return g.error(
            '%s wink slides\n'
            '%s @slide nodes\n'
            '%s @no_screenshot nodes' % (
                n1,n2,n3))

    return True
</t>
<t tx="ekr.20111017085134.16192">def check_dir (self,theDir):

    if not g.os_path_exists(theDir):
        return g.error('not found: %s' % (theDir))

    if not g.os_path_isdir(theDir):
        return g.error('not a directory: %s' % (theDir))

    return True
</t>
<t tx="ekr.20111017085134.16193">def count_slide_nodes (self):

    '''Return n1,n2

    n1 is the total number of @slide nodes in the @slideshow tree.
    n2 is number of @slide nodes containing an @no-slideshow child.
    '''

    p = self.slideshow_node
    after = p.nodeAfterTree()
    p = p.firstChild()
    n1,n2 = 0,0
    while p and p != after:
        if self.match(p,'@slide'):
            n1 += 1
            if self.has_at_no_screenshot_node(p):
                n2 += 1
            p.moveToNodeAfterTree()
        elif self.match(p,'@ignore'):
            p.moveToNodeAfterTree()
        else:
            p.moveToThreadNext()

    g.trace(n1,n2)
    return n1,n2
</t>
<t tx="ekr.20111017085134.16194">def copy_files (self,aList):

    '''Copy files from the wink_dir to slideshow_dir,
    numbering the destination files to reflect "holes"
    created by @no-screenshot nodes.'''

    # Traverse the tree as in the screenshot plugin.
    # That is, ignore @ignore trees and nested @slide nodes.
    # This ensures that the slide number, n, is correct.
    p = self.slideshow_node
    after = p.nodeAfterTree()
    p = p.firstChild()
    wink_n = 0 # Wink screenshot numbers start at 0.
    slide_n = 1 # Slide numbers start at 1.
    while p and p != after:
        if self.match(p,'@slide'):
            if not self.has_at_no_screenshot_node(p):
                self.copy_file(aList,slide_n,wink_n)
                wink_n += 1
            slide_n += 1
            p.moveToNodeAfterTree()
        elif self.match(p,'@ignore'):
            p.moveToNodeAfterTree()
        else:
            p.moveToThreadNext()
</t>
<t tx="ekr.20111017085134.16195">def copy_file (self,aList,slide_n,wink_n):

    trace = True

    if wink_n &gt;= len(aList):
        return g.trace('can not happen: '
            'len(aList): %s, n: %s' % (
                len(aList),wink_n))

    fn_src = aList[wink_n]
    fn_dst = 'slide-%03d.png' % (slide_n)

    if trace:
        g.trace('%7s -&gt; %s' % (g.shortFileName(fn_src),fn_dst))

    shutil.copyfile(fn_src,fn_dst)
</t>
<t tx="ekr.20111017085134.16196">def get_wink_screenshots (self):

    '''Return the properly sorted list of wink screenshots.'''

    trace = False

    aList = glob.glob(self.wink_dir + '/*.png')

    def key(s):
        path,ext = g.os_path_splitext(s)
        junk,n = g.os_path_split(path)
        n = n.strip()
        if n.isdigit():
            return int(n)
        else:
            g.error('bad wink screenshot: %s' % (s))
            raise KeyError

    aList.sort(key=key) # Essential.

    if trace:
        for z in aList:
            print(z)

    return aList
</t>
<t tx="ekr.20111017085134.16197">'''Renumber @slide nodes under p, an @slideshow node.'''

if g.match_word(p.h,0,'@slideshow'):
    n = 1
    for child in p.children():
        if g.match(child.h,0,'@slide'):
            child.h = '@slide %03d' % n
            n += 1
    c.redraw()
else:
    g.error('not an @slideshow node',p.h)
</t>
<t tx="ekr.20111017085134.16198">@language python

changed = 0
b = c.undoer.beforeChangeTree(p)

for child in p.children():
    s = child.b
    i = s.find('.. image::')
    if i &gt; -1:
        i,j = g.getLine(s,i)
        child.b = s[:i] + s[j+1:]
        # g.es(child.h)
        changed += 1

if changed:
    g.es('changed %s nodes' % changed)
    c.undoer.afterChangeTree(p,'remove-image-directives',b)

</t>
<t tx="ekr.20111017085134.16199">@language python

changed = 0
b = c.undoer.beforeChangeTree(p)
for child in p.children():
    for child2 in child.children():
        if g.match_word(child2.h,0,'@url built slide'):
            child2.doDelete()
            changed += 1
            break

if changed:
    g.es('deleted %s nodes' % (changed))
    c.undoer.afterChangeTree(p,'remove-@url-built-slide',b)
    c.redraw()
</t>
<t tx="ekr.20111017085134.16200">@language python

changed = 0
b = c.undoer.beforeChangeTree(p)
for child in p.children():
    for child2 in child.children():
        if g.match_word(child2.h,0,'@url final output file'):
            child2.doDelete()
            changed += 1
            break

if changed:
    g.es('deleted %s nodes' % (changed))
    c.undoer.afterChangeTree(p,'remove-@url-final-output',b)
    c.redraw()
</t>
<t tx="ekr.20111108052738.5507">run-marked-unit-tests-externally = Alt-4
run-all-unit-tests-externally = Alt-5
</t>
<t tx="ekr.20111115063523.13619">The following puts up a test window when run as a Leo script::

    from PyQt4 import QtGui
    w = QtGui.QWidget()
    w.resize(250, 150)
    w.move(300, 300)
    w.setWindowTitle('Simple test')
    w.show()
    c.my_test = w # &lt;-- Keep a reference to the window!
    
**Important**: Something like the last line is essential. Without it, the window
would immediately disappear after being created.  The assignment::

    c.my_test = w
    
creates a permanent reference to the window so the window won't be garbage
collected after the Leo script exits.
    
</t>
<t tx="ekr.20111127144911.5544">@language rest
@pagewidth 75

@ @rst-options
call_docutils=False
stylesheet_path=..\doc
write_intermediate_file = True
@c

###############
Downloading Leo
###############

.. links

.. _`latest stable release`: https://sourceforge.net/projects/leo/files/Leo/4.10%20final/
.. _`SourceForge`: https://sourceforge.net
.. _`Leo's snapshots page`: http://www.greygreen.org/leo/
.. _`nightly snapshot`: http://www.greygreen.org/leo/
.. _`Leo's latest sources`: https://code.launchpad.net/leo-editor/
.. _`Launchpad`: https://code.launchpad.net/
.. _`bzr`: http://bazaar.canonical.com/

Leo's core code is always being improved and developed. Unit-testing
ensures that the daily commits are as bug-free as possible. Almost all of
the time, downloading the most recent `nightly snapshot`_ of the
development code is going to give you code that is just as stable and much
more up-to-date than the most recent `latest stable release`_ which most
Leonistas would consider already outdated.

If you are just checking Leo out, feel free to use the `latest stable release`_
download if it makes you feel more secure, but once you've
decided to work with Leo on a regular basis, we highly recommend regularly
keeping your installation up to date with the most recent `nightly snapshot`_.

To summarize, you may get Leo in three ways:

1. Download the `latest stable release`_ from `SourceForge`_. This release
   contains an executable installer. This release will usually be a bit out of date.

2. Download a `nightly snapshot`_ from `Leo's snapshots page`_. This page
   contains .zip archives of Leo's code from 1, 2, 5, 10, 30 and 90 days
   ago.
   
3. Download `Leo's latest sources`_ from `Launchpad`_ using `bzr`_. Once
   bzr is installed, getting the latest version of Leo is very easy.
</t>
<t tx="ekr.20120229094652.15098">.. .. http://groups.google.com/group/leo-editor/browse_thread/thread/92ae059cc5213ad3

**Important**: Installing Leo on MacOS is challenging. Furthermore, Leo
does not work as well on MacOS as on other platforms.

Many thanks to Ludwig Schwardt for the following installation instructions.

I recently received a new MacBook Pro and did a fresh upgrade to Mac OS
10.7 (Lion). I then used the opportunity to test out installation
procedures of various software on a clean system. My main finding is that
the excellent Homebrew (mxcl.github.com/homebrew/) makes things much easier
these days.

Why Homebrew? It does not try to replace every single bit of functionality
on your Mac with their own version, like Macports or fink. It reuses the
existing libraries as far as possible. No need to reinstall Python, for
example (one of my pet gripes when people try to install new software on
their Macs, and the source of much confusion and pain). It installs to
/usr/local, the standard place to find third-party libraries and headers,
instead of the obscure /opt or /sw. It's simple to use and to extend.

I last installed Leo on Mac OS 10.4 (Tiger) back in the Tk days, and
wondered what it looked like in Qt. All the horror stories of PyQT on Mac
discouraged me from trying this before, so I was keen to see if Homebrew
helps. Here is my installation write-up:

- Read the Homebrew installation instructions at
  https://github.com/mxcl/homebrew/wiki/Installation

- Make sure you have Xcode installed (test it by confirming that "gcc" runs
  in the Terminal). You can either get the full Xcode beast or the
  lean-and-mean Command-Line Tools for Xcode, as suggested in the Homebrew
  installation instructions.

- In preparation for Homebrew, the best option in my opinion is
  to delete /usr/local via::

    sudo rm -rf /usr/local

  and install any software in it via Homebrew instead. If this step
  fills you with dread and you do not want to lose your beloved
  third-party software, the second-best option is to make sure you
  have write permission for the directory via::

    sudo chown -R &lt;your user name&gt;:admin /usr/local

  If you don't know your username, run "whoami". :-) This is
  useful because homebrew actually discourages you from
  installing third-party software as the superuser (the usual Mac
  apps in /Applications are also installed as the normal user,
  for that matter).

- Install Homebrew (http://mxcl.github.com/homebrew/) by running the
  following command in the Terminal::

    /usr/bin/ruby -e "$(/usr/bin/curl -fsSL https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"
    
- Run "brew doctor" and check any further suggestions to improve your system.

- Run "brew update" to get the latest formulas

- Install sip and note the caveat::

    brew install sip

  This warns you to add the local python directory to your PYTHONPATH.
  Make a note of what this is (especially if you are not on Lion!).

- Add the following lines to your ~/.bash_profile
  (or ~/.profile on Leopard). This is the default for LION::

      export PATH=/usr/local/bin:$PATH
      # This is for SIP (and PyQT) as suggested by Homebrew
      export PYTHONPATH=/usr/local/lib/python2.7/site-packages:$PYTHONPATH

- Install PyQT::

    brew install pyqt
 
- Open a new Terminal tab / window so that the above settings take effect,
  and install Leo. I downloaded the Leo-4.9-final-a.zip, unzipped it, and
  ran "python launchLeo.py" inside the Leo directory.

It would really be great to get a Leo formula going for Homebrew. As
mentioned before, the main question is just where to place all the Leo
files in the /usr/local hierarchy.
</t>
<t tx="ekr.20120229094652.15099">Put @command nodes as children of an @commands node in myLeoSettings.leo.
This makes the the @command nodes available to all opened .leo files.

Using @command rather than @button means that there is never any need to
disable scripts. There is no need for @button. To see the list of your
\@command nodes, type::

    &lt;alt-x&gt;@c&lt;tab&gt;
    
Similarly to see the list of your \@command nodes, type::

    &lt;alt-x&gt;@b&lt;tab&gt;
</t>
<t tx="ekr.20120229094652.15124">It sometimes happens that the focus gets left in a Leo
widget that doesn't support Leo's key bindings. You would
think that you would have to use the mouse to click in, say,
the body pane so that you can use Leo's key bindings again.

But you don't have to do that.  Instead, use Alt-tab once to change
away from Leo, and then use Alt-tab again to change back to Leo.  When
you do this, Leo puts focus in the body pane and you are all set.
</t>
<t tx="ekr.20120229094652.15125">When running unit tests externally, Leo copies any @mark-for-unit-tests nodes
to dynamicUnitTest.leo.  Of course, this is in addition to all @test nodes
and @suite nodes that are to be executed.
You can use @mark-for-unit-test nodes to include any "supporting data"
you want, including, say, "@common test code" to be imported as
follows::

    exec(g.findTestScript(c,'@common test code'))

**Note**: putting @settings trees as descendants of an @mark-for-unit-test node
will copy the @setting tree, but will *not* actually set the corresponding settings.
</t>
<t tx="ekr.20120229094652.15130">@language rest
@pagewidth 75

Q. When I run the following script I see a window appear and then
immediately disappear::

    from PyQt4 import QtGui
    w = QtGui.QWidget()
    w.resize(250, 150)
    w.move(300, 300)
    w.setWindowTitle('Simple test')
    w.show()
    
What's going on?

A. When the script exits the sole reference to the window, w, ceases to
exist, so the window is destroyed (garbage collected). To keep the window
open, add the following code as the last line to keep the reference alive::

    g.app.scriptsDict['my-script_w'] = w

Note that this reference will persist until the next time you run the
execute-script. If you want something even more permanent, you can do
something like::

    g.app.my_script_w = w
</t>
<t tx="ekr.20120229094652.15137">.. .. http://groups.google.com/group/leo-editor/browse_thread/thread/61019e45d75a6f18/71ee770ee4421222

1. Archive and remove the previous version of Leo.
2. Download the nightly snapshot zip file.
3. Unzip it into the same place as the previous version.
4. Enjoy your up-to-date Leo code...

To make this work, it's important to keep your folder containing Leo
separate from your .mySettings.leo and any data files.
</t>
<t tx="ekr.20120229094652.15148">.. _`this posting about BibTeX citations`: http://groups.google.com/group/leo-editor/browse_thread/thread/d36d76174dcd6786/9c2a298049f4f01c

.. _`raw-data`: http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through

When using LaTeX and BibTeX, I would like to use inside of Leo a kind of
LaTeX-inline-markup, that after generation of the RsT file through Sphinx
as well as after running of "make latex", generate a LaTeX file containing
the citation call of the form \cite{CITBook001} as described in a file
\*.bib. Is there a way to have Leo/Sphinx/RsT generate the inline raw latex
syntax?

Use the docutils `raw-data`_ syntax. Examples::

    .. role:: raw-role(raw)
      :format: html latex
    .. raw:: latex
      \bibliographystyle{acm}
      \bibliography{myBibliography}
      
For more details, see `this posting about BibTeX citations`_.
</t>
<t tx="ekr.20120229094652.15152">Some people seem to think that it is difficult to understand how Leo
handles "clone wars": differing values for a cloned nodes that appear in
several external files. That's not true. The rule is::

    **The last clone that Leo reads wins.**

That is, for any cloned node C, Leo takes the value of C.h and C.b to
be the values specified by the last copy that Leo reads.

There is only one complication::

    **Leo reads the entire outline before reading any external files.**

Thus, if C appears in x.leo, y.py and z.py, Leo will choose the value for C
in x.py or y.py, depending on which @&lt;file&gt; node appears later in the
outline.

**Note**: Whenever Leo detects multiple values for C when opening an
outline, Leo creates a "Recovered nodes" tree. This tree contains all the
various values for C, nicely formatted so that it is easy to determine
where the differences are.

</t>
<t tx="ekr.20120317130339.8282">@language rest
@pagewidth 75

The following script won't work as intended:

    from PyQt4 import QtGui
    w = QtGui.QWidget()
    w.resize(250, 150)
    w.move(300, 300)
    w.setWindowTitle('Simple test')
    w.show()
    
When the script exits the sole reference to the window, w, ceases to
exist, so the window is destroyed (garbage collected). To keep the window
open, add the following code as the last line to keep the reference alive::

    g.app.scriptsDict['my-script_w'] = w

Note that this reference will persist until the next time you run the
execute-script. If you want something even more permanent, you can do
something like::

    g.app.my_script_w = w
</t>
<t tx="ekr.20120319065417.8788">The following check boxes options appear in the search dialog and control
the operations of the find and change commands.

Ignore Case
    When checked, the Find and Change commands ignore the case of
    alphabetic characters when determining matches.

Mark Changes
    When checked, the Change command marks all headlines whose headline or
    body text are changed by the command.

Mark Matches
    When checked, the Find and Change commands mark all headlines in which
    a match is found with the pattern.

Pattern Match
    When checked, the Find and Change commands treat several characters
    specially in the find pattern.

    - '*'  matches any sequence of zero or more characters.
    - '.'  matches any single character.
    - '^'  matches a newline at the start of a pattern.
    - '$'  matches a newline at the end of a pattern.

Examples::

    "^abc$" matches lines that only contain "abc".
    "^a" matches any line starting with "A".
    "a$" matches any line ending with "a".
    "^*$" matches any line at all.

Search Body Text
    When checked, the Find and Change commands search body text.

Search Headline Text
    When checked, the Find and Change commands search headline text.

Suboutline Only
    When checked, the Find and Change commands search only the currently
    selected headline and its offspring.

Whole Word
    When checked, the find pattern must match an entire word. Words consist
    of an alphabetic character or underscore, followed by zero or more
    alphabetic characters, numbers or underscores.

Wrap Around
    When checked, the Find and Change commands continues at the top of the
    file when the command reaches the bottom of the file. For reverse
    searches, the find or change command continues at the bottom of the
    file when the command reaches the top of the file.
</t>
<t tx="ekr.20120319065417.8790">The ``search-with-present-options`` (Ctrl-F) command prompts for a
search string. Typing the &lt;Return&gt; key puts the search string in the
Find tab and executes a search based on all the settings in the Find
tab. This is a recommended default search command. The ``find-next``
(F3) command continues a search started with
``search-with-present-options``. The ``find-previous`` (F2) commands
searches backwards using the present search options.

To search and replace, type &lt;Ctrl-F&gt;, followed by the search pattern,
followed by the ``replace-string`` (Ctrl-Shift-R) command, followed by
the replacement pattern, and finally a &lt;Return&gt; to start the search.
</t>
<t tx="ekr.20120319065417.8791">The ``find-all`` command prints all matches in the log pane. The
``clone-find-all`` command searches the outline and creates a new root node
called Found: *&lt;your search pattern&gt;*. This node contains clones of the
found nodes. The ``clone-find-all-flattened`` commands includes all found
nodes, even if they are also children of previously found nodes.
</t>
<t tx="ekr.20120319065417.8792">Leo supports a wide array of commands for searching and replacing
text. The typical way to find text is with the
``search-with-present-options`` (Ctrl-F). Focus moves to the
minibuffer. Type the search pattern, followed by a &lt;Return&gt;. To search
and replace, type &lt;Ctrl-F&gt;, followed by the search pattern, followed
by ``replace-string`` (Ctrl-Shift-R) command, followed by the
replacement pattern, and finally a &lt;Return&gt; to start the search.

The following sections discuss all of Leo's find and change commands.
**Important**: The radio buttons in the Find tab (Entire Outline,
Suboutline Only and Node only) control how much of the outline is
affected by Leo's find and change commands.
</t>
<t tx="ekr.20120319065417.8794">Several commands toggle the checkboxes and radio buttons in the Find tab,
and thus affect the operation of the search-with-present-options command.
You may bind these commands to keys or toggle these options in a mode.
These commands toggle checkboxes::

    Alt+Ctrl+I  toggle-find-ignore-case-option
    Alt+Ctrl+B  toggle-find-in-body-option
    Alt+Ctrl+H  toggle-find-in-headline-option
    Alt+Ctrl+C  toggle-find-mark-changes-option
    Alt+Ctrl+F  toggle-find-mark-finds-option
    Alt+Ctrl+X  toggle-find-regex-option
    Alt+Ctrl+W  toggle-find-word-option
    Alt+Ctrl+A  toggle-find-wrap-around-option

These commands set radio buttons::

    Alt+Ctrl+E  set-find-everywhere
    Alt+Ctrl+N  set-find-node-only
    Alt+Ctrl+S  set-find-suboutline-only
</t>
<t tx="ekr.20120319065417.8795">The following commands set an option in the Find tab, then work
exactly like the ``search-with-present-options`` command. The
``search-backward`` and ``search-forward`` commands set the 'Whole
Word' checkbox to False. The ``word-search-backward`` and
``word-search-forward`` set the 'Whole Word' checkbox to True. The
``re-search-forward`` and ``re-search-backward`` set the 'Regexp'
checkbox to True.
</t>
<t tx="ekr.20120319065417.8797">The ``replace-string`` (Ctrl-Shift-R) command prompts for a search string.
Type &lt;Return&gt; to end the search string. The command will then prompt for
the replacement string. Typing a second &lt;Return&gt; key will place both
strings in the Find tab and executes a **find** command, that is,
search-with-present-options.

The ``replace`` (Ctrl-=) command replaces the selected text with the
'change' text in the Find tab. The ``replace-then-find`` (Ctrl--)
command replaces the selected text with the 'change' text in the Find
tab, then executes the find command again. These commands can simulate
any kind of query-replace command. The ``replace-all`` command changes
all occurrences of the 'find' text with the 'change' text.
</t>
<t tx="ekr.20120319065417.8798">Incremental find commands move through the text as you type individual
characters. Typing &lt;BackSpace&gt; backtracks the search. To repeat an
incremental search, type the shortcut for that command again. Here are
Leo's incremental find commands::

    Alt+R isearch-backward
          isearch-backward-regexp
    Alt+S isearch-forward
          isearch-forward-regexp
          isearch-with-present-options
</t>
<t tx="ekr.20120319170934.6094">Leo has many commands that select nodes in the outline. These commands can be
found in the Outline:Go To menu.

As described in the tutorial, you can move about the outline by clicking on the
headlines or using Alt+arrow keys.
</t>
<t tx="ekr.20120319170934.6095">You can expand or contract a node by clicking in the tree view icon to the
left of the headline. The icon in the Qt gui matches the native OS's tree
view icon, i.e. for Mac's, a triangle pointing right or down; on Windows, a
square containing a plus or minus. Expanding a node shows its immediate
children; contracting a node hides all its children.

The ``expand-node`` and ``contract-node`` commands also expand and contract
nodes. For more convenient navigation, there are ``expand-and-go-right``
(Alt-Right) and ``contract-or-go-up`` (Alt-Left) commands.

The ``expand-all`` command expands every node in the outline.
``contract-all`` (Alt-hyphen) contracts every node in the outline. In all
but the smallest outlines, ``expand-all`` is rarely used, and it does not
have a default key binding.
</t>
<t tx="ekr.20120319170934.6096">The ``insert-node`` (Ctrl-I or Insert) command inserts a new node into the
outline. When invoked, (from any pane), it inserts a new node below the
presently selected node, and at the same level as that node, or at the
child level if it has a visible child. The ``delete-node`` command deletes
a node and all its children. To retain the children, just promote all the
children before you do the delete.
</t>
<t tx="ekr.20120319170934.6097">The ``cut-node`` (Ctrl-Shift-X) ``paste-node`` (Ctrl-Shift-V),
``copy-node`` (Ctrl-Shift-C) and ``delete-node`` commands work on nodes
rather than text. The ``cut-node`` and ``copy-node`` commands copy a text
representation of the outline to the clipboard. This representation is the
same as Leo's .leo file format with some information deleted. You may copy
this text representation into a body pane (or into any other text editor)
using Edit-&gt;Paste in the menus, Ctrl-V, or Alt-X paste-text.

**Warning**: If you want to preserve the "cloned" attribute of a node, or
want to paste the node as a clone of the node you cut or copied, use the
``past-retaining-clones`` command, which in the Outline menu is called
"Paste Node as Clone". The ``paste-node`` command instead creates a new,
distinct version of the node you previously cut or copied, though if there
were descendant nodes which were clones of each other, the new version will
have parallel, distinct nodes that are also clones of each other (just not
of the originals). You may paste a node between .leo files, but there can
be no clone relationship across files.

The ``paste-retaining-clones`` command is disabled if it would cause a node
to become a parent of itself. The Leo outline is thus mathematically a
*directed acyclic graph*: clones make it more flexible than a tree, but not
a generalized graph.
</t>
<t tx="ekr.20120319170934.6098">The ``move-outline-up`` (Ctrl-U or Alt-Shift-Up), ``move-outline-down``
(Ctrl-D or Alt-Shift-Down), ``move-outline-left`` (Ctrl-L or
Alt-Shift-Left), and ``move-outline-right`` (Ctrl-R or Alt-Shift-Right)
commands move the currently selected node. **Important**: When focus is in
the outline pane, you can move nodes without adding the Alt modifier.
Shift-Up moves the select node up, etc.

The ``promote`` (Ctrl-[) command makes all the children of
a node siblings of the node. The ``demote`` (Ctrl-]) command makes all following
siblings of a node children of the node.
</t>
<t tx="ekr.20120319170934.6099">A cloned node is a copy of a node that changes when the original changes.
One may also think of it as a single node that is hooked into the outline
at multiple positions. Because that single node brings along all its
descendants, changes are maintained across all the the clones of a node,
along with changes to its offspring (children, grandchildren, etc.), i.e.,
any changes are simultaneously made to the corresponding offspring of all
of those clones. A small red arrow in the icon box marks cloned nodes. You
can think of the arrow as pointing out that there are other paths to get to
this same node. There is no real distinction between the "original" node
and any of its clones. Any headline or body update of a clone headed
subtree affects all of its clones simultaneously. A cloned node becomes a
regular node whenever deletion of its other clones makes it the only one
left. Clones are useful for making alternate views of a program. See
`Clones`_ for full details.

The ``clone-node`` (Ctrl-\`) command creates a clone as the immediate
sibling of a selected node. You have to place it where you want it by
either using move commands, or cutting and paste the clone.
</t>
<t tx="ekr.20120319170934.6100">The ``mark`` (Ctrl-M) marks a node if it is unmarked, and unmarks the node
if it is already marked. The ``mark-subheads`` command marks all offspring
of the presently selected node. The ``mark-changed-items`` command marks
all nodes whose headline or body text has been changed since the file
was last saved.

Leo's find and change commands mark nodes if the "Mark Changes" and "Mark
Finds" checkboxes are checked. You can change these checkboxes with the
``toggle-find-mark-changes-option`` and ``toggle-find-mark-finds-option``
commands.

The ``goto-next-marked`` command selects the next marked node.
</t>
<t tx="ekr.20120319170934.6101">You may drag a node (including all its descendants) from one place to
another in an outline. To start a drag, press the main (left) mouse button
while the cursor is over the icon for a node. The cursor will change to a
hand icon. If you release the mouse button while the hand cursor is above
another node, Leo will move the dragged node after that node.
If you release the mouse button when the hand cursor is not over a node,
Leo will leave the outline pane as it is. Leo scrolls the outline pane as
the result of mouse-moved events, so to continue scrolling you must keep
moving the mouse.

If the recipient node has children and is expanded, the dropped node will
be inserted as the first child of the recipient node, otherwise the
dropped node will be inserted after the recipient node.

Holding down Alt before releasing the node will force insertion as a
child of the recipient node, even if the recipient node is not expanded.

Holding down Control before releasing the node will cause a clone to be
dropped, leaving the original where it was.
</t>
<t tx="ekr.20120319170934.6104">Leo auto indents unless @nocolor is in effect.  Typing a newline
automatically inserts the same leading whitespace present on the previous line.

If Python is the present language, Leo inserts an additional tab if the previous
line ends with a colon.  When the smart_auto_indent setting is True, Leo uses Emacs-style
auto-indentation instead.  This style of auto-indent aligns newly created lines
with unmatched ( [ or { brackets in the previous line.
</t>
<t tx="ekr.20120319170934.6105">The ``add-editor`` command adds a new editor in the body pane and gives it
the body editor focus. The ``delete-editor`` command deletes the editor
with body editor focus. The ``cycle-editor-focus`` command cycles body
editor focus between editors in the body text. The editor that has focus
shows the content of the selected outline node; the other body editors
continue to show the node contents they last had when they had the body
editor focus.
</t>
<t tx="ekr.20120319170934.6108">You can change the relative sizes of the outline and body panes by dragging
the splitter bar. The ``equal-sized-panes`` command resizes the panes so
that each fills half of the main window.
</t>
<t tx="ekr.20120319170934.6109">Leo checks that the URL is valid before attempting to open it. A valid
URL is:

-   3 or more lowercase alphas
-   followed by one :
-   followed by one or more of:
-   ``$%&amp;'()*+,-./0-9:=?@A-Z_a-z{}~``
-   followed by one of: ``$%&amp;'()*+/0-9:=?@A-Z_a-z}~`` 

That is, a comma, hyphen and open curly brace may not be the last character.

URL's in Leo should contain no spaces: use %20 to indicate spaces.

You may use any type of URL that your browser supports: http, mailto,
ftp, file, etc.
</t>
<t tx="ekr.20120319170934.6110">Chapters are regions of a Leo outline whose root is an ``@chapter`` node. They
are available in an outline if the ``@bool usechapters`` option is True.
``@chapter`` nodes may appear anywhere in an outline, but the ``create-chapter``
command (see below) creates ``@chapter`` nodes as children of the first
``@chapters`` (note the ``s``) node in the outline.

One selects a chapter with the ``select-chapter`` command, after which Leo shows
only the nodes in the selected chapter; in this respect, chapters are like
hoists. The ``main`` chapter represents the entire outline and can not be
deleted by name. When chapters are in effect, Leo creates an ``@chapters`` node
for the use of ``create-chapter``.

Associated settings:

- The ``@bool use_chapters`` setting determines whether chapters are enabled.
- The ``@bool use_chapter_tabs`` setting determines whether the chapters
  pop-up menu appears in the icon area. Choosing a chapter name from this list selects a chapter.

When chapters are enabled, the Cmds-&gt;Chapters menu shows all available chapter commands:

- The ``chapter-create`` command creates an @chapter node and populates it with a single node.
- The ``chapter-remove`` command deletes the currently selected chapter.
- The ``chapter-select`` command prompts for a chapter name and makes only the nodes of the selected chapter visible.
- The ``chapter-move-node-to``, ``chapter-clone-node-to`` and ``chapter-copy-node-to`` commands
  prompt for a chapter name and add the currently selected node (and its descendants) to another chapter.
</t>
<t tx="ekr.20120320153011.6055">@language rest

.. What's new.
</t>
<t tx="ekr.20120320153011.6056">.. _`bug 800157`: https://bugs.launchpad.net/leo-editor/+bug/800157
.. _`bug 823267`: https://bugs.launchpad.net/leo-editor/+bug/823267
.. _`bug 875327`: https://bugs.launchpad.net/leo-editor/+bug/875327
.. _`bug 917814`: https://bugs.launchpad.net/leo-editor/+bug/917814
.. _`bug 875323`: https://bugs.launchpad.net/leo-editor/+bug/875323
.. _`bug 831658`: https://bugs.launchpad.net/leo-editor/+bug/831658

- Fixed several bugs related to selection following hoists &amp; chapters:

    - `bug 823267`_: When a tab is closed focus may go to a tab other than the visible one.
    - `bug 875327`_: Positioning outside of hoisted outline" usually causes problems.
    - `bug 917814`_: Switching Log Pane tabs is done incompletely.
    - `bug 875323`_: Hoist an @chapter node leaves a non-visible node selected.
    - `bug 831658`_: @url doesn't leave Chapter.

.. _`bug 951739`: https://bugs.launchpad.net/leo-editor/+bug/951739
.. _`bug 951721`: https://bugs.launchpad.net/leo-editor/+bug/951721
.. _`bug 944555`: https://bugs.launchpad.net/leo-editor/+bug/944555
.. _`bug 944551`: https://bugs.launchpad.net/leo-editor/+bug/944551
.. _`bug 893230`: https://bugs.launchpad.net/leo-editor/+bug/893230
    
- Fixed several bugs related to URL's:

    - `bug 951739`_: xdg-open of a file-scheme URL containing blanks.
    - `bug 951721`_: @url with URL in headline.
    - `bug 944555`_: Ctrl-left-click URL handling not as sophisticated as @url URL handling.
    - `bug 944551`_: @url URL Open Hangs Leo.
    - `bug 893230`_: URL coloring does not work for many Internet protocols.
    - Removed "significant" calls to os.system.
    - Added support for colorizing the following schemes:
      gopher,mailto,news,nntp,prospero,telnet,wais.
      
- Fixed several other serious bugs:
      
    - `bug 800157`_, an ancient hanger in paste-retaining-clones.
    - Fixed at serious read bug. Changed at.readEndOthers and at.readEndRef.
    - Fixed bug: @button @key=x does not override x.
    - Fixed the wretched scrolling bug.
    
- Fixed almost 70 minor bugs. For details, see the release notes.
</t>
<t tx="ekr.20120320153011.6808">.. _`quicksearch plugin`:  http://groups.google.com/group/leo-editor/browse_thread/thread/e0ad60ae319359df/e932052a1ef6e9f5
.. _`bigdash plugin`: http://groups.google.com/group/leo-editor/browse_thread/thread/f7eaf4dd4e84a535

- Improved the `quicksearch plugin`_.

- A new `bigdash plugin`_.

- Removed scrolledmessage plugin.

- The vim and xemacs plugins now work smoothly with contextmenu plugin.

- Supported auto-hide in viewrendered plugin.
</t>
<t tx="ekr.20120320153011.6826">- New settings:

    - @bool indent_added_comments
    - @color focus_border_color = red
    - @int focus_border_width = 1
    - @bool use_body_focus_border  = True
    - @bool use_focus_border = True
    
- Other changes:
    
    - Added show-decoration-selected: 1 to QTreeWidget stylesheet. This causes
      the entire headline row to be shown when selected.
    - Added stylesheets for Log &amp; Find tabs.
    - Eliminated the -c option.
    - New format for @openwith settings nodes. See leoSettings.leo for details.

- New search order for leoSettings.leo::

    1. leoSettings.leo in the home directories.
    2. &lt;machine-name&gt;leoSettings.leo in the home directories.
    3. leoSettings.leo in leo/config directory.

- New search order for myLeoSettings.leo::

    1. myLeoSettings.leo in the local directory.
    2. myLeoSettings.leo in the home directories.
    3. &lt;machine-name&gt;myLeoSettings.leo in the home directories.
    4. myLeoSettings.leo in leo/config directory.

- New default settings for run unit tests commands::

    run-marked-unit-tests-externally    = Alt-4
    run-selected-unit-tests-externally  = Alt-5
    
</t>
<t tx="ekr.20120320153011.8201">Small improvements the unit testing framework created big results. They
completely eliminate the overhead in running unit tests:

    - The run-marked-unit-tests-externally (Alt-4) command runs all marked
      @test nodes. To choose tests, just mark them.
    - Alt-4 now saves the .leo file first.
    - Almost all unit tests may now be run externally:
        - External unit tests always read config settings.
        - The nullGui now uses a fully capable string-based body widget.
        - The nullGui now uses the regular undoer.
    - Unit tests now always have the sources available.
    - Disabled messages on external unit tests.
    - The unit test commands always run a selected @test node.

These improvements mean that almost all unit tests may be run externally.
In turn, this creates a remarkable work flow::

    Edit
    Alt-4
    Edit
    Alt-4
    ...

The energy difference between weightless and heavy is astounding. Try the
new way: you will surely like it.

**Notes**:

Experience shows that being able to run the desired unit tests *without*
selecting any particular node makes an amazingly large difference. Being
able to run all and only marked unit tests is a big step forward.

If a marked node is neither an @test node nor an @suite node, all nodes in
the tree are considered to be marked.
</t>
<t tx="ekr.20120320153011.8400">- Weightless unit testing.

- Added the following commands::

    beautify-c
    c-to-python
    clone-find-all-flattened
    clone-marked-nodes
    delete-marked-nodes
    move-marked-nodes
    run-marked-unit-tests-externally
    run-marked-unit-tests-locally
    select-to-matching-bracket
    split-defs
    
- Improved the following commands::
    
    add-comments
    delete-comments
    open
    page-up
    page-down
    print-bindings
    print-commands
    rst3
    shell-command
    shell-command-on-region
    
.. _`The leoInspect Module`: http://leoeditor.com/leoInspect.html
    
- The leoInspect module allows scripts to interrogate static code.
  For full details, see `The leoInspect Module`_ chapter.
    
- Improved existing features:

    - Leo's File:Open With command now works with Qt
    - The new quick edit/save mode allows Leo to be a drop-in replacement for SciTe.
    - Detached windows.
    - A major improvements to Leo's abbreviation code.
    - Improved presentation of autocompletion list.
    - Applied patch for bug 800399: smart word jumps/deletes.

- Code improvements:

    - Most of Leo's core files now import just leo.core.leoGlobals.
    - Global switches are now all in leoGlobals.py.
    - version.py now uses bzr_version.py. Leo now reports bzr version numbers and dates automatically.
    - Unified the high-level interface &amp; eliminated the low-level interface.
    - Create properties for logCtrl &amp; bodyCtrl.
    - Added event filters to top-level frames.
    - Added g.app.isExternalUnitTest.
    - Added c.config.set.

- Created new classes::

    EditCommandsManager
    KeyStroke &amp; ShortcutInfo
    LoadManager
    TestManager
    
- Dozens of other new commands and features.

For details, see the release notes.
</t>
<t tx="ekr.20120320153011.8537">- Improved the create @auto nodes script.

- Added import-org-mode script.

- Added a script for displaying a function call hierarchy in Leo.

- Improved recursive import script.

- Created a script for replacing Qt stylesheets on the fly.

- Scripts to add bookmarks automatically.

- A new "magic refactor" button.

- Changed calling signatures of g.openWithFileName and g.app.newCommander.

- The open-with event now uses a "d" arg.

For full details, see the release notes.
</t>
<t tx="ekr.20120320153011.8551"></t>
<t tx="ekr.20130803073926.17120">target = '-- \nYou received this message because'
target = '--=20\nYou received this message because'
while p:
    s = p.b
    i = s.find(target)
    if i &gt; -1:
        p.b = s[:i]
        g.es(p.h)
    p.moveToThreadNext()
</t>
<t tx="ekr.20130807203905.16526">@language rest

When I study a program, I like to import it into Leo. I have several
scripts that do this: some create @auto nodes; others create @file nodes.
Whatever the method used, the import process has the potential to change
many files. Usually, I just change @auto and @file to @@auto or @@file, so
that any changes I make while studying the code won't affect the originals.

But this "safety first" approach means that I can't actually use Leo to
insert tracing statements (or for any other changes.) Happily, there is a
way to import "live" code into Leo safely::

   Create a bzr repository for the code before importing it

The Aha is to create the repository *wherever the code is*, including,
say, python/Lib/site-packages.

- bzr qdiff ensures that import hasn't significantly altered the code,
- bzr revert undoes any unwise or unwanted changes.

This is exactly what I need:  I can make changes to important tools
*safely* within Leo.
</t>
<t tx="ekr.20130807203905.16597">*Important*: Leo's binary Windows installer sets file associations
automatically, so this section is needed only if you are installing Leo
from a .zip file or other sources.

There are two ways of associating .leo files with Leo. The first uses the
Windows control panel, the second, the Windows console.

**Method 1: Using the Windows Control Panel**

The goal is that you want to associate .leo files with the following command::

    "&lt;path to python&gt;\python.exe" "&lt;path to launchLeo.py&gt;\launchLeo.py" "%1"
    
Before Windows 7, you do this with using the Folder Options control panel.
In Windows 7, you do this with the Default Programs control panel.

*Note*: "%1" passes just the file being clicked on, quoted for spaces etc.
The quotation marks are needed to handle file paths containing spaces.

*Warning:* In a batch file, %1 passes just the first command line parameter.
It is logical to expect %* to work for file associations just as in batch
files. Alas, it does not.

**Method 2: Using the Windows Console**

Open a Windows console with administrator privileges, then type::

    ftype LeoFile="&lt;path to python&gt;\pythonw.exe" "&lt;path to launchLeo.py&gt;\launchLeo.py" "%1" %*
    assoc .leo=LeoFile

And put this leo.bat in %PATH%::

    @start /b "Leo" "&lt;path to python&gt;\python.exe" "&lt;path to launchLeo.py&gt;\launchLeo.py" %*
    
You may omit the /b option if you want to create a separate console window for Leo.
</t>
<t tx="ekr.20130807203905.16602">Leo has a binary installer for Windows, available at
http://sourceforge.net/projects/leo/files/Leo/ The binary installer
installs Leo and sets Windows file associations. Now see `Running Leo`_ for
how to run Leo after installing it.
</t>
<t tx="ekr.20130807203905.16603">You may download Leo's sources in one of three ways, as described at:
http://leoeditor.com/download.html If the sources are zipped, unpack them
into a temp folder. You may place the sources anywhere you like, including
Python's \*site-packages* folder, for example,
C:\\Python26\\Lib\\site-packages.

Next, you will find it convenient to create Windows files associations for
.leo files, as described in the next section.
</t>
<t tx="ekr.20130815102041.15618">This plugin supports printing using the Qt GUI.
Written by Jacob M. Peck.
</t>
<t tx="ekr.20130815102041.15619"></t>
<t tx="ekr.20130815102041.15628">By Ville M. Vainio
See: http://en.wikipedia.org/wiki/Mylyn

I went on to start a "leo mylyn" plugin to exercise using the
childrenModified and contentModified signals.

If you want to play with it, enable leomylyn.py, modify stuff around the
tree and do alt-x mylyn-scores.

Of course as it is useless in this state, but becomes useful when it has a
proper gui (maybe in Nav pane), where you would then have a list of "most
interesting" nodes.

In the future, this could be able to remember the scores through the
sessions, degrade the old scores by time, etc. Also, a scoreset would be
associated with a "project" (e.g."own research", "work project foo"), each
of them having their own typical node working set.

Mylyn was a nice boost back in the eclipse days, it could work for Leo too.
My main motivation right now was to demonstrate the signals with something
that is much simpler than using them in qmlnotebook.

</t>
<t tx="ekr.20130815102041.15630">By Terry Brown.

See http://leo-editor.github.io/screen_capture.html

screen_capture now captures an image immediately, screen_capture_5sec waits
five seconds, so you can position the pointer, open menus etc. The only
feedback is in the console, as messages in the log would be distracting in
the captured image.
</t>
<t tx="ekr.20130815102041.15631">By Edward K. Ream

Screencasts promise to be easy to be *much* easier to create than 
slideshows, while also being more interesting, informative and flashy.  It 
is *so* much easier to write a screencast script than it is to lay out a 
slide, take a screenshot, and then manage resulting slide.

In particular, there are few continuity problems with screencasts.  
Continuity is a *huge* problem with slideshows!  If I change one slide, I 
am likely to want to change all following slides.  Which means I have to 
retake all the slides, and file the new versions in the proper places.  In 
contrast, any changes to screencasts naturally propagate forward.  There 
might be an effect on following screencasts scenes, but this will happen 
rarely with a reasonable scene design, and any problems should be easy to 
fix.

With screencasts, the *movie* script is also the *python* script!  There is 
no "translation" from one to the other.  Furthermore, all the work to 
produce a screencast is done (naturally!) within Leo.  No need to create 
and manage external data.  This is another huge advantage and it make 
producing screencasts much faster than producing slideshows.

Screencasts may be the long-awaited tools that will allow me to show Leo in
action so that other will finally be able to understand it easily.
</t>
<t tx="ekr.20130815102041.15632">By Kent Tenney

The timestamp plugin manages the following node attributes:

- str_ctime: creation time
- str_mtime: time node was last modified
- str_atime: time node contents were last viewed
</t>
<t tx="ekr.20130816100419.17299">The default language if no @language or @comment is in effect.

Valid values are (case is ignored):

actionscript,c,csharp,css,cweb,elisp,html,java,latex,
pascal,perl,perlpod,php,plain,plsql,python,rapidq,rebol,shell,tcltk.</t>
<t tx="ekr.20130926053913.15854">Leo 4.11 b1                                     September 26, 2013

Leo 4.11 b1 is now available at: http://sourceforge.net/projects/leo/files/Leo/
Leo 4.11 contains over a year's work on Leo.

Leo is a text editor, data organizer, project manager and much more.
See http://leoeditor.com/tutorial.html

The highlights of Leo 4.11:
---------------------------

- Greatly improved abbreviations.
- Clones are now valid anywhere in @file nodes.
- Leo now warns if a .leo file is open elsewhere.
- Added support for sessions
- Added colorizing themes.
- A colored border highlights the pane with focus.
- Added support for the clojure, markdown and TypeScript languages.
- Added importers for .ipynb, .otl and vimoutliner files.
- Many new and improved plugins.
- Dozens of new scripts.
- Dozens of improved commands.
- Dozens of bug fixes and code-level improvements.

Links:
------
Leo:      http://leoeditor.com
Forum:    http://groups.google.com/group/leo-editor
Download: http://sourceforge.net/projects/leo/files/
Bzr:      http://code.launchpad.net/leo-editor/
Quotes:   http://leoeditor.com/testimonials.html
</t>
<t tx="ekr.20130926053913.16131"></t>
<t tx="ekr.20130926053913.16132"></t>
<t tx="ekr.20130926053913.16133">This was a recent problem.  Normally setInputState should *not* set the border.

Added code to eventFilter to call remove_border on focus out.

set-xxx-state commands call setInputState with set_border = True.
</t>
<t tx="ekr.20130926053913.16134">The fix was in qtBody.setWrap.
</t>
<t tx="ekr.20130926053913.16135"># The change was to g.getScript.
</t>
<t tx="ekr.20130926053913.16136">The trick is to find the wrapper first: it is *also* a QMenu.
We can then call menuBar.setActiveAction on its action!!
</t>
<t tx="ekr.20130926053913.16137">https://bugs.launchpad.net/leo-editor/+bug/1021849

Rev 5789 fixes this bug, using some hints from the NSIS support forum.

The fix was to CreateShortCut in the Desktop Shortcut section:
  - remove single quotes.
  - remove the "0" trailing arg.

The installer passes all my tests on my Windows 7 machine, which is all the testing I have ever done.


Here is the checkin log::

QQQ
Fixed the icon problem and improved and simplified the install/uninstall 
process in several ways.

1. Fixed https://bugs.launchpad.net/leo-editor/+bug/1021849

The fix was to CreateShortCut in the Desktop Shortcut section:
  - remove single quotes.
  - remove the "0" trailing arg.

2. Changed the make-leo button to simplify the uninstall manifest.

Rather than computing the files to be deleted, the uninstall script now 
just does RMDir /r "$INSTDIR\\leo".
This *is* safe, and ensures that all files &amp; directories get deleted, 
including $INSTDIR itself.
QQQ

The only possible drawback to using the /r option is that it will delete 
any files that the user has created in the leo directory.  Imo, there is no 
perfect solution to this.  Warning prompts never do any good, and if we 
retain files, for whatever reason, there will be bug reports saying that 
Leo didn't properly uninstall itself.  This has already happened :-)

I am happy to live with the present situation, unless somebody a) objects 
loudly and b) shows how the problem can be solved cleanly.
</t>
<t tx="ekr.20130926053913.16138">https://bugs.launchpad.net/leo-editor/+bug/1194209

save-as doesn't update the window title.  Changing tabs does.

The main fixes were to qtFrame.get/setTitle. When using tabs, the
LeoTabbedTopLevel widget is the top-level window, *not* the DynamicWindow
(a QMainWindow).

Another fix was setting c.frame.title in saveAs to::
    
    c.computeWindowTitle(c.mFileName)
    
This ensures that all all window titles have the same format.

I chose to do the bare minimum fix, confined to g.computeWindowTitle::

    if os.sep in '/\\':
        title = title.replace('/',os.sep).replace('\\',os.sep)

I didn't have the nerve to put similar code in, say, g.os_path_join. The
Python docs for os.path.join state, "In all cases, join(head, tail) returns
a path to the same location as path (but the strings may differ)."

</t>
<t tx="ekr.20130926053913.16139">https://bugs.launchpad.net/leo-editor/+bug/879338

Having the colorizer colorize a language properly gives the false illusion
that Leo "understands" the language.

Supporting the language in the global tables in leoApp.py makes the
illusion a reality.

Rev 5334 is a first draft of a fix of bug 879338:
Global tables in leoApp.py should describe all languages known to the colorizer
https://bugs.launchpad.net/leo-editor/+bug/879338

The essence of the bug fix is that Leo's language-description tables should
contain entries for all .py files in the leo/modes folder. These files
control the colorizer. If Leo's colorizer knows about a language, then Leo
should know as much as possible about the language.

In concept, this is a fairly straightforward process, but there were *many*
details to handle. If you aren't a Leo developer, you might want to stop
reading now...

===== Tables

Fixing this bug required non-trivial changes to the following tables::

    g.app.language_delims_dict
    # Keys are languages, values are 1,2 or 3-tuples of delims.

    g.app.language_extension_dict
    # Keys are language names, values are extensions.

    g.app.self.extension_dict
    # Keys are extensions, values are language names

I used scripts to generate new entries for these tables, but these scripts
can not possibly deal with the all the complications...

Leo uses these tables as follows:

1.  To generate the comment delimiters in sentinels for each language.

Happily, getting the comment delimiters correct was probably the easiest
part, so Leo should continue to write sentinels properly for
previously-know languages. However, I had to take care to preserve the REM,
CWEB, forth and perlpod hacks, so that comment delims would include the
necessary spaces.

2. To associate file extensions with importers.

Knowing about new file extensions doesn't actually allow Leo to import any
new languages. For all languages without an official importer Leo will
simply copy the entire text of the file into a single node, as it always
has.

3. To colorize code.

Leo's colorizer mostly doesn't use these tables: to colorize language x,
the colorizer looks for the file leo/modes/x.py. Thus, these changes
probably do not affect the colorizer at all.

===== Special cases

I did a lot of googling in order to determine the proper file extensions to
use for various language. In the process, I learned that *almost* all
languages described in the leo/modes folder are real, interesting and
useful languages.

However, there at least 5 categories of special cases that affect the
tables:

1. Languages that are really just colorizer modes:

These include embperl, pseudoplain and phpsection. We need entries in
leo/modes for these, but they aren't real languages and thus they should
not appear in the language-description tables.

2. Things that might be colorized but aren't real languages.

Afaik, the following are not real languages, and Leo would never have to
generate files in these languages: cvs_commit,dsssl,relax_ng_compatc and svn_commit.

Notes:

- relax_ng_compact is an xml schema.

- The rtf colorizer is *not* a colorizer for binary .rtf file format, is a
  colorizer for .rtf sources. It probably won't do too much harm to retain
  the colorizer data for these languages, but I wouldn't mind eliminating
  them either.

3.  Unknown languages.

A few languages seem not really to exist: freemarker, hex, jcl, progress, props.

4. Languages without real comment delimiters.

Patch annotations are *not* real comment delimiters, so Leo could not
generate patch (.fix or .patch) files from an outline. Happily, there is no
need to do so.

5. Conflicting file extensions.

There are two separate kinds of problems:

A. Leo contains colorizers for several assembly languages. Typically,
assembly languages have .asm or .a file extensions. However, a particular
extension can only be associated with a single language name. Thus, Leo has
no way of knowing what language to associate with .asm or .a files. So I
just punted and didn't make any association at all.

B. Both the rebol and r languages use the .r file extension. One of Leo's
users previously created an entry for rebol, so that's the language that
takes precedence.
</t>
<t tx="ekr.20130926053913.16140">https://bugs.launchpad.net/leo-editor/+bug/971171

If If $(HOME)/.leo/.leoRecentFiles.txt does not exist,
the only recent file ever is the current file

The fix: rf.writeRecentFilesFile creates $(HOME)/.leo/.leoRecentFiles.txt if it does not exist.
</t>
<t tx="ekr.20130926053913.16141">https://bugs.launchpad.net/leo-editor/+bug/981849

The original fix was misguided. It attempted to use more careful code in
setSelectionRangeHelper &amp; lengthHelper.
    
The new fix avoids messing with the viewport in both setEditorColors methods:

leo-editor thread: opening new top level windows
http://groups.google.com/group/leo-editor/browse_thread/thread/8f5f6c72d8716b33

The key is to use a descriptor in LeoQTextBrowser stylesheets.  Example::

'LeoQTextBrowser { &lt;&lt; the actual stylesheet &gt;&gt; }

See http://stackoverflow.com/questions/9554435/qtextedit-background-color-change-also-the-color-of-scrollbar


    
</t>
<t tx="ekr.20130926053913.16142">https://bugs.launchpad.net/leo-editor/+bug/998090
save file as doesn't remove entry from open file list

Save file as leaves the file's previous path in g.app.db.openFiles, so
that next time the original file's opened you get a "already open"
message.
</t>
<t tx="ekr.20130926053913.16143">The bug was in chapter.findPositionInChapter.
</t>
<t tx="ekr.20130926053913.16144">These bugs are really the same bug

Node body contents displayed is unpredictably incorrect
https://bugs.launchpad.net/leo-editor/+bug/979142

Prints to tabs in the Log Pane are UTF-8 encoded
https://bugs.launchpad.net/leo-editor/+bug/971166

The fix was:

1. Use the "slow" code in leoQTextEditWidget.get.
2. Use w.get/setAllText in leoFrame.pasteText.
</t>
<t tx="ekr.20130926053913.16145"></t>
<t tx="ekr.20130926053913.16146"></t>
<t tx="ekr.20130926053913.16147">Traceback (most recent call last):
  File "c:\leo.repo\trunk\leo\core\leoCommands.py", line 553, in doCommand
    val = command(event)
  File "c:\leo.repo\trunk\leo\core\leoCommands.py", line 2120, in flattenOutline
    c.importCommands.flattenOutline(fileName)
  File "c:\leo.repo\trunk\leo\core\leoImport.py", line 479, in flattenOutline
    theFile.write(s)
TypeError: must be str, not bytes
</t>
<t tx="ekr.20130926053913.16148">The crash happens only when the new readSettings argument to leoBridge.bridgeController is False.
In that case, the global dicts were not inited properly.

What I did:
    
- Created lm.createDefaultSettingsDicts, called by lm.readGlobalSettingsFiles.
- leoBridge.initLeo calls lm.createDefaultSettingsDicts to set the global dicts.

Bug description:

--- Begin Python script to run from a console ------
import leo.core.leoBridge as b
bridge = b.controller(gui='nullGui',verbose=False,loadPlugins=False,readSettings=False)
c = bridge.openLeoFile(r'c:\users\edreamleo\test\minimal.leo')
--- End Python Script -----

The above script and minimal.leo are attached to this bug report.  Put
them in the same directory, open a console, set the current working
directory to the directory containing the script, and run the script.
You will see the this exception on the console:

2012-11-16 11:28:51 /home/ldi/tmp
$ python readSettingsFalse.py
Traceback (most recent call last):
File "readSettingsFalse.py", line 5, in &lt;module&gt;
  cmdrUnl = bridge.openLeoFile('minimal.leo')
File "/home/ldi/bzr/LeoLatest/leo/core/leoBridge.py", line 330, in openLeoFile
  c = self.createFrame(fileName)
File "/home/ldi/bzr/LeoLatest/leo/core/leoBridge.py", line 367, in createFrame
  c = g.openWithFileName(fileName)
File "/home/ldi/bzr/LeoLatest/leo/core/leoGlobals.py", line 1875, in openWithFileName
  return g.app.loadManager.loadLocalFile(fileName,gui,old_c)
File "/home/ldi/bzr/LeoLatest/leo/core/leoApp.py", line 2539, in loadLocalFile
  previousSettings = lm.getPreviousSettings(fn)
File "/home/ldi/bzr/LeoLatest/leo/core/leoApp.py", line 1668, in getPreviousSettings
  lm.globalSettingsDict,lm.globalShortcutsDict,localFlag=True)
File "/home/ldi/bzr/LeoLatest/leo/core/leoApp.py", line 1626, in computeLocalSettings
  settings_d = settings_d.copy()
AttributeError: 'NoneType' object has no attribute 'copy'
2012-11-16 11:28:55 /home/ldi/tmp
$
</t>
<t tx="ekr.20130926053913.16149">Note: happens only with Python 3.3.0.

Here is a minor traceback when opening quickstart.leo

Leo 4.11 devel, build 5468, 2012-09-30 13:02:59
Python 3.3.0, qt version 4.8.3
Windows 6, 1, 7601, 2, Service Pack 1
reading: C:\Python33\Lib\site-packages\leo-editor\leo\doc\quickstart.leo
unexpected exception in g.importFromPath(rest)
Traceback (most recent call last):
  File "C:\Python33\Lib\site-packages\leo-editor\leo\core\leoGlobals.py", line 5689, in importFromPath
    data = imp.find_module(moduleName,[path]) # This can open the file.
  File "C:\Python33\lib\imp.py", line 203, in find_module
    package_directory = os.path.join(entry, name)
  File "C:\Python33\lib\ntpath.py", line 171, in join
    if b[:1] in seps:
TypeError: Type str doesn't support the buffer API
Can not import rest
</t>
<t tx="ekr.20130926053913.16150">The @test at.readOneAtShadowNode retains @shadow links node
give fail1: test not set up properly.
The outline is then corrupted, causing other unit tests to fail.
The partial solution is not to call the undo command in the finally clause.
</t>
<t tx="ekr.20130926053913.16151">https://groups.google.com/group/leo-editor/browse_thread/thread/bb063866875a81c3/6162e6108b09428e

The new code is much like g.computeFileUrl.
</t>
<t tx="ekr.20130926053913.16152">** Not all import problems can be fixed automatically! **

- Added perfectImportFlag. (There was already an importing flag).

- Fixed bug in Fixed underindent convention:

    undentBy adds a period; parseUnderindentTag removes the period.
    
- @file read code must *regenerate* the \\- convention.

    This is done by readNormalLine.
    
    - Fixed an unrelated bug in g.computeWidth.  All unit tests pass.

    - Created g.computeLeadingWhitespaceWidth.
    
- some docstrings are not imported properly in py2_test_grammar.py

    The must be fixed by hand, using @raw and @end_raw.

- escapeFalseSectionReferences now is a do-nothing:
    
    It never generates @verbatim sentinels during import.
    
===== Notes

Rev 5378: cleanup-imported-nodes script in scripts.leo &amp; an Aha
http://groups.google.com/group/leo-editor/browse_thread/thread/77b9df4f4ed6dba0

&gt; The third (and I think last) import fail involves not generating
&gt; @verbatim sentinels when importing files.

Fixed in the trunk at rev 5386.

This is (to me) a really interesting dark corner of Leo's import code.

By searching for @verbatim, I discovered a method called
escapeFalseSectionReferences.  This method inserts an @verbatim
"directive" before lines that look like section references.

This is wrong for multiple reasons.  It confuses the importer, there
is no such thing as an @verbatim directive, and worst, it fails to
solve the essential problem, which is that before the imported file is
saved, the **user** must fix the problem!

For example, when importing a line like::

  a = x &lt;&lt; y &gt;&gt; z

The user, and *only* the user, should change this to something like::

   a = x &lt;&lt; y \
   &gt;&gt; z # EKR

I suppose each importer could figure out a language-specific
workaround, but imo this isn't particularly important, for reasons
which will become clearer below.

So now escapeFalseSectionReferences is a do-nothing.

With this explanation, perhaps the checkin log will make sense::

QQQQQ
Fixed another import fail in an "interesting" way: the import code no
longer inserts @verbatim. This means a later write of the imported
will fail. This is correct!

Indeed, the failed write is the only way to alert the user that the
code must be revised by hand.

Note that another import fail, involving a leading '@' on a line in a
docstring, must also be fixed by hand. In lib2to3/pgen/grammar.py the
*only* possible fix is to enclose the entire docstring at the end of
the file by @raw and @end_raw.

All unit tests pass, but no new tests have been added so far.
QQQQQ

The other import fail mentioned in the checkin log is a truly
fascinating case, one that no amount of AI could possibly discover the
correct fix.

At the very end of lib2to3/pgen/grammar.py the following code
(shortened a bit) appears at the top level::

   opmap_raw = """
   ( LPAR
   ) RPAR
   [snip]
   @ AT
   [snip]
   == EQEQUAL
   != NOTEQUAL
   """
   opmap = {}
   for line in opmap_raw.splitlines():
       if line:
           op, name = line.split()
           opmap[op] = getattr(token, name)

There are several things to notice about this code:

1. It contains a line starting with '@'.  Sooner or later, this is
going to cause problems for either Leo's import code or Leo's write
code.

2. It's overly clever, but it's overly clever for a reason: it's
testing tokenizing logic.

3. The code at the end of the file assumes that all lines of the
docstring are 2-tuples.

For these reasons, the one and *only* possible way to make Leo write
this code correctly is to enclose the *entire* docstring in @raw and
@end_raw directives.  Like this::

   @raw
   opmap_raw = """
   ( LPAR
   ) RPAR
   [snip]
   @ AT
   [snip]
   == EQEQUAL
   != NOTEQUAL
   """
  @end_raw

In particular, surrounding the line "@ AT" with @raw/@end_raw
directives will cause 2to3 to fail on startup:  the Leo sentinel lines
will not be 2-tuples!

===== Important Conclusions

All this picky detail illustrates a crucial fact.  No matter how good
Leo's importers are, (and they are now quite good), there will
*always* be cases where thoughtful human intervention will be
required.

Furthermore, the simplest thing that could possibly work is for the
importers to allow some constructions that are guaranteed to cause
problems later, when the user attempts to write the file.  We hope
that Leo will complain about certain constructions, but Leo may not be
able to complain about all constructions.

Thus, some import mistakes can *only* be found by running tests.  For
complex programs like 2to3, the only truly safe way to check imports
is by running the 2to3 test suite.
</t>
<t tx="ekr.20130926053913.16153">The fix was to always call c.selectPosition in leoFind.showSuccess.
This ensures that leoTree.setBodyTextAfterSelect always does w.setAllText,
which is essential to init the syntax colorer properly.

The happy side effect of this change is that a lot of duplicate selection
code in showSuccess disappears.

Also converted two section references in leoTree.selectHelper to selectNewNode.
</t>
<t tx="ekr.20130926053913.16154">http://groups.google.com/group/leo-editor/browse_thread/thread/bb063866875a81c3#

In my installation, now on the latest revision ( r5195) I'm still
experiencing an issue with the '@url command' using 'File-URL' in a Windows
environement.

I'm able to create the Leo User documentation locally. - However, when I
try to read the documentation using the 'File-URL'

file:///D:/Branches/leo-editor/leo/doc/html/_build/html/leo_toc.html

I get the following message in the Leo-Log.

&lt;log&gt;

File 'D:\D:\Branches\leo-editor\leo\doc\html\_build\html\leo_toc.html' does not exist

&lt;/log&gt;

However if I enter this URL directly into FF it is found and displayed properly.

EKR: Obviously, the 'D:\D:\' is the problem.

The fix is simply to special-case file:/// on Windows in g.computeFileUrl.
</t>
<t tx="ekr.20130926053913.16155">LeoQTextBrowser.onSliderChanged must set v.scrollBarSpot only if "self" is actually the body pane.

Othewise scrolling the log pane will scroll the body pane!
</t>
<t tx="ekr.20130926053913.16156">The maintain_scroll option is *evil*.
</t>
<t tx="ekr.20130926053913.16157">An assert failed during scanning in mungeAllFunctions.

Added defensive code to mungeAllFunctions, dedentBlocks and
replaceComments. The new code simply increments a pointer if a "progress"
assert would fail. (The progress assert still exists, as a double-check.)

Fixed bug: the call to u.afterChangeGroup in the go() method is called only once.

Suppress warning messages given by CPrettyPrinter.indent.
</t>
<t tx="ekr.20130926053913.16158">If the user has not typed anything in the minibuffer, &lt;alt-x&gt;&lt;tab&gt; returns *all* completions.

Otherwise, if there are no completions, the "Completions" tab is empty, *not* all completions.

This behavior is much more intuitive than the old behavior.

The fix was a new special case in k.computeCompletionList.
</t>
<t tx="ekr.20130926053913.16159"># The fix was simply to call c.endEdiing in undo and redo *before* getting the undo params.
# This allows c.endEditing to properly set the undo stack.
</t>
<t tx="ekr.20130926053913.16160">dw.createFindTab now creates a third column with a minimum width.
The find/change text widgets span the second and third columns.
</t>
<t tx="ekr.20130926053913.16161">Don't show full completion list when the minibuffer becomes empty.
</t>
<t tx="ekr.20130926053913.16162">http://groups.google.com/group/leo-editor/browse_thread/thread/dd16ac6dc1832eb2

bookmarks.py was the culprit. The code in onCreate must test to see if c.free_layout already exists.
</t>
<t tx="ekr.20130926053913.16163"></t>
<t tx="ekr.20130926053913.16164"># Changed: onActivateEvent (qtGui), onDeactivateEvent (qtGui)
</t>
<t tx="ekr.20130926053913.16165">Added code to findAllUnitTestNodes to look up the tree for @test &amp; @suite nodes
if none have been found so far.  Only for the run-unit-tests-externally/locally.
</t>
<t tx="ekr.20130926053913.16166"></t>
<t tx="ekr.20130926053913.16167">A shock: p.deletePositionsInList must be rethought and rewritten
https://groups.google.com/forum/#!topic/leo-editor/IWMWhUlkos0
</t>
<t tx="ekr.20130926053913.16168">The fix was to set new_c=self.c in the call to c.close in createFileFromOutline.
</t>
<t tx="ekr.20130926053913.16169">If an assert fails, the entire file is read into a single node.
</t>
<t tx="ekr.20130926053913.16170">https://bugs.launchpad.net/leo-editor/+bug/903640
Import of Python files containing the strings "&lt;&lt;" and "&gt;&gt;" does not work

At present @auto can import .py files containing self.cprint("&lt;&lt;" + ret +
"&gt;&gt;\n")

Furthermore, it's possible to write such files properly after changing
them.

Thus, this bug seems to have been completely fixed, as far as @auto goes.

However, *importing* the file with Leo's import-file command does fail (an
@ignore is inserted). This is expected: unlike @auto, the import command
creates an @file node, so the "perfect import" check will complain that the
section called &lt;&lt; ret &gt;&gt; is undefined.

I am going to close this item. I see no real need to support other section
delimiters in external files. If there ever becomes a real need to do so, a
separate wishlist item will be appropriate.
</t>
<t tx="ekr.20130926053913.16171"></t>
<t tx="ekr.20130926053913.16172">Rev 5840 adds support for hack that is active only on Ubuntu systems.

When Leo starts up, it creates a commander (tab) called "loading..." before
loading all tabs. This ensures that the first "real" .leo file loaded (into
a tab) will have a menu area. This tab exists only until the first real
.leo file is loaded.

Yes, this is a pretty horrible hack, but it seems necessary on Ubuntu
Unity. Presumably this is a Qt or Unity problem, but there has been
response to previous bug reports, so it seems that best that can be done.

</t>
<t tx="ekr.20130926053913.16173">This was a horrible kludge in LM.doPostPluginsInit
</t>
<t tx="ekr.20130926053913.16174">Changes in rev 4163 caused the bug.

The problem is the call to w.setStyleSheet in g.app.gui.update_style_sheet.
Apparently, this causes a layout-request event that spoils the scroll position.

The fixes:
    
1. update_style_sheet does nothing if the new stylesheet is the same as the old.

2. Added lockout to mouseReleaseEvent. update_style_sheet does nothing if
   the lockout is set.
   
3. mouseReleaseEvent sets c.p.v.insertPoint if appropriate.

Hitting Ctrl-H can still cause a small unwanted scroll, but the insert point remains visible.
</t>
<t tx="ekr.20130926053913.16175">https://bugs.launchpad.net/leo-editor/+bug/1184855

The fix was to set the name of the .leo file to foobar.pyxxx.leo in LM.initWrapperLeoFile.
</t>
<t tx="ekr.20130926053913.16176">Selecting body editor with clicks doesn't save/restore visual ivars.
The solution would be to create a new onClick event handler...

- Removed insert=None,new_p=None args from all versions of setAllText.
  These are entirely misguided, and may have contributed to scrolling problems.
  
  setAllText now *only* sets text, nothing else!

- All calls to leoMoveCursorHelper are follwed by code that updates
  v.insertSpot, v.selectionStart and v.selectionLength.
  
- v.restoreCursorAndScroll now *carefully* restores selection
  based on v.insertSpot, v.selectionStart and v.selectionLength.
  It also restores the scrollbar using v.scrollBarSpot.
  
- &lt; &lt; unselect the old node &gt; &gt; (selectHelper) now *only*
  sets v.scrollBarSpot.
</t>
<t tx="ekr.20130926053913.16177"></t>
<t tx="ekr.20130926053913.16178">https://groups.google.com/forum/#!topic/leo-editor/IWMWhUlkos0

There has been much discussion recently about deleting lists of positions.
I now see that all previous strategies are fatally flawed. This is quite
shocking.

Here is the Aha: the positions passed to p.deletePositionsInList only
*specify* the desired changes; the only way to *make* those changes is to
operate on vnodes!

The new view of the problem is relatively straightforward. Consider this
very simple outline, containing no clones::

    + ROOT
      - A
      - B

The fundamental problem is simple. If we delete node A, the index of node B
in ROOT.children will change. This problem has (almost) nothing to do with
clones or positions.

To make this concrete, let's look at the *vnodes* that represent this tree.
It is the vnodes, and *not* the positions, that represent all of Leo's
data. Let ROOT, A and B be the vnodes corresponding to the nodes ROOT, A
and B. ROOT.children will look like this at first::

    ROOT.children = [A,B]

That is, the children array contains references (links) to both A and B.
After deleting A, we will have::

    ROOT.children = [B]

As you can see, the reference to B is at index 1 of ROOT.children before
deleting A, and at index 0 of ROOT.children after deleting A. Thus, *any*
position referring to B will become invalid after deleting A.

Several people, including myself, have proposed an unsound solution--just
delete positions in reverse order, so that B will be deleted before A. This
idea has appeal, but it truly *is* unsound. Here is an outline that at last
explodes the notion that there is *any* correct order for deleting
positions. All A' nodes are clones of each other::

    + ROOT
      + A'
        - B # at position p1
      + A'
        - B # at position p2

**Important**: B is *not* a clone. Also note that there is only *one* node
called A and *one* node called B. The children arrays will look like::

    ROOT.children = [A,A]
    A.children = [B]
    B.children = []

It surely must be reasonable to pass either *or both* positions p1 and p2
to p.deletePositionsInList. But after deleting the B corresponding to p1,
the children arrays will look like:

    ROOT.children = [A,A]
    A.children = []
    B.children = [] # B is no longer referenced anywhere!

So if p.deletePositionsInList attempts to delete position p2 (from A), B
will no longer appear in A.children!

There are many other cases that we could discuss, but the conclusion in all
cases is that we must use the positions passed to p.deletePositionsInList
only as *hints* about what to do.

Happily, there is a simple strategy that sidesteps all the difficulties:

Step 1. Verify, *before* making any changes to the outline, that all the
positions passed to p.deletePositionsInList *initially* make sense.

Step 2. Treat each position as a "request" to delete *some* vnode from the
children array in the *position's* parent vnode.

This is just a bit subtle. Let me explain it in detail.

First, recall that vnodes do not have unique parent vnodes. Because of
clones, a vnode may may have *many* parents. Happily, every position *does*
specify a unique parent (vnode) at that position.

Second, as shown above, there is no way to order positions such that all
later positions remain valid. As the example above shows, deleting (the
vnode corresponding to) a position P may cause *all* later positions
referring to P.v to refer to *already deleted* vnodes.

In other words, we simply *must* ignore the child indices in positions.
Given a position P, P.parent is well defined. So Step 2 above will simply
delete the *first* element in P.parent.children containing P.v.

As we have seen, there may not even *be* any such element of
P.parent.children: a previous delete may have already deleted the last item
of P.parent.children equal to P.v. That should *not* be considered an
error--Step 1 has ensured that all positions *originally* did make sense.

Summary

Positions passed to p.deletePositionsInList specify *vnodes* to be deleted
from specific parents, but they do *not* specify at what index in the
parent.children array (if any!) those vnodes are to be found. The algorithm
will delete the *first* item in the children array that references the
vnode to be deleted.

This will almost always be good enough. In the unlikely event that more
control is desired, p.deletePositionsInList can not possibly be used.

The new emphasis on vnodes at last puts the problem an a completely solid
foundation. Moreover, the new algorithm should be considerably faster than
the old: there is no need to sort positions.
</t>
<t tx="ekr.20130926053913.16179"></t>
<t tx="ekr.20130926053913.16180"></t>
<t tx="ekr.20130926053913.16181">http://groups.google.com/group/leo-editor/browse_thread/thread/93f2cc88ebbf9893
</t>
<t tx="ekr.20130926053913.16182"></t>
<t tx="ekr.20130926053913.16183">If off, only the insert point is restored.

It's kinda pointless to make this a user option.
</t>
<t tx="ekr.20130926053913.16184">Extensions is a convenient place: code can use g.importExtension to import it.

Alas, sh.py can not be used in Leo's core.
</t>
<t tx="ekr.20130926053913.16185">The format of such local suppressions is::

    # pylint: disable=&lt;message-number&gt;
</t>
<t tx="ekr.20130926053913.16186">The new code works like leoTree.onHeadChanged.

The code can be called twice, so it is a bit tricky
to only issue warnings once.
</t>
<t tx="ekr.20130926053913.16187"></t>
<t tx="ekr.20130926053913.16188"></t>
<t tx="ekr.20130926053913.16189">A few changes that should have been done long ago:

- Added support for 'before' keyword.  Prints something before the function name.
- Use g.shortFileName(__file__) instead of "&lt;module&gt;"
</t>
<t tx="ekr.20130926053913.16190"></t>
<t tx="ekr.20130926053913.16191">Remove all .xml files in the leo/modes directory.

Imo, this should have been done long ago, for at least the following
reasons:

- These files are part of the jEdit project.
- They are used only by the jedit2py script in scripts.leo.
- The colorizer doesn't use them.
- Bug fixes to the colorizer are made to the .py files, not to the .xml files.
- We can always get updated versions of the .xml files from the jEdit
  project in the unlikely event that we ever need them again.

2. Remove the following .py files from the leo/modes directory:
cvs_commit.py, dsssl.py, freemarker.py, hex.py, jcl.py, progress.py,
props.py and svn_commit.py.

Notes:

- embperl.py, phpsection.py and pseudoplain.py will *not* be removed;
they are internal colorizer states.

- relax_ng_compact.py will be removed if it is not used by any other
colorizer.

- patch.py and rtf.py colorizers will be retained, even though Leo can
never generate such files. 
</t>
<t tx="ekr.20130926053913.16192"></t>
<t tx="ekr.20130926053913.16193">You can get this branch here: https://code.launchpad.net/~leo-editor-team/leo-editor/contrib
</t>
<t tx="ekr.20130926053913.16194">By Ville M. Vainio.

I created a proof of concept for dumping leo trees to excel.

Demo outline is in collab branch,

/Projects/excel_integration

Screenshot attached.

My usage is that I collect and organize findings (of technology studies) in
leo, and then dump the report to excel, to be read and actioned upon by
other ppl.

I haven't yet polished this workflow in that there is a bunch of manual
work in formatting the report...
 
</t>
<t tx="ekr.20130926053913.16195">Apart from the full text search indexing script I just added, I've made
a bunch of basically cosmetic changes to Ville's multi outline full text
search tool.  There's a new @setting, @int fts_max_hits, which controls
the max hits returned, instead of the hardwired default of 30.

With any sensible value for fts_max_hits, searches for terms which
generate many hits in many outlines won't return the full list of
outlines containing hits, because the search stops when fts_max_hits is
reached.  I set fts_max_hits to a non-sensible 1200 to get around this,
it seems to work fine.  Obviously terms which generate that many hits
are bad search terms anyway, but it's helpful to get as close to the
full list of outlines containing hits as possible.

Also most of my changes apply only to the "f target" find command, not
the simpler "s target" search command.
</t>
<t tx="ekr.20130926053913.16196">From Ville:

aaaaand we are live :).

Test it out at:

http://koti.kapsi.fi/vivainio/t/LeoReader/main.html

Sources here:

https://github.com/vivainio/LeoReader

Pretty much all the relevant stuff is in these files:

https://github.com/vivainio/LeoReader/blob/master/leoaccess.coffee

https://github.com/vivainio/LeoReader/blob/master/main.html

Works ok in Firefox and Chrome.
</t>
<t tx="ekr.20130926053913.16197">By Ville M. Vainio

Ok, I now created a toy UI demo for how "cell" based leo (like ipython
notebook) could operate.

qmlnotebook.leo (ctrl+b script + test outline) is now at contrib branch. If
you want to try it, open the .leo file, ensure you are running latest Leo
from trunk, and press ctrl+b on the first node.

It's probably the first stab at using QML to solve a problem in Leo. It
doesnt' run from leo yet (it's not a plugin, more protoing needed before
it's worthwhile to make it a plugin.

When you add and delete text, the cells resize naturally.

What it currently does is putting every node wrapper in a list of QObjects,
and use that as the model in QML side (model is just a container that has
the list of stuff to show in Repeater).

So you can edit every node in a leo document in this "notebook". Future
version will probably only allow editing a subtree.

Note how headlines are "toned down" with small, grey font. Intention is
that e.g. with ipython notebook, the headline will just be a running,
uneditable sequence number basically.

BTW, forgot to mention that I put the NodeWrapper stuff under leo.core. We
can move it out eventually, but right now it seemed like a natural place
for this kind of cross-plugin utility.

And on related note: remember that with QML, sky is the limit as far as the
styling goes :). So if you have wild ideas about adding customizable
images, animated checkboxes, or other weird stuff next to the nodes, fire
away.

===== Kent Tenney

Interesting ...

Am I correct: this is POC, edits in your serialized pane don't reflect in
the Leo file?

===== Ville

Yes, modifications are not saved yet. Also, modifications in normal body
editors are not copied over to the notebook yet.  This is probably going to
end up like tabula and stickynotes in this regard.

===== Kent

This is a hint of something I've long wanted, what I have called 'slurped'
vs 'chunked' Something I miss with Leo is the capability get an overview of
a file, I find myself needing to 'open file with gvim' to grok at file
level.

The pane you are generating offers both at once, I can see the linear view
of the file, retaining the 'chunk' metadata (node headlines).

===== Ville

Getting an overview of a file could be an interesting extra usecase, my
main interest is still in using it for interactive programming/computation
(like ipython notebook) .

===== Terry Brown

Played with it. I guess the next step would be demo of python handling
events from the QML UI elements, and of python finding and manipulating the
QML UI elements.

I'm wondering about the advantages of this approach over the "regular"
QWidget approach. QML is perhaps a more terse and elegant language for
defining a UI, and it has scripting of UI behavior in javascript. And
perhaps it has a more tablet friendly widget set?

But I wonder what it lets you do that you can't do with the QWidget stack,
given that mixing the two seems to mean that Leo is using two GUI systems -
they may be very tightly integrated, but mind-space wise it's two complex
systems instead of one.

Which isn't a reason not to use QML, just wondering if it has advantages
I'm missing.

===== Terry

Here's a demo to run Ville's QML thing in a free_layout pane. Requires rev.
5284 so the .qml file in leo/plugins/qmlnb/ is available.

Paste this into a node, run-script on the node, right click a splitter
handle, Insert, click the Action button, select "Add QML shower".

Note that you can flick the text boxes it shows up and down with the mouse,
in a tablet / phone ui kind of way.

---cut here---
from PyQt4.QtCore import QUrl
from PyQt4.QtDeclarative import QDeclarativeView
class QMLShower:
    def __init__(self, c):
        self.c = c
        c._qml_shower = self
        self.w = None
        c.free_layout.get_top_splitter().register_provider(self)
    def ns_provider_id(self):  # allow for re-registering, mainly for dev.
        return '__qml_shower'
    def ns_provides(self):  # what we can provide
        return [("Add QML shower", '__add_qml_shower')]
    def ns_provide(self, id_):  # provide it
        if id_ == '__add_qml_shower':
            g.unregisterHandler('select2', self.update)
            g.registerHandler('select2', self.update)
            if not self.w:
                self.w = self.make_widget()
            return self.w
    def make_widget(self):
        view = QDeclarativeView()
        path = g.os_path_join(g.computeLeoDir(), 'plugins', 'qmlnb', 'qml', 'leonbmain.qml')
        view.setSource(QUrl(path))
        view.setResizeMode(QDeclarativeView.SizeRootObjectToView)
        # Display the user interface and allow the user to interact with it.
        view.setGeometry(100, 100, 400, 240)
        view.show()
        # rootObject = view.rootObject()
        return view   
    def update(self, tag, kwords):
        pass
    def closed(self, event):
        g.unregisterHandler('select2', self.update)

QMLShower(c)
---cut here---
</t>
<t tx="ekr.20130926053913.16198">From: Jacob Peck

One of the ways I use Leo is as an information management/database for when
I'm running tabletop RPGs. Such games involve a fair amount of similarly
structure data. I set out to make a way of defining a template, and
providing macro expansions within the template, so that the user could
click a script button, be prompted for data, and be rewarded with a
fully-populated copy of the template. I've managed to accomplish this with
the code below:

https://gist.github.com/gatesphere/2be5030506a364ee6ec1

How it works is like this:

- Create a `@template` node.  This is the parent node for your template.

- Create a `@destination` node as a child of the @template node. This 
node's headline is the name of a top level node where your completed 
template will be placed.  `@destination Sessions` will place the 
finished product under the top-level "Sessions" node.

- Populate the @template node with various `@item` nodes - these keep 
their structure in the filled template.  Anything that needs to be a 
part of the final product has to be an @item node.

All of that is fine and dandy if you just want to copy and paste... but 
that's already baked into Leo.  So I added macro expansion.  The script 
gathers up all instances of anything that fits the regex "&lt;\\$\\w+&gt;" is a 
macro variable name.  Something like `&lt;$name&gt;` or `&lt;$date&gt;`.  The script 
gathers up all of these variable names, and prompts the user (ala 
todo.py's "Redistribute Priorities" function) for values for each of 
them. They are global with respect to the template, so using the same 
macro variable in multiple places in the same template will result in 
all of them being filled in with the same value.

In addition, there is one more type of node that can go under @template 
nodes - @default.  @default nodes provide a default value for a macro 
variable.  The node with a headline of `@default &lt;$name&gt;` and a body of 
"This is my body" gives the `&lt;$name&gt;` macro a value of "This is my body" 
everywhere within the template, and that macro will not be prompted for 
a value.  This is handy if you're copying templates between Leo 
worksheets, and want them flexible, but don't want them to fill in the 
same value for every single invocation of copy-template.

Here's an example template:

@template &lt;$campaign&gt; Session #&lt;$num&gt; ($date)
       @destination Sessions
       @default &lt;$campaign&gt;
       @item Who's Coming?
       @item In-World Start Date
       @item Log
       @item Threads
             @item High Priority
             @item Low Priority
       @item News
             @item Out of Character
             @item In Character

The body of `@default &lt;$campaign&gt;` is "World of Ka'rim".  The body of 
`@item Who's Coming?` is "John, Jane, Jack, Jenny, Jeremy".

Running copy-template on this template, and filling the values prompted 
for (&lt;$num&gt; and &lt;$date&gt;) gives the following under the top-level node 
Sessions:

World of Ka'rim Session #1 (01 May 2013)
       Who's Coming?
       In-World Start Date
       Log
       Threads
             High Priority
             Low Priority
       News
             Out of Character
             In Character

The headlines bodies are correctly filled in with macro expansions, and 
other text is verbatim copied from the respective headlines and bodies.

So... two questions:

1.) Did I re-implement something Leo already does?
2.) Anyone have any suggestions on reducing the amount of code/any fixes?

Also, hope someone else finds this useful.  Once it's cleaned up, I 
might do a leo-editor blog post about it.
</t>
<t tx="ekr.20130926053913.16199"></t>
<t tx="ekr.20130926053913.16200">Help-for command translate !&lt;command-name&gt;! in the docstring to the binding for command-name.
</t>
<t tx="ekr.20130926053913.16201"></t>
<t tx="ekr.20130926053913.16202">Skip '.' before section names in v.matchHeadline.

2013/08/01: bug fix: allow leading periods in at.isSectionName.
</t>
<t tx="ekr.20130926053913.16203"></t>
<t tx="ekr.20130926053913.16204">In earlier version of Leo if one runs test externally with the selected
position under @test node, that @test was executed with
(run-marked-unit-tests-externally)

The fix was to the "important special case" in TM.findAllUnitTestNodes.
</t>
<t tx="ekr.20130926053913.16205">The commands now work, and Alt-slash and Alt-Ctrl-slash are bound as in Emacs.
</t>
<t tx="ekr.20130926053913.16206">The quicksearch plugin now supports the go-anywhere command. It works "sort
of" like Nav bar. Also Nav bar now does live search on headline (you have
to press enter to force search of bodies as well)

Once the hits are shows, you can navigate them by pressing up/down while
focus is still in line editor &amp; you can keep on typing (sort of like
sublime text).

This has a very clever hack (even if I say so myself)--spaces in search
string are replaced with * wild card. So if you search for, say "file txt",
it will search for "file*txt", matching e.g. @file readme.txt
</t>
<t tx="ekr.20130926053913.16207"></t>
<t tx="ekr.20130926053913.16208">Instead of just printing their docstrings.
</t>
<t tx="ekr.20130926053913.16209"></t>
<t tx="ekr.20130926053913.16210"></t>
<t tx="ekr.20130926053913.16211">- Documented that return ends the search.
- Documented that deleting the entire search pattern aborts the search.
- Removed annoying status messages printed to log.

- (Can't do) If text is already highlighted, Alt-S or Alt-R should use that text.

</t>
<t tx="ekr.20130926053913.16212">By Terry Brown

I assume all *nix shell users use the screen shell multiplexer, and
hopefully *nix shell users who use Leo know about the leoscreen plugin
which passes text back and forth between Leo and the shell (provided you're
running screen), which is very handy for build scripts and SQL hacking etc.
etc.

Anyway, if you're in that sliver on the Venn diagram :-) there's a new
command leoscreen-jump-to-error which scans the output in the shell for the
offending line in the last python traceback, handy if you're coding python
in Leo and running/debugging in the shell.

leoscreen-jump-to-error
    Jump to the python error reported in the shell window, if the
    file's loaded in the current Leo session. Just looks for a line:

        File "somefile.py", line NNN, in xxx

    and looks for a node starting with "@" and ending with "somefile.py",
    then jumps to line NNN in that file.
</t>
<t tx="ekr.20130926053913.16213">https://bugs.launchpad.net/bugs/994985
Wishlist: normalize-whitespace

When using @auto, the logic often complains about "abnormal" whitespace and
refuses to write/read node normally.

What I did:
    
1. The clean-lines command (and thus the clean-all-lines command)
   now remove trailing whitespace while preserving newlines.
   
2. reportMismatch suggests using the clean-all-lines command.
   Note: a good unit test for reportMismatch already exists.
   
3. Added a unit test for clean-lines.
</t>
<t tx="ekr.20130926053913.16214">Useful for re-parsing text that was not originally parsed properly.
</t>
<t tx="ekr.20130926053913.16215">Created print-buttons command, showing source of all @command and @button nodes.

Changed ParserBaseClass.doButtons/doCommands so they return
lists of (p.copy(),script) rather than (p.h,script)

Added g.app.config.atLocalButtonsList &amp; g.app.config.atLocalCommandsList
for use by print-buttons command.
</t>
<t tx="ekr.20130926053913.16216">"refresh from disk" is now done for all selected nodes. You can either

ctrl-click each @&lt;file&gt; node you want refreshed, then "refresh from
disk" to refresh all of them, or

shift-click the first and last @&lt;file&gt; node you want refreshed, to
select the entries in between, then "refresh from
disk" to refresh all of them.

(i.e. standard UI list multi item selection)

But be aware of this bug:
https://bugs.launchpad.net/leo-editor/+bug/1090950

using refresh from disk immediately after cutting nodes from the
outline has odd effects.
</t>
<t tx="ekr.20130926053913.16217">A simple change to k.computeCompletionList was all that was needed.

</t>
<t tx="ekr.20130926053913.16218"></t>
<t tx="ekr.20130926053913.16219">From: Terry Brown &lt;terry_n_brown@yahoo.com&gt;

I just pushed two new commands, zoom-in and zoom-out, which increase
or decrease the body text font size by one point size.  They probably
deserve default bindings, but to what?  I have them on Ctrl-; and Ctrl-'

They leverage the new theme "engine" by manipulating a constant
"@font-size-body".  I've set it up in the default theme, anyone using
the new dark theme will need to add

   @font-size-body = 18px

in the config node for that theme, 

@settings--&gt;solarized_dark theme settings--&gt;stylesheet &amp; source--&gt;config

and replace the literal "18px" with "@font-size-body" in the node

@settings--&gt;solarized_dark theme settings--&gt;stylesheet &amp; source--&gt;Non-color styles (fonts etc.)--&gt;body editor

commit log:

  zoom-in / zoom-out commands
  ctrl-mouse wheel scrolling for same
  
  replace old focused pane border highlight with pure stylesheet
  version
  
  rename solarized_dark theme leo_dark_0
</t>
<t tx="ekr.20130926053913.16220"></t>
<t tx="ekr.20130926053913.16221">This is a significant improvement, and makes Leo suitable for authoring
text. It should have been done ages ago. Please let me know immediately if
this new behavior causes problems for you.

There is one glitch.  If you add @wrap, the directive won't be in effect 
until you leave the node and revisit it.

===== redla

There is one problem which is caused by this change: I have @wrap active
and see my "plain" text wrapped properly. But if there is any "long enough"
URL on the page (i.e. longer than the screen width), this is not wrapped
(as there is no space in the string) nor I can see the end of it (as there
is no horizontal scrollbar either)

</t>
<t tx="ekr.20130926053913.16222">These are generated from the @button node's docstring, if it exists.
</t>
<t tx="ekr.20130926053913.16223">Leo now supports having border colors that show which pane has focus.

To enable such borders, modify (in your myLeoSettings.leo)::

    @data qt-gui-plugin-style-sheet

Change::

  @focused-border-style = none

to::

  @focused-border-style = solid

**Important**: The following settings are no longer used::

    @int focus_border_width = 1
    @bool use_focus_border = False 
</t>
<t tx="ekr.20130926053913.16224">by Terry Brown

I just pushed the solarized dark theme to trunk. There were some changes to
core code, but nothing too major, and I've been using it for some time.

In leoSettings.leo there's a new top-level node called 'Themes', which
contains a single theme node at the moment, you can copy that to you
myLeoSettings.leo file under @settings. Read the README node of the theme
node for more instructions.

The theme is far from perfect - it's relatively easy to get it looking ok
if you're already running a dark desktop theme, which is what I'm doing,
but much harder if you want Leo dark in a light desktop theme, as you need
to theme everything.

 - See the README. If you're already running a dark theme there's a `base`
   node which can be switched to `@ignore base` to take more advantage of
   your desktop theme.

 - The new theme system includes a stylesheet authoring tool with macro
   substitutions :-) you no longer edit @data qt-gui-plugin-style-sheet
   directly but edit a more comfortable Leo tree version and then
   run-script on the appropriate node to "compile" to @data
   qt-gui-plugin-style-sheet
   
**Note**: The docs in the theme node do mention moving other @data
qt-gui-plugin-style-sheet and @color nodes out of the way, but I've added a
couple of notes about putting it at the bottom of the @setting list to
ensure it overrides other settings. The problem is when the default theme's
@data qt-gui-plugin-style-sheet node comes after the dark theme's.

===== Ville.

If you prefer the bigger contrast that e.g. Sublime Text 2 has, try this
"config": https://gist.github.com/vivainio/5261207

===== Terry

From: Terry Brown &lt;terry_n_brown@yahoo.com&gt;

Along these lines someone wanted a dark body only, you can get that by just
adding @ignore to all the color related nodes other than body, or moving
all of them under an @ignore node.

===== Ville 

I'm slightly bothered by the fact that color variable names have
"solarized" in them. You are supposed to create new themes by changing
their values in the "config" node, after which the theme is not "solarized"
any more. How about "@leotheme-c-0" (for color 0) etc.

===== Terry

The variable replacement runs up to ten levels deep, after which it bails
assuming you've created a loop :-)

So there's nothing wrong with::

  @solarized-yellow = #abcdef

The issue is that `@solarized-yellow` is used in the guts of the stylesheet
definition. Instead, ideally, but I didn't get to it, in the config node
you'd have::

  @solarized-yellow = #abcdef
  ...
  @highlight-hot = @solarized-yellow

and then use `@highlight-hot` in the guts of the stylesheet definition.

**Note**: you can't create new themes simply by editing the config node,
it's not possible to create enough constants for every style element that
can be addressed by a stylesheet.

But it would be nice to move all the color and numeric constants out of the
stylesheet and into the config node as I've described above, just a find
and replace operation.
</t>
<t tx="ekr.20130926053913.16225">By Ville M. Vainio

https://plus.google.com/103097156557482112329/posts/6D9GPRCdXVh
</t>
<t tx="ekr.20130926053913.16226">- Added the following commands:
    
    - ctrl-click-icon
    - ctrl-click-at-cursor
    - open-url
    - open-url-under-cursor
    
- Double-click *only* edits headline.
- Only look at first line of the body in @url nodes.
- Ctrl-click in body allows spaces in url's.
</t>
<t tx="ekr.20130926053913.16227"></t>
<t tx="ekr.20130926053913.16228">Leo now contains support for \@testsetup nodes. At present, they work only
when running unit tests locally.

In effect, \@testsetup nodes provide common setup code for all following
\@test and \@suite nodes. Such common setup code is the real reason for
having custom subclasses of unittest.TestCase. This Leonine solution is
much than either:

a) @testclass nodes (which I never use) or

b) "injecting" common test code using::

    exec(g.findTestScript(c,\'@common name-of-common-test-code\'))

Leo's test-execution code prepends the body text of an \@testsetup node to
all following @test and @suite nodes. Multiple \@testsetup nodes may appear
in an outline. The range of an @testsetup node extends over all following
\@test and \@suite nodes until the next \@testsetup node is seen (in
outline order).

</t>
<t tx="ekr.20130926053913.16229">\@testclass nodes should set either the suite or testclass vars.

\@suite nodes should set the suite var.
</t>
<t tx="ekr.20130926053913.16230">- Changed es so it always queues messages when g.app.log is None.
- Completed the command-line args: --session-save and --session-restore.
- Wrote session info in leoTabbedTopLevel.closeEvent and g.app.onQuit.

Rev 5324 finishes some session-related work. The existing
session commands are unchanged, but Leo now fully supports
two new command-line arguments::

    --session-restore     restore previously saved session tabs at startup
    --session-save        save session tabs on exit

If you use both arguments, everything is automatic: Leo
saves the tabs when you quit Leo, and restores tabs when you
start Leo. Note that you can still specify file names on the
command line in addition to whatever files --session-restore
will open for you.

If you use only --session-restore, it is up to you to save
sessions "by hand" with one of the session commands, for
instance, session-snapshot-save.
</t>
<t tx="ekr.20130926053913.16231">A major change in Leo's read/write code.  The first "live" rev was 5584.
At present, controlled by the allow_cloned_sibs switch in leoAtFile.py.

Fixes the following bugs:

clones sometimes not saved
https://bugs.launchpad.net/leo-editor/+bug/882243

When all clones of a node are in an @file subtree, they disappear on exit
https://bugs.launchpad.net/leo-editor/+bug/1084661
</t>
<t tx="ekr.20130926053913.16232">http://groups.google.com/group/leo-editor/browse_thread/thread/67a28984616d09c9
About bug 882243: clones sometimes not saved

What I did:

- Added allow_cloned_sibs switch at the start of leoAtFile.py.
  All new code enabled by this switch.

- Refactored at.createNewThinNode:
    - Renamed createThinChild4 to old_createThinChild4.
    - Added new_createThinChild4.
    - Added createV5ThinNode.
    
The key invariant in createV5ThinNode:
    On exit from at.changeLevel, top of at.thinNodeStack is the parent.
</t>
<t tx="ekr.20130926053913.16233">From: Terry Brown &lt;terry_n_brown@yahoo.com&gt;

Abbreviations can now include computed values and place holders which you
can step through, filling in a template.

Here's a quick screencast of the template expansions:
http://www.greygreen.org/tmp/leoabbrev.ogv

Here are the draft docs. for abbreviations:

Abbreviations are very versatile. You can type ``def;;``, and Leo will
prompt you for a function name, detect whether the function needs a
``self`` parameter, ask for a list of parameters, and expand your input
(just ``"some_function"`` and ``"one, two, three=4"`` to something
like:: 
    def some_function(one, two, three=4):
        """some_function - Return &lt;|return|&gt;
    
        :Parameters:
        - `one`: &lt;|describe one|&gt;
        - `two`: &lt;|describe two|&gt;
        - `three`: &lt;|describe three|&gt;

        Created: Wed Aug 22 10:32:54 CDT 2012
        """
    
        &lt;|code|&gt;

The first placeholder, ``&lt;|return|&gt;`` will be selected, so you can
begin typing in the right place. Hitting ``,,`` will select the next
place holder, and so on.

They can also close XML tags, enter balanced indented markup for
various languages, etc.

Here's a list of `@settings` which relate to abbreviations.

@bool enable-abbreviations = False
    True: enable abbreviations
    False disable abbreviations
    
    Typically you would enable abbreviations in myLeoSettings.leo or in
individual .leo files.
@data global-abbreviations &amp; @data abbreviations
    # Comments lines (lines starting with '#') are ignored.
    # Non-comment lines should have the form::
    #
    #    name=definition
    
    # Definitions in @data abbreviation nodes override definitions in
@data # global-abbreviation nodes. Typically you would define @data
abbreviation nodes # in myLeoSettings.leo
@string abbreviations-subst-start = None
    If this @string is set to something other than None, *and*
    @bool scripting-at-script-nodes = True, then substitutions
    will be made when abbreviations are inserted.  For example
    set abbreviations-subst-start to ``{|{`` and
    abbreviations-subst-end to ``}|}`` and an abbreviation
    like::
    
        date;;={|{import time;x=time.asctime()}|}
    
    will expand to something like "Mon Aug 20 22:00:40 2012"
    
    See also abbreviations-subst-env.
@string abbreviations-subst-end = }|}
    See abbreviations-subst-start.  This setting,
    abbreviations-subst-end, has no effect if
    abbreviations-subst-start is not set.
@data abbreviations-subst-env
    If abbreviations-subst-start is set (see that 
    @setting), the code in this node will be executed, once
    only, when the outline is loaded, in an environment which
    will be used for execution of substitutions in
    abbreviations.  For example, if this node contains
    ``import time``, then an abbreviation like::
    
        date;;={|{import time;x=time.asctime()}|}
    
    can be written more simply as::
    
        date;;={|{x=time.asctime()}|}
    
    The environment will contain `c` and `g`, a dict called `_values`
    (see ask() and get() in @data abbreviations-subst-env), and
    `_abr`, the abbreviation being expanded.
    
    Start lines with `\\:` to preserve indentation.
@@data abbreviations examples
    See the node for examples of advanced abbreviations with
    substitutions.
@string abbreviations-place-start = &lt;|
    Start of a placeholder for template expansions.  E.g.
    the `&lt;|` in::
    
        w;;=while &lt;|condition|&gt;:
        \\:    &lt;|code|&gt;
    
    This would expand with the `&lt;|condition|&gt;` selected, and `,,`,
    if that's an abbreviation linked to next_place(), see 
    @@data abbreviations examples, would select `&lt;|code|&gt;`.
@string abbreviations-place-end = \\|&gt;
    The end of a placeholder for template expansions, e.g.
    `|&gt;`. See @string abbreviations-place-start.


===== EKR

The same exec statement appears to allow the execution of arbitrary
Python code.

===== Terry

That's why enabling requires @bool scripting-at-script-nodes = True as
well as the abbreviation specific stuff.  The risk seems equivalent to
the scripting-at-script-nodes = True risk.
</t>
<t tx="ekr.20130926053913.16234">@language rest

Leo's abbreviations have been significantly improved by adding scripted
abbreviations and templates. This is the work of Terry Brown,
&lt;terry_n_brown@yahoo.com&gt;

Terry describes the new features in a screencast: http://www.greygreen.org/tmp/leoabbrev.ogv

The highlights::

1. The @data abbreviations-subst-env node contains a script defining the
   environment in which all abbreviations execute. This allows helper
   functions to be deined. Very handly.
   
2. Scripts may span multiple lines. Line starting with "\:" (2 characters)
   continue a script. This allows abbreviations to define multi-line
   templates.  Helpers defined in @data abbreviations-subst-env can
   fill in templates with *calculated* (not predefined) data.
   
3. Templates may contain placeholders that the user can fill in.  By default,
   the double comma binding selects the next placeholder.

4. Added a new setting: @bool scripting-abbreviations, default False.
   Scripting abbreviations will be enabled if *either* of the following is
   True::

        @bool scripting-abbreviations
        @bool scripting-at-script-nodes
    
    This is a safety feature: it allows scripting abbreviations to be
    enabled *without* enabling the (very dangerous in general)
    scripting-at-script-nodes setting.

5. Added a new example node: @@data abbreviations examples.  This contains
   several extremely useful scripts.
</t>
<t tx="ekr.20130926053913.16235">https://bugs.launchpad.net/leo-editor/+bug/711158

- The PickleShareDB object is created even if caching (of files) is disabled.
  This allows us to used g.app.db even when --no-cache is in effect.
  
- Added the three methods in app.Detecting already-open files.
</t>
<t tx="ekr.20130926053913.16236"></t>
<t tx="ekr.20130926053913.16237">Leo now supports @auto-otl, along with imports of .otl files.

**Warning**: the new code is simply a prototype.  Play with these
features *only* on files you can afford to be corrupted.

To use @auto-otl:

1.  The easy, and relatively safe way:

- Use Leo's import-file command to create and populate an @auto-otl
node.
- Save the .leo file.

2. The manual, less safe way:

- Create a node called @auto-otl x.y
  x can be an absolute path or a path relative to the directory
containing the .leo file.

- Save the .leo file, but **do not** overwrite the existing .otl file
when prompted.

Either way, you should now have an @auto-otl node whose **children**
represent the contents of the external .otl file.  (The actual @auto-
otl node is *not* written to the external file.  This allows you to
put Leo directives in the node.) Changing the children in Leo will
change the external file.  Changing the external file outside of Leo
will update the outline the next time you restart the .leo file
containing the @auto-otl node.

**Important**: as with all kinds of @auto nodes, clone links will
break the next time you load Leo if the @auto-otl tree contains any
kind of cloned nodes.  This is pretty much a fundamental limitation of
@auto trees.

However, if the VO people wanted to *retain* gnx's when editing in
vim, it would, in theory, be possible to retain clone links when Leo
read the external .otl file.  I don't plan to do this any time soon,
and it would require and extension to the VO file format, but I wanted
to point out the possibilities.


&gt; **Important**: as with all kinds of @auto nodes, clone links will
&gt; break the next time you load Leo if the @auto-otl tree contains any
&gt; kind of cloned nodes.  This is pretty much a fundamental limitation of
&gt; @auto trees.

I'd like to add two points to this discussion:

1. This limitation instantly disappears when you convert from (any
kind of) @auto to @file.  The reason is that the sentinels that Leo
writes "carry" both outline structure *and* node identity.  It is this
unique, immutable node identity which provides for robust linking of
clones.

I hinted in another thread that a smallish addition to the otl format
would allow .otl files to carry identity.  For example, suppose that
headlines were optionally represented in the file format as::

    &lt;indentation: hard tabs&gt; :: gnx :: headline

The VO folks could do this in an upward compatible manner without
changing vim's core in any way.  True, it doesn't give VO Leo's clone
capabilities, but it *retains* the information necessary to use clones
*in Leo*.

2. Unlike .otl, the external files produced by Leo can be used
*unchanged* as program source files.  Indeed, all of Leo's Python
source files contain outline structure and node identity--Leo
sentinels are simply comment lines in the appropriate language.  In
contrast, the format of .otl files ensures that body text can not be
used untranslated as source code.  It is the ability to *be* source
code, even more than cloning, that makes Leo's external file format so
useful.

&gt; As of rev 5309 of the trunk, Leo now supports @auto-otl, along with
&gt; imports of .otl files.

Rev 5310 contains a rewrite of the scanHelper method.  As before, this
code should be considered experimental.

The scanHelper method now parses each line of the .otl independently:
any combination of headline and body lines should now be valid,
regardless of indentation level.  If necessary, the parser will insert
intermediate nodes so as to allow lines that are indented more than
one more than the previous node. This is the most general scheme that
I can imagine.
</t>
<t tx="ekr.20130926053913.16238">Rev 5488 contains a prototype for importing IPython notebook (.ipynb) files 
into Leo.  In theory, this would allow two-way interchanges between Leo 
outlines and the outlines in IPython notebooks.

At present, the prototype simply converts a string containing the contents 
of a .ipynb file to a Leo outline.  A few details remain, but it shows that 
such conversion is straightforward.  Otoh, this is just a first step: we 
would like the Leo outline to support most of the features of IPython 
notebooks, including embedded images, etc.

===== From: Alia K

May a suggest a radical thought exercise that only occurred to me after 
seeing what can be achieved in terms of in-browser editing with 
http://codemirror.net/: 

Why not create an ipython notebook "plugin" version of leo which would only 
provide core leo functionality: outlines, literate programming, and clones, 
but would not be burdened by having to support legacy leo plugins. 

You could leverage all the mad goodness and momentum that is happening with 
ipython right now (interactivity, parallelism, networking and 
collaboration, interactive access to javascript libs like d3.js, etc.., 
inline images, and movies, and cell magic, etc..). Since ipython is pretty 
much pervasively used ... it could be a good thing for leo (-:
</t>
<t tx="ekr.20130926053913.16239">Added TypeScriptScanner class and related code.
</t>
<t tx="ekr.20130926053913.16240">Created vimoutlinerScanner.

Created at.writeAtAutoOtlFile.
</t>
<t tx="ekr.20130926053913.16241"></t>
<t tx="ekr.20130926053913.16242" str_atime="1376412280.0">@language rest
</t>
<t tx="ekr.20130926053913.16243">Added printing.py.
</t>
<t tx="ekr.20130926053913.16244">From: Ville M. Vainio
See: http://en.wikipedia.org/wiki/Mylyn

I went on to start a "leo mylyn" plugin to excercise using the
childrenModified and contentModified signals.

If you want to play with it, pull, enable leomylyn.py, modify stuff
around the tree and do alt-x mylyn-scores.

Of course as it is useless in this state, but becomes useful when it
has a proper gui (maybe in Nav pane), where you would then have a list
of "most interesting" nodes.

In the future, this could be able to remember the scores through the
sessions, degrade the old scores by time, etc. Also, a scoreset would
be associated with a "project" (e.g."own research", "work project
foo"), each of them having their own typical node working set.

Mylyn was a nice boost back in the eclipse days, it could work for Leo
too. My main motivation right now was to demonstare the signals with
something that is much simpler than using them in qmlnotebook.
</t>
<t tx="ekr.20130926053913.16245" str_atime="1376412288.0">The printing.py plugin fixes this bug:
https://bugs.launchpad.net/leo-editor/+bug/1132804

Here's the docscring:

'''Supports printing from the Qt GUI.

Jacob M. Peck, 2013

Commands
========
This plugin supports the following twelve commands:

print-selected-node
-------------------

Opens up the print dialog to print the selected headline and node.

print-preview-selected-node
---------------------------

Opens up the print preview dialog to preview the selected headline
and node.

print-selected-node-body
------------------------

Opens up the print dialog to print the selected node body.

print-preview-selected-node-body
--------------------------------

Opens up the print preview dialog to preview the selected node body.

print-expanded-node
-------------------

Opens up the print dialog to print the expanded contents of the
selected node, with top-level headline.

print-preview-expanded-node
---------------------------

Opens up the print preview dialog to preview the expanded contents
of theselected node, with top-level headline.

print-expanded-node-body
------------------------

Opens up the print dialog to print the expanded node body.

print-preview-expanded-node-body
--------------------------------

Opens up the print preview dialog to preview the expanded node
body.

print-marked-nodes
------------------

Opens up the print dialog to print all marked nodes in the current
outline, with headlines.

print-preview-marked-nodes
--------------------------

Opens up the print preview dialog to preview all marked nodes in \\
the current outline, with headlines.

print-marked-node-bodies
------------------------

Opens up the print dialog to print the bodies of all marked nodes
in the current outline.

print-preview-marked-node-bodies
--------------------------------

Opens up the print preview dialog to preview the bodies of all
marked nodes in the current outline.

Settings
========
- ``@string printing-font-family = DejaVu Sans Mono``
   The font family for printing.  A monospaced font is recommended.

- ``@string printing-font-size = 12``
   The font size for printing bodies, in px.  Due to limitations
   of PyQt, the size of headlines cannot be changed.
   
'''
</t>
<t tx="ekr.20130926053913.16246">By Terry Brown.

See http://leo-editor.github.io/screen_capture.html

screen_capture_now captures an image immediately, screen_capture_5sec waits
five seconds, so you can position the pointer, open menus etc. The only
feedback is in the console, as messages in the log would be distracting in
the captured image.
</t>
<t tx="ekr.20130926053913.16247">By Edward K. Ream

Screencasts promise to be easy to be *much* easier to create than 
slideshows, while also being more interesting, informative and flashy.  It 
is *so* much easier to write a screencast script than it is to lay out a 
slide, take a screenshot, and then manage resulting slide.

In particular, there are few continuity problems with screencasts.  
Continuity is a *huge* problem with slideshows!  If I change one slide, I 
am likely to want to change all following slides.  Which means I have to 
retake all the slides, and file the new versions in the proper places.  In 
contrast, any changes to screencasts naturally propagate forward.  There 
might be an effect on following screencasts scenes, but this will happen 
rarely with a reasonable scene design, and any problems should be easy to 
fix.

With screencasts, the *movie* script is also the *python* script!  There is 
no "translation" from one to the other.  Furthermore, all the work to 
produce a screencast is done (naturally!) within Leo.  No need to create 
and manage external data.  This is another huge advantage and it make 
producing screencasts much faster than producing slideshows.

Screencasts may be the long-awaited tools that will allow me to show Leo in
action so that other will finally be able to understand it easily.
</t>
<t tx="ekr.20130926053913.16248">By Kent Tenney

The timestamp plugin manages the following node attributes:

- str_ctime: creation time
- str_mtime: time node was last modified
- str_atime: time node contents were last viewed
</t>
<t tx="ekr.20130926053913.16249"></t>
<t tx="ekr.20130926053913.16250">By Terry Brown

The bookmarks.py plugin provides a pane with colored links to nodes.
Bookmarks can now be added and removed with mouse clicks, making navigation
back and forward between related nodes quick and easy.

The free_layout Action button context menu will also allow you to add one
of these bookmark panes, and they will be saved and loaded again if the
layout is saved and loaded.

=====

Can also be used for bookmarking directly from the browser to Leo.  To
do this, add a bookmark to the browser with the following URL / Location:

    javascript:w=window;if(w.content){w=w.content}; d=w.document; w.open('http://localhost:8130/_/add/bkmk/?&amp;name=' + escape(d.title) + '&amp;selection=' + escape(window.getSelection()) + '&amp;url=' + escape(w.location.href),%22_blank%22,%22toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=yes, copyhistory=no, width=800, height=300, status=no%22);void(0)

and edit the port (8130 in the example above) to match the port you're using
for mod_http.

Bookmarks are created as the first node in the outline which has been opened longest.
You can set the ``@string`` ``http_bookmark_unl`` to specify an alternative location,
e.g.::

    @string http_bookmark_unl = /home/tbrown/.bookmarks.leo#@bookmarks--&gt;Incoming

to place them in the `Incoming` node in the `@bookmarks` node in the `.bookmarks.leo` outline.

The headline is preceeded with '@url ' *unless* the ``bookmarks`` plugin is loaded.
If the ``bookmarks`` plugin is loaded the bookmark will have to be moved to a ``@bookmarks`` tree to be useful.

The browser may or may not be able to close the bookmark form window for you, depending on settings - set ``dom.allow_scripts_to_close_windows`` to true
in ``about:config`` in Firefox.
</t>
<t tx="ekr.20130926053913.16251">IPython plugin now works with all versions of IPython.

- Import logic looks for legacy IPython first (0.11 and prev),
  then looks for new-style IPython (0.12 and above).

- Created GlobalIPythonManager class, assigned to leoIPython.gipm and g.app.gipm.

- Added self.c ivar to LeoNode class.  This is the same as p.v.context.

- Changed:
    - init (qtGui.py top level) (qtPdb)
    - runMainLoop (qtGui)
    - start_new_api
</t>
<t tx="ekr.20130926053913.16252">**Important** Ville M. Vainio has made many nifty additions to this plugin.

Here is a summary: http://leo-editor.github.io/valuespace-intro.html

Some details:

1. valuespace now support yaml in named anchors (i.e. "@a foo.yaml" now parses
parent as yaml and assigns the result to variable "foo"). It also has a
dependency on pyyaml now.

2. I'm doing some research now, that requires storing inputs in json, I use
   those inputs to calculate some outputs and store them in .json files. I
   added a few directives to valuespace.py plugin to bring native json data
   support.

**@vsi foo.json**

reads in file foo.json, and stores the parsed data structure to vs /
ipython variable "foo"

**@vso bar.json**

serializes content of variable "bar" to json file. \@vsi gets executed
during pass 1 of vs-update, \@vso gets executed in phase 2.

Body text gets assigned with json content in both cases.

Some further notes:

- Yes, the .json extension is explicitly special cased in the code. The
  idea is that e.g. @vso foo.csv would serialize the contents of variable
  "foo" as csv, .yml would use yaml etc.

- vsi and vso stand for value space input and value space output,
  respectively

For now, the best way to study it is valuespage_example.py in contrib
branch.

I'm being very succesful in using it + new ipython support as "ipython
notebook" workalike.

Ipython notebook is better for quick experiments, but I'm doing long term
(multi-week) research, where Leo + IPython + valuespace is doing a great
job so far.

===== Terry Brown

I've added ``vs-eval``, ``vs-last``, and ``vs-last-pretty`` commands to
the ``valuespace.py`` plug-in.  Update docs below.

===== Ville

If you don't want them in there, let me know and I'll move them. I put them
in there to avoid creating yet another plug-in, they're sort of a light
weight local calculation tool, vs. ``valuespace.py``'s outline wide calcs.

valuespace.py
=============

vs-eval
-------

Execute the selected text, if any.  Select next line of text.
    
Tries hard to capture the result of from the last expression in the
selected text::
    
    import datetime
    today = datetime.date.today()
    
will captue the value of ``today`` even though the last line is a
statement, not an expression.
    
Stores results in ``c.vs['_last']`` for insertion
into body by ``vs-last`` or ``vs-last-pretty``.

Removes common indentation (``textwrap.dedent()``) before executing,
allowing execution of indented code.

``g``, ``c``, and ``p`` are available to executing code, assignments
are made in the ``c.vs`` namespace and persist for the life of ``c``.
    
vs-last
-------

Insert the last result from ``vs-eval``.  Inserted as a string,
so ``"1\\n2\\n3\\n4"`` will cover four lines and insert no quotes,
for ``repr()`` style insertion use ``vs-last-pretty``.
    
vs-last-pretty
--------------

Insert the last result from ``vs-eval``.  Formatted by
``pprint.pformat()``,  so ``"1\\n2\\n3\\n4"`` will appear as
'``"1\\n2\\n3\\n4"``', see all ``vs-last``.
</t>
<t tx="ekr.20130926053913.16253">Supported ctrl-clicks in viewrendered panes.

Jacob Peck added support for markdown
http://packages.python.org/Markdown/
markup in viewrendered panes.
</t>
<t tx="ekr.20130926053913.16254">The following scripts have been added to scripts.leo:

By Terry Brown::

    Add @script node
    Cross-outline node editing
    Export full contents
    Full tree view (See the discussion in the child)
    Indexing files for full text search
    Persistent state with json as a leo abbreviation
    Tool for diffing Leo files
    
By Edward K. Ream::

    Cleanup imported nodes
    Create global data structures from in modes/*.py files
    Get all comments from modes (slow)
    Import org mode
    jinja2 templating
    Recursive import script (with cleanups)
    
By Brian Theado::

    Display function call hierarchy in Leo
</t>
<t tx="ekr.20130926053913.16255">From: wgw &lt;wgwinder@gmail.com&gt;

I would like to see a fuller outline view of Leo trees. So instead of 
seeing one body only and the tree of headlines, I want to display all the 
parts of the tree (all bodies and subheadings) as continuous text, much 
like a word processor outline. 

===== From: Terry Brown &lt;terry_n_brown@yahoo.com&gt;

Ville did something possibly similar:
https://groups.google.com/forum/?fromgroups=#!topic/leo-editor/Zs-5jKjPAB0

===== From: wgw &lt;wgwinder@gmail.com&gt;

Thanks! That plugin does both more and less than I want: more, because I
get a full and nicely formatted window with editable text boxes; less,
since it doesn't write any edited text back to the tree.

My fumbling tinkering would go towards not editing in the preview
window/pane at all, and just having a keystroke or click scroll the editing=

pane to the right node in Leo. But that would mean that the preview panel=

would have have to be properly indexed so that from the cursor position in=

the panel the plugin could find the proper node back in the Leo panel.
 (Kludgy way: put the node id in the text!)

Thanks for the suggestion.

===== wgw

Is there a  way to delete an inserted pane?

===== Terry

Yes, although a bit putzy.  Right click on the panel divider adjacent
to the pane, it may be above or below or left or right of it.  The panes
either side of the divider will be highlighted blue and orange.  There
will be an option to "Delete 1 left" or "Delete 1 below" or similar, if
that seems to refer to the panel you want to delete, that's your option.

If the target panel seems to be joined with another (i.e. 2 not 1
above) try right clicking a different divider to start with.

===== Matt Wilkie

I use *"r-click &gt; Edit in ..."* for this purpose. It's a poor man's
workaround. Something integrated would be much nicer. Just thought I'd
mention it for anyone looking for something they might be able to use right
away.

===== Terry

When I try that it only edits the one node, none of its children.
Which is what I thought it did.

===== Matt Wilkie

Are the links in the overview supposed to open up a browser window? The
alt-tip text gives an in-Leo hiearchy, e.g. "B:\code\dropbox-code.leo#leo
stuff--&gt;Overview of selected nodes" but clicking goes to
http://www.google.ca/, and in Internet Explorer even though Firefox is my
default browser.

===== Terry

No, that's not right, they're supposed to just select the node they
belong to.

===== Matt

And, more generally, can these hover-over-pane-divider-then-right-click
actions be made available any other way? Like a drop down menu from a
button or alt-x command or something.

===== Terry

What, you mean instead of being completely hidden where no one will
ever find them?  :-)  Most of them (not the Open Window variants of
course) rely on the context provided by your selection of a particular
divider, insert-where, delete-which etc.

Probably the most friendly would be a button which pops up an overlay
over the UI where you can select which pane to delete, or where to
insert, etc.  But that would be hard.

But it occurs to me that it might be the open window variants you want,
specifically the code to make a button / command to open a window with
a particular panel in it.  That would be this:

if hasattr(c, 'free_layout'):
    splitter = c.free_layout.get_top_splitter()
    if splitter:
        splitter.open_window(action='_add_overview_pane')

===== wgw

Excellent! This is really a great help for me. I'm still experimenting, but 
one thing I will find useful is that I can open several of these panes and 
navigate through each of the "views". Plus (and this has been a longtime 
wishlist item for those with fading sight), I can increase the text size 
for reading big chunks of text. 

(Another plus, and this is a big one, I can actually read your code well 
enough that I start to have some inkling about how to do this kind of 
addition to Leo. I could never begin to write it myself, but Leo makes it 
accessible even for shambling hackers.)

One question: is there a  way to delete an inserted pane?  It  looks useful 
to have an inserted pane, but refreshing will require killing the pane and 
reinserting.... 


</t>
<t tx="ekr.20130926053913.16256">- Added @color minibuffer-foreground-color setting.
- Added @color log_warning_color setting.
- Fully supported :: convention in @mode nodes.
- Added --no-plugins command-line option.
</t>
<t tx="ekr.20130926053913.16257">The new home page is http://leoeditor.com/

- Added link to home page from the TOC.
- Removed online-tutorial link.
- Added search box.
- Added link to glossary from Leo's home page.
- Added scaled screen shot to Leo's home page.
- Brought screen shots up to date.
</t>
<t tx="ekr.20130926053913.16258"></t>
<t tx="ekr.20130926053913.16259"></t>
<t tx="ekr.20130926053913.16312">https://bugs.launchpad.net/leo-editor/+bug/1208942
Leo holding directory/file handles after file close?

Open Leo
2. Create a new directory "test"
3. Create a new Leo file, save as "test/test.leo"
4. Create @file node in test.leo, save file.
5. Close test.leo, but keep Leo open (with another .leo open in a different tab)
6. Attempt to delete "test" directory &lt;&lt;-- FAILS, "open in another application"
7. Close Leo completely
8. Delete "test" directory &lt;&lt;-- Succeeds, now that Leo's closed

Actually, only just opening a .leo file without any @file nodes was enough to keep a file open.

The fix was to close theFile in fc.getLeoFile.
</t>
<t tx="ekr.20130926053913.16313">This will reduce duplicate scripts.
</t>
<t tx="ekr.20130926053913.16314">importing a medium sized java project ~ 400 files
https://groups.google.com/forum/#!searchin/leo-editor/importing$20a$20medium$20sized$20java$20project/leo-editor/PiuFXtAHG0s/o6vwu19PsMEJ

For example, when warning about existing files.

Fixed at rev 5935. What I did:
    
1. Added yesToAllMessage keyword arg to all runAskYesNoCancelDialog methods.

2. **only** at.writeAll manages at.canCancelFlag, at.cancelFlag and at.yesToAll.

3. Path changed logic in at.writeAllHelper now calls at.promptForDangerousWrite.

4. at.promptForDangerousWrite sets cancelFlag and yesToAll *only* if canCancelFlag is True.
   This ensures that these flags are not changed outside the code managed by at.writeAll.
</t>
<t tx="ekr.20130926053913.16315">Undoing a headline change does not change focus to the headline
https://bugs.launchpad.net/leo-editor/+bug/1162307
</t>
<t tx="ekr.20130926053913.16316">the tricky string that leo can not handle 
https://bugs.launchpad.net/leo-editor/+bug/1182695
</t>
<t tx="ekr.20130926053913.16317">https://bugs.launchpad.net/leo-editor/+bug/1182694

A string-formatting bug.

https://groups.google.com/forum/?fromgroups#!topic/leo-editor/uy_7dP1uY8w

https://leo-editor.googlegroups.com/attach/4b330006a649027d/SC-2013_5_21_14_12_31.png?view=1&amp;part=5

https://leo-editor.googlegroups.com/attach/4b330006a649027d/SC-2013_5_21_14_12_19.png?view=1&amp;part=4

This is a consequence of an underindented comment.  Like this::

        def test(self):
            string = "abc,\n\
    xyz"

http://leoeditor.com/directives.html#index-7

An underindented line is a line of body text that is indented less then the
starting line of the class, method or function in which it appears. Leo
outlines can not represent such lines exactly: every line in an external
file will have at least the indentation of any unindented line of the
corresponding node in the outline. Leo will issue a warning (not an error)
for underindented Python comment lines. Such lines can not change the
meaning of Python programs.
</t>
<t tx="ekr.20130926053913.16318">https://bugs.launchpad.net/leo-editor/+bug/1193870

The fix was to leoQtMenu.destroy.  Previously, it did nothing.
</t>
<t tx="ekr.20130926053913.16319">https://bugs.launchpad.net/leo-editor/+bug/1019794

Added the following to copyTreeFromSelfTo:

    p2.v.u = copy.deepcopy(p.v.u)
</t>
<t tx="ekr.20130926053913.16320">1183855 (un)select hooks not fired when node selection changed by find command
https://bugs.launchpad.net/leo-editor/+bug/1183855

1212332 Insert doesn't fire unselect / select events
https://bugs.launchpad.net/leo-editor/+bug/1212332


Select and unselect hooks were not being called when a command (including
the find command) left focus in the headline.

The fix was to c.redraw(!) It now calls c.frame.tree.select before calling
c.frame.tree.redraw.
</t>
<t tx="ekr.20130926053913.16321">This bug was fixed by the new_read (and new_write) logic
first committed at Rev. 5960.

To do when removing new_read switch:
- Remove unused theFile &amp; fileName args from at.readLine.
</t>
<t tx="ekr.20130926053913.16322">https://bugs.launchpad.net/leo-editor/+bug/1223383

https://groups.google.com/forum/#!searchin/leo-editor/garbled$20text/leo-editor/tq1HdMFuyVg/fbpK2M6K1tIJ

**Note**: Python does not support utf-16 encoding:
http://www.python.org/dev/peps/pep-0263/

converting utf-16 -&gt; utf-8 AND remove BOM
http://stackoverflow.com/questions/8827419/converting-utf-16-utf-8-and-remove-bom

    # str.decode will get rid of the BOM for you (and deduce the endianness).
    with open(ff_name, 'rb') as source_file:
        with open(target_file_name, 'w+b') as dest_file:
            contents = source_file.read()
            dest_file.write(contents.decode('utf-16').encode('utf-8'))
        
Note:  my favorite way to see BOM bytes is to open the file in xemacs and use &lt;alt-x&gt;hexl-mode.
For example, the following body text::
    
    @first # -*- coding: utf-16 -*-
    @encoding utf-16

    This is a test
    
Will be rendered as::
    
    00000000: fffe 2300 2000 2d00 2a00 2d00 2000 6300  ..#. .-.*.-. .c.
    00000010: 6f00 6400 6900 6e00 6700 3a00 2000 7500  o.d.i.n.g.:. .u.
    00000020: 7400 6600 2d00 3100 3600 2000 2d00 2a00  t.f.-.1.6. .-.*.
    00000030: 2d00 0a23 fffe 4000 2b00 6c00 6500 6f00  -..#..@.+.l.e.o.
    00000040: 2d00 7600 6500 7200 3d00 3500 2d00 7400  -.v.e.r.=.5.-.t.
    00000050: 6800 6900 6e00 2d00 6500 6e00 6300 6f00  h.i.n.-.e.n.c.o.
    00000060: 6400 6900 6e00 6700 3d00 7500 7400 6600  d.i.n.g.=.u.t.f.
    00000070: 2d00 3100 3600 2c00 2e00 0a23 fffe 4000  -.1.6.,....#..@.
    00000080: 2b00 6e00 6f00 6400 6500 3a00 6500 6b00  +.n.o.d.e.:.e.k.
    00000090: 7200 2e00 3200 3000 3100 3300 3000 3900  r...2.0.1.3.0.9.
    000000a0: 3000 3900 3100 3900 3300 3700 3000 3200  0.9.1.9.3.7.0.2.
    000000b0: 2e00 3900 3100 3700 3000 3a00 2000 2a00  ..9.1.7.0.:. .*.
    000000c0: 2000 4000 6600 6900 6c00 6500 2000 6300   .@.f.i.l.e. .c.
    000000d0: 3a00 2f00 7400 6500 7300 7400 2f00 7500  :./.t.e.s.t./.u.
    000000e0: 7400 6600 2d00 3100 3600 2d00 7400 6500  t.f.-.1.6.-.t.e.
    000000f0: 7300 7400 2e00 7400 7800 7400 0a23 4040  s.t...t.x.t..#@@
    00000100: 6669 7273 740a 23ff fe40 0040 0065 006e  first.#..@.@.e.n
    00000110: 0063 006f 0064 0069 006e 0067 0020 0075  .c.o.d.i.n.g. .u
    00000120: 0074 0066 002d 0031 0036 000a 0aff fe54  .t.f.-.1.6.....T
    00000130: 0068 0069 0073 0020 0069 0073 0020 0061  .h.i.s. .i.s. .a
    00000140: 0020 0074 0065 0073 0074 000a 2340 2d6c  . .t.e.s.t..#@-l
    00000150: 656f 0a                                  eo.

From: Chema Cortes &lt;pych3m4@gmail.com&gt;

I have some external files encoded with utf8 and utf16-le with BOM marks.
Leo ignores these marks, and these files become garbled. I cannot fix this
problem with @enconding directives.

Reading the code, I can see the problem when leo opens files as
binary, followed by a unicode encoding. Why not use, instead, the
'codecs.open' for this job, more friendly with BOM-marks?

Testing with system:
Leo 4.11 devel, build 5418, 2012-07-09 09:10:17
Python 2.7.3, qt version 4.8.0
Windows 5, 1, 2600, 2, Service Pack 3

</t>
<t tx="ekr.20130926053913.16323">Added new_write master switch in leoAtFile.py.
When new_write is True:
- Leo no longer writes a temporary output file.
- at.replaceTargetFileIfDifferent calls the new at.create method to write the target file.
- onl simply writes '\n'.  Conversion to the desired newline happens only in at.create.

Important: writing utf-16 files appears to work, but reading utf-16 files
does not. There are problems decoding utf-16 string in at.readline.
Possibly reading the entire file and converting to unicode might work.

Added new_read master switch in leoAtFile.py.
When new_read is True:
- at.readFileToUnicode converts the entire input file to unicode
  with a single call to g.toUnicode.
- at.getLine uses ivars to retrieve the next line.
  (the theFile and fileName arguments to at.getLine are not used).
  
I am quite happy with the new code. It is considerably
simpler than the old, and handles unicode in a much more
reasonable fashion. In particular:

1. at.readFileToUnicode at last handles the problem of
   discovering encodings properly, without reading files
   twice. It uses a trial encoding (ascii) in order order to
   scan @+leo headers. This is an unexpected simple
   fundamental method. at.readFileToUnicode converts the
   entire file unicode.

2. When new_read is True, at.readLines now is very simple
   because the conversion to unicode has already happened.

3. When new_write is True, the conversion of newlines and
   the conversion to an encoded string each happens exactly
   once, in at.create. This is an important simplification.
</t>
<t tx="ekr.20130926053913.16324">https://bugs.launchpad.net/leo-editor/+bug/1193819

Changed mod_scripting.py and setCommandForButton in qtGui.py.
</t>
<t tx="ekr.20130926053913.16325">Changed DynamicWindow.createFindTab.

Added a help line at the bottom.
</t>
<t tx="ekr.20130926053913.16326">c-x e in emacs.
Use Alt-Ctrl-M
</t>
<t tx="ekr.20130926053913.16327">Already fixed.
</t>
<t tx="ekr.20130926053913.16328">https://bugs.launchpad.net/leo-editor/+bug/1185409

Added g.is_binary_external_file and is_binary_string.
Modified ic.createOutline to create @url file:// node.
</t>
<t tx="ekr.20130926053913.16329">https://bugs.launchpad.net/leo-editor/+bug/1046195

If I drag part of an outline from one leo file to another and the source
outline contain special characters (ä, ö, ü, ß, ...), then they are
misrepresented in the target file.

The fix was to use g.toUnicode rather than g.u in parseText.
</t>
<t tx="ekr.20130926053913.16330">https://bugs.launchpad.net/leo-editor/+bug/1028986

The fix was to createUrlForBinaryFile.
</t>
<t tx="ekr.20130926053913.16331">https://bugs.launchpad.net/leo-editor/+bug/1074812

The problem are the marks created by a svn conflict. Leo can not recover
from this kind of error in such a way as to recover data. The workaround is
to report a corrupted file in at.scanText4.
</t>
<t tx="ekr.20130926053913.16332">https://bugs.launchpad.net/leo-editor/+bug/1132821

When opening a file with @auto via a soft link (on Linux) Leo reads in the
file correctly, but after modifying the content leo replaces the link with
an actual file, which means the original file, is not modified and you end
up with two different versions on disk.

os.path.realpath follows symbolic links.

The only safe place for the fix is in at.replaceTargetFileIfDifferent.
</t>
<t tx="ekr.20130926053913.16333">https://bugs.launchpad.net/leo-editor/+bug/1178249

I am going to mark this report as invalid. Please reopen if necessary.

There were recent changes to the @url handling::
- rev 5171 Refactored URL handling, and revised bookmarks plugin to use the new code.
- rev 5208 Fixed g.computeFileUrl so that it converts (Windows only) file:/// to file://

However, file url's seem to be working as expected.

Note that @url file:filename.leo is *not* a valid url, it should be @url file://filename.leo.

Any of the following work in a headline::

    &lt; a relative path &gt;
    file://&lt; a relative path &gt;
    @url &lt; a relative path &gt;
    @url file://&lt; a relative path&gt;

In particular, note this code in g.computeFileUrl::

    path = g.os_path_finalize_join(c.openDirectory,base,path)

</t>
<t tx="ekr.20130926053913.16334">The cursor was positioned one character from the end when there was no
newline at the end of the paragraph.  

The fix was to adjust ins in rp_reformat as follows::

    if not tail and ins &lt; len(s): ins += 1

Example::

A file that is both source controlled and customized by the user is inconvenient for both novices and experts.
</t>
<t tx="ekr.20130926053913.16335">https://bugs.launchpad.net/leo-editor/+bug/1224586

Reorganizing @chapter nodes under an outline's @chapters node breaks the
Chapter dropdown navigation box until the outline is reloaded.

Summary:

- Recompute drop-down list every time it is activated.
- Eliminated chapter.hoist ivar.
- Recompute chapter data every time a chapter is selected.

Details:
    
- Eliminate chapter.root ivar.
- recompute root of @chapter node every time it is needed
  using chapter.findChapterNode(chapter.name).
- Eliminated chapter.hoistStack.
  Append one entry to c.hoistStack when selection a non-main chapter.
  Pop one entry when unselecting a non-main chapter.
- Created LeoQComboBox in tt.createControl in order to be able to sublass focusInEvent.
- Created cc.setAllChapterNames, called from LeoQComboBox.focusInEvent.
- Added "create" keyword argument to selectChapterByName.
  This avoid a compile-time choice: it is True except when the user
  types the name from the minibuffer. 
</t>
<t tx="ekr.20130926053913.16336">https://bugs.launchpad.net/leo-editor/+bug/869385

The Nav pane and the "prev" and "next" buttons can't position
from one chapter to another.


What I did:
    
- c.goToNext/PrevHistory now just call nodeHistory.goNext/Prev.
  This encapsulates complications properly.
- Added "chapter" keyword arg to cc.selectChapterForPosition.
  When present, this forces a match in the given chapter if possible.
- Rewrote the select and update methods in class nodeHistory.
  Most importantly, update removes duplicates.
  A kludge: update ignores @chapter nodes, which are "selected" behind the scenes.
</t>
<t tx="ekr.20130926053913.16337">https://bugs.launchpad.net/leo-editor/+bug/1175013

A file that is both source controlled and customized by the user is
inconvenient for both novices and experts.

What I did:
    
- leo\plugins\spellpyx.txt is no longer part of the distribution.
- EnchantClass.__init__ creates an empty leo/plugins/spellpyx.txt if necessary.

Rev 5992: eliminate redraw flash when selecting the Chapters: combo box.
</t>
<t tx="ekr.20130926053913.16338">https://bugs.launchpad.net/leo-editor/+bug/1046728

The @auto example now works.
</t>
<t tx="ekr.20130926053913.16339">https://bugs.launchpad.net/leo-editor/+bug/1159302
</t>
<t tx="ekr.20130926053913.16340">https://plus.google.com/_/notifications/emlink?emr=02870587547267324596&amp;emid=CJCDv9Ppo7QCFcQbTAodl2MAAA&amp;path=%2F103097156557482112329%2Fposts%2FTL3HQegbK3T&amp;dt=1355829277202&amp;ub=63

\@auto did not write the following .json file properly(!)::

    {
        'name' : "Test app 1"
    }

The last } was missing from the generated file.

The fix was to at.putCodeLine(!!).  It is amazing that this bug could exist.
</t>
<t tx="ekr.20130926053913.16341">@language rest

https://bugs.launchpad.net/leo-editor/+bug/1226358

First reported at URLs seem to be broken on Mac OS 10.7 Lion
https://groups.google.com/forum/#!searchin/leo-editor/URLs$20seem$20to$20be$20broken/leo-editor/vM8qn66aNi0/4oTIu_UIDUwJ

I think I know the cause of the problem with file URLs on Mac OS 10.7
Lion. In leoGlobals.py, in g.os_startfile(fname), we have::

@language python

    elif sys.platform == 'darwin':
        # From Marc-Antoine Parent.
        try:
            subprocess.call(['open', quoted_fname])
        except OSError:
            pass # There may be a spurious "Interrupted system call"
        except ImportError:
            os.system('open %s' % (quoted_fname))
            
@language rest

The problem is that the quoted file path is being passed to
subprocess.call, instead of the raw file path. I verified this by
experimenting with subprocess.call() in a Python interactive mode
window -- it doesn't want the path to be quoted. I also modified the
os_startfile method to use the unquoted pathname, and verified that
this fixed the problem.
</t>
<t tx="ekr.20130926053913.16342">From: "Ville M. Vainio" &lt;vivainio@gmail.com&gt;
Leo 4.10 deb for Ubuntu Precise available

The open_dict now protects agains crashes with try/except.
It's not clear when this new code happened.

When launched from command line, it causes this error that should
probably be hidden with try-except:

/home/ville/.leo/workbook.leo
Traceback (most recent call last):

  File "/usr/lib/pymodules/python2.7/leo/core/leoEditCommands.py",
line 10372, in __init__
    self.d = enchant.DictWithPWL(language,fn)

  File "/usr/lib/python2.7/dist-packages/enchant/__init__.py", line
735, in __init__
    self.pwl = self._broker.request_pwl_dict(pwl)

  File "/usr/lib/python2.7/dist-packages/enchant/__init__.py", line
280, in request_pwl_dict
    self._raise_error(eStr % (pwl,))

  File "/usr/lib/python2.7/dist-packages/enchant/__init__.py", line
219, in _raise_error
    raise eclass(err)

Error: Couldn't open personal wordlist
'/usr/share/pyshared/leo/plugins/spellpyx.txt'

not a valid dictionary file /usr/share/pyshared/leo/plugins/spellpyx.txt
wrote recent file: /home/ville/.leo/.leoRecentFiles.txt
ville@ville-tp:~$ leo

** isPython3: False
Leo 4.10 final, build 5020, 2012-02-26 13:18:08 -0600
Python 2.7.3, qt version 4.8.1
linux2
reading settings in /usr/share/pyshared/leo/config/leoSettings.leo
Using default leo file name:
/home/ville/.leo/workbook.leo
Traceback (most recent call last):

  File "/usr/lib/pymodules/python2.7/leo/core/leoEditCommands.py",
line 10372, in __init__
    self.d = enchant.DictWithPWL(language,fn)

  File "/usr/lib/python2.7/dist-packages/enchant/__init__.py", line
735, in __init__
    self.pwl = self._broker.request_pwl_dict(pwl)

  File "/usr/lib/python2.7/dist-packages/enchant/__init__.py", line
280, in request_pwl_dict
    self._raise_error(eStr % (pwl,))

  File "/usr/lib/python2.7/dist-packages/enchant/__init__.py", line
219, in _raise_error
    raise eclass(err)

Error: Couldn't open personal wordlist
'/usr/share/pyshared/leo/plugins/spellpyx.txt'

not a valid dictionary file /usr/share/pyshared/leo/plugins/spellpyx.txt
wrote recent file: /home/ville/.leo/.leoRecentFiles.txt

</t>
<t tx="ekr.20130926053913.16343">https://bugs.launchpad.net/leo-editor/+bug/1099035

The new kill-to-end-of-line command is supposed to work just
like the emacs kill-line command. That is, it kill from the
insert point to the end of the line. If there are no
non-blank characters to the right of the insert point, it
kills everything up to and including the newline.
</t>
<t tx="ekr.20130926053913.16344">https://bugs.launchpad.net/leo-editor/+bug/1208659

The compare failure was the result of using baseScannerClass.startsString.
This is wrong: single quotes do *not* start strings in xml or html.

Added better traces when the comparison fails.

Another change: if the @auto import fails, the file is imported as usual
(with an @ignore node). That is, no @edit node is created. This disables a
dubious feature.

Alas, reportMismatch can't possibly detect tokenizing errors: reportMismatch
only has the imported lists of *lines* for the error report, not the
tokens.
</t>
<t tx="ekr.20130926053913.16345">https://bugs.launchpad.net/leo-editor/+bug/1182864

The fix was to countLinesHelper.
</t>
<t tx="ekr.20130926053913.16346">The problem was that no standard bindings were created for the spell tab.
This is done in leoQtLog.createTab.  Yes, it's a terrible hack.

Changed cycleAllFocus,leoQtLog.createTab and DynamicWindow.createSpellTab.
</t>
<t tx="ekr.20130926053913.16347">Found empty methods using: ^[ ]*def.*$(\n[ ]*)*pass
    
Removed all calls to unused methods in qtGui.
    
Rev 6016:
- Removed all definitions and calls to createBindings.
  All definitions were empty.
  
Rev 6017:
- Removed all definitions and calls of createFindPanel.
  All definitions were empty.
- Removed call to createFrame in findTab ctor in leoFind.py.
  The gui code creates the frame.
- Removed all calls to createRootWindow and recreateRootWindow
- Removed do-nothing leoQtFindTab.createFindTab and leoQtFindTab.createFrame.
- Removed all definitions and calls of setBindings.
  All definitions were empty.
  
Rev 6017:
- Removed all definitions of killGui, createRootWindow and recreateRootWindow.
  All definitions were empty and they were never called.
- Removed all definitions of interrupt.  All were do-nothings.
  Removed a single call to .interrupt in 
- Removed do-nothing def of colorizer.kill.  Never called.

Rev 6018:
- Removed do-nothing def of setCanvasBindings.  Never called.
- Removed LeoQTreeWidget.dragEvent.  Never called.
- Removed all definitions of isSameColorState.  It always returned True.
  Removed the single usage of isSameColorState.
- Removed all definitions of killPopupMenu.
  Removed the only call to killPopupMenu in backlink.py.
- Removed all definitions of gui.color.  Never called.
- Removed qtFrame.enable, qtFrame.disable and qtFrame.isEnabled. Never called.
- Removed all calls to getFrame.  They were never called and they always returned None.
- Removed all calls to onActivate.  They were never called and did nothing.

Rev 6019:
* Removed leoQtLog do:nothings, and any calls in Leo's core.
    No calls: configureBorder,configureFont,getFontConfig.
    Commented out calls to setColorFromConfig and setFontFromConfig.
- Removed leoQtLog: saveAllState, restoreAllState, SetWidgetFontFromConfig, forceLogUpdate.
- Removed HighLevelInterface: onActivateLog, disable, enable.
- Removed *all* defs of setFocus.  They are never called!
- Removed all defs of setTabBindings and one call.  All defs were do-nothings.
- Ditto for setMinibufferBindings and createBindings.  All defs were do-notings.
* Removed tree methods: headWidth,widthInPixels,
    setEditLabelState,setUnselectedLabelState,
    setDisabledHeadlineColors,setEditHeadlineColors,setUnselectedHeadlineColors,
    setFont,getFont.
</t>
<t tx="ekr.20130926053913.16348">Added qtGui.setFilter and used it to simplify the code.

The new code is only enabled if the newFilter is set at the start of qtGui.pyi
</t>
<t tx="ekr.20130926053913.16349">Added c.insertHeadlineBefore and unit tests for same.
</t>
<t tx="ekr.20130926053913.16350">Typed tab while autocompleting:  The fix was adding a better guard in tab_callback.

</t>
<t tx="ekr.20130926053913.16353">Made the following changes:

1. The \: convention is deprecated in @data abbreviations-subst-env nodes.
   The \: will be stripped from such nodes, but will appear in neither the
   \@data abbreviations-subst-env node nor the @data abbreviations examples
   node in leoSettings.leo.

2. Refactored the code in abbrevClass.finishCreate into three parts, mostly
   so each may have its own docstring.

3. Added try/finally protection in the exec statement, so that errors in
   \@data abbreviations-subst-env do not cause problems during startup.

4. Added a new setting: @bool scripting-abbreviations, default False.
   Scripting abbreviations will be enabled if *either* of the following is
   True::

        @bool scripting-abbreviations
        @bool scripting-at-script-nodes
    
    This is a safety feature: it allows scripting abbreviations to be
    enabled *without* enabling the (very dangerous in general)
    scripting-at-script-nodes setting.

5. finishCreate always reports either::

        Abbreviations on
        Abbreviations off

    in the normal operating environment (not unit testing, not null gui,
    not batch mode, etc.) As a result, there is less need to issue the
    following message::

        Note: @abbreviations-subst-start found, but no substitutions without @scripting-at-script-nodes = True"

6. Changed @data abbreviations-subst-env node to handle missing os.environ['LOGNAME'].

7. To make this work, the doData parser in leoConfig.py no longer strips lines.
</t>
<t tx="ekr.20130926053913.16354">https://bugs.launchpad.net/leo-editor/+bug/1229896

The fix was to nodeHistory.select at rev 6042
</t>
<t tx="ekr.20130926053913.16355">https://bugs.launchpad.net/leo-editor/+bug/1226816

The fix was to LM.initWrapperLeoFile.
</t>
<t tx="ekr.20130926053913.16356">If $(HOME)/.leo/.leoRecentFiles.txt does not exist, the only recent file ever is the current file

https://bugs.launchpad.net/leo-editor/+bug/971171

It works for me.  I did make minor changes to rf.writeRecentFileFileHelper.
</t>
<t tx="ekr.20130926053913.16357">https://bugs.launchpad.net/leo-editor/+bug/1160660

The primary fix was to createCompareClones.

The created nodes are also a bit clearer about what the changes are.
</t>
<t tx="ekr.20130926053913.16358"></t>
<t tx="ekr.20130926053913.16359">@language rest

# https://bugs.launchpad.net/leo-editor/+bug/879338

Only the clojure language needed entries in the tables.

The following script finds all language keys lacking a mode file::

@language python

    import glob
    files = glob.glob(g.os_path_finalize_join(g.app.loadDir,'..','modes','*.py'))
    files = [g.shortFileName(z)[:-3] for z in files]
    print('\n'.join(sorted(files)))
    keys = sorted(g.app.language_delims_dict.keys())
    for fn in files:
        if fn not in keys:
            print(fn)
            
The result is::
        
    clojure
    embperl     # A helper mode
    patch       # No comment lines
    phpsection  # A helper mode.
    pseudoplain # No coment lines.
    rtf         # Annotations not exactly a comment.
</t>
<t tx="ekr.20130926053913.16360">import glob
files = glob.glob(g.os_path_finalize_join(
    g.app.loadDir,'..','modes','*.py'))
files = [g.shortFileName(z)[:-3] for z in files]
print('\n'.join(sorted(files)))
keys = sorted(g.app.language_delims_dict.keys())
g.cls()
for key in keys:
    if key not in files:
        print(key)

    ada
    autohotkey
    config
    cpp
    cweb
    elisp
    javaserverpage
    kshell
    noweb
    perlpod
    rapidq
    rst
    tcltk
    typescript
    unknown
    unknown_language
    vim
    vimoutline
    xslt
</t>
<t tx="ekr.20130926053913.16361">https://bugs.launchpad.net/leo-editor/+bug/1090950

A shock: fixing bug 1090950 re resurrected nodes may define Leo 5.0
https://groups.google.com/forum/#!topic/leo-editor/nIl3ud7Tbig


</t>
<t tx="ekr.20130926053913.16362"></t>
<t tx="ekr.20130926053913.16363"></t>
<t tx="ekr.20130926053913.16364"></t>
<t tx="ekr.20130926053913.16365"></t>
<t tx="ekr.20130926053913.16366"></t>
<t tx="ekr.20130928065624.16019">@language rest

https://bugs.launchpad.net/leo-editor/+bug/1168689

You must use "python launchLeo.py --ipython" instead of the ipython.py plugin

The old ipython.py plugin is deprecated: it exists in leo/plugins/obsolete.

The docs of ipython and leo should be updated

https://groups.google.com/forum/?fromgroups#!topic/leo-editor/n5IVGe6fh2k
</t>
<t tx="ekr.20130928065624.16021">@language python

</t>
<t tx="ekr.20130928065624.16022">def runWithIpythonKernel(self):

    try:
        # This try/except does not work.
        # Apparently ipython calls sys.exit on failure.
        import leo.plugins.internal_ipkernel as ipk
    except Exception:
        print('can not import leo.plugins.internal_ipkernel')
        g.app.ipk = None
        g.app.ipm = None
        g_ipm = None
        g.es_exception()
        return
    g.app.ipk = ipk = ipk.InternalIPKernel()
    if not ipk:
        print('can not init leo.plugins.internal_ipkernel')
        return
    ipk.init_ipkernel('qt')
    ns = ipk.namespace
    ns['g'] = g
    # launch the first shell, 'c' is not defined there
    ipk.new_qt_console()

    @g.command("ipython-new")
    def qtshell_f(event):            
        """ Launch new ipython shell window, associated with the same ipython kernel """
        g.app.ipk.new_qt_console()
        ns['c'] = event['c']

    @g.command("ipython-exec")
    def ipython_exec_f(event):
        """ Execute script in current node in ipython namespace """
        c = ns['c'] = event['c']
        self.execInNamespace(c, c.p, g.app.ipk.namespace)

    # blocks forever here, equivalent of 
    # QApplication.exec_()
    ipk.ipkernel.start()

def execInNamespace(self, c, p, ns):
    """" Needed because c.executeScript doesn't handle ns properly """
    script = g.getScript(c,p)
    try:
        exec(script, ns)
    except:
        g.es_exception()

def runMainLoop(self):

    '''Start the Qt main loop.'''

    g.app.gui.dismiss_splash_screen()
    if self.script:
        log = g.app.log
        if log:
            g.pr('Start of batch script...\n')
            log.c.executeScript(script=self.script)
            g.pr('End of batch script')
        else:
            g.pr('no log, no commander for executeScript in qtGui.runMainLoop')
    elif g.app.useIpython and g.app.ipm:
        # g.app.ipm exists only if IPython was imported properly.
        self.runWithIpythonKernel()
    else:
        # This can be alarming when using Python's -i option.                           
        sys.exit(self.qtApp.exec_())
</t>
<t tx="ekr.20130928065624.16023">Leo finally caught up with modern IPython ;-).

I added support for the client/server ipython architecture, where Leo
process runs an ipython "kernel", and terminal sessions can connect to it
from other processes. So you can launch a new xterminal, and connect an
ipython ui session (qt or terminal based).

Branch is here:

https://code.launchpad.net/~villemvainio/leo-editor/ipkerneldemo

Launch leo by "python launchLeo.py --ipython"

You should see a terminal being launched.

You can do alt-x ipython-new to launch new terminals (connected to the same
kernel)

You need to install some dependencies to get this working. Try "sudo pip
install ipython matplotlib" at least. This may fail if you don't have c
compiler set up correctly; I leave it to others to repeat this and compose
better instructions.

Screenshot attached. "c" is available because I launched the session with
alt-x ipython-new
</t>
<t tx="ekr.20130928065624.16024">===== EKR

But the old push-to-ipython command crashes. Is there a way to pass scripts
from Leo to ipython?

===== Ville

At least push-to-ipython can evaluate scripts in ipython namespace (you can
see where that namespace dict is from my code).

Now that we know it works on windows as well, do you want me to merge the
code with leo trunk?

Also, enthought python distribution has PyQt too? Maybe it could be a good
recommendation for Windows users to use that when installing Leo on blank
machine...
</t>
<t tx="ekr.20130928065624.16025">Added a new command: alt-x ipython-exec

This executes the currently selected node/script in ipython kernels
namespace

This is a replacement for the old push-to-ipython command.

-----

valuespace.py is now adapted to use ipython namespace at all times, if it's
enabled (with --ipython command line switch).

It's hard to briefly explain what valuespace plugin does and how it relates
to ipython, but if you are curious check out Contrib branch
Projects/valuespace.

Basically, it provides a "workbook" like way to get data from Leo document
to the namespace, and do calculations based on that data. Having this data
be accessible to the ipython instance makes it convenient to interact and
poke around with the same data.
</t>
<t tx="ekr.20130928065624.16026">alr

Bug 1168689 "outdated documentation about ipython" is misnamed. I have
been tweaking Leo's IPython-related code as described below. I still hope
to release b1 tomorrow, but I'll delay another day if there are problems.

Recent revs have updated Leo's code relating to IPython as follows:

- The old ipython.py plugin has demoted to leo/plugins/obsolete.

- internal_ipkernel.py (the code called when the user gives the --ipython
  option) now can import the IPKernelApp class regardless of which version
  (0.x or 1.x) of IPython is in effect.

The --ipython option works on Ubuntu; it *might* work on Windows, but I'm
having installation problems.

Questions:

1. Is anyone using IPython with Leo successfully on Windows?

2. I don't see any way to access Leo's data from IPython? In particular,
   internal_ipkernel.py injects no _leo object into the IPython namespace.
   Is this intentional?
</t>
<t tx="ekr.20130928065624.16027">'c' is available because I launched the session with alt-x ipython-new"

The --python option injects "g" into the namespace right away.

g.app.ipk is an instance of the InternalIPKernel class defined in
internal_ipkernel.py.

g.app.ipk.namespace is the IPython namespace(!)
</t>
<t tx="ekr.20130928065624.16028">https://github.com/zeromq/pyzmq/downloads

pyzmq-2.2.0.win32-py2.7.msi
</t>
<t tx="ekr.20131001045038.17448">This idea got started when I (Ville M. Vainio) saw this post by Edward Ream
on IPython developer mailing list:
http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html

I was using FreeMind as mind mapping software, and so I had an immediate
use case for Leo (which, incidentally, is superior to FreeMind as mind
mapper). The wheels started rolling, I got obsessed with the power of this
concept (everything clicked together), and Edwards excitement paralleled
mine. Everything was mind-bogglingly easy/trivial, something that is
typical of all promising technologies.

The goal of close cooperation between Leo and IPython went from vague dream
to completed reality over the span of about 10 days. The IPython bridge has
continued to evolve since then.
</t>
<t tx="ekr.20131001045038.18979">The IPython bridge turns Leo into another kind of `IPython Notebook`_.
IPython users typically use %edit to produce non-trivial functions/classes
instead of entering them directly on the interactive prompt. But this is a
bit clumsy. With Leo, *every Leo node works like an IPython %edit file*:

- You can execute any Leo node in IPython with &lt;Alt-I&gt; (ipython-exec)
- Saving your Leo outline saves all your IPython scripts.
- You can use Leo as always to organize all your IPython scripts.
</t>
<t tx="ekr.20131001045038.18980">*You can run any IPython script from Leo*. Leo's ipython-exec (Alt-I)
command executes the body text of the presently selected Leo node in the
address space of the IPython shell. Such scripts *immediately* affect the
IPython interpreter.

The IPython bridge sets several global variables *within Leo*, allowing Leo
scripts *complete* access to all of IPython's code and data:

- g.app.ipk.namespace is IPython's namespace.
- g.app.ipk.ipkernel is an IPython IPKernelApp object.
- g.app.ipk.ipkernel.shell is an IPython InteractiveShell object.
</t>
<t tx="ekr.20131001045038.18981">*You can run any Leo script from IPython*. The IPython bridge injects an
object called _leo into IPython's namespace. IPython scripts may access
Leo's c and g objects as follows::

    c,g = _leo.c, _leo.g

This allows IPython scripts to do *anything* that a Leo script can do.
Scripts run from IPython *immediately* change Leo, *exactly* as if the
script were run from Leo.

**Important**: the _leo object is an instance of LeoNameSpace class,
defined in leo.core.leoIPython.py. This class allows IPython scripts to
access multiple Leo outlines at once. See the actual code for details.
</t>
<t tx="ekr.20131001100236.15925">@language rest
</t>
<t tx="ekr.20131001100236.15926">You can do alt-x ipython-new to launch new terminals (connected to the same
kernel)

You need to install some dependencies to get this working. Try "sudo pip
install ipython matplotlib" at least. This may fail if you don't have c
compiler set up correctly; I leave it to others to repeat this and compose
better instructions.
</t>
<t tx="ekr.20131001100236.15927">valuespace.py is now adapted to use ipython namespace at all times, if it's
enabled (with --ipython command line switch).

It's hard to briefly explain what valuespace plugin does and how it relates
to ipython, but if you are curious check out Contrib branch
Projects/valuespace.

Basically, it provides a "workbook" like way to get data from Leo document
to the namespace, and do calculations based on that data. Having this data
be accessible to the ipython instance makes it convenient to interact and
poke around with the same data.
</t>
<t tx="ekr.20131001100236.15928">Injects only _leo into the IPython namespace
_leo.c is a property
The getter returns the single element of _leo.commanders_list
or a commander set previously by the setter.
    
_leo.commanders is a read-only property returning _leo.commanders_list
after first doing an update.

-----

The highlights of the changes:

1. leo.core.leoIPython.py now contains *all* of Leo's IPython-related code.
   The setup code comes mainly from leo.plugins.internal_ipkernel.py.

2. internal_ipkernel.py still exists (it will go away soon), but it has has
   been completely disabled as follows::

    if 0:
        @others

3. When the --ipython command-line argument is in effect, g.app.ipk is a
   *singleton* IPython shell, shared by any and all IPython consoles.

4. The startup code injects only a single object, _leo, into the IPython
   namespace. This is an instance of the bulked-up LeoNameSpace class. This
   interface class now contains features that make it easier to deal with
   multiple open Leo commanders.

- _leo.g is set to leoGlobals only once. Not exactly correct, perhaps, but
  nobody will notice.

- _leo.commanders is a (read-only) property returning the list of open
  commanders. This list is always kept up-to-date: it scans
  g.app.windowList before returning its result.

- _leo.c is a (read/write) property returning g.app.windowList[0].c if the
  windowList has only one element, or the "designated commander" if it
  exists. Otherwise, it returns None. In that case, the expectation is that
  the user will "designate" a commander with: _leo.c = aCommander.

- _leo.find_c(path) returns the commander c such that c.fileName() or
  g.shortFileName(c) matches path.

5. Perhaps most importantly, that's *all* there is. In particular, Ville's
   magic functions and LeoWorkbook class are gone.

Imo, the deleted code might better exist as IPython startup code, but I
could be wrong. Furthermore, Leo's p.h and p.b properties are new since
Ville first created the code, and so this kind of support code is less
urgently needed.

If there is a great demand to restore these features, it can always be done
later. For now, though, I wanted to do the simplest thing that could
possibly work.
</t>
<t tx="ekr.20131001100335.15938">Ctrl-F (search-with-present-options) shows the Find Tab and puts the focus
in the minibuffer. |br|
**Important**: the Find tab just shows you the status of search and replace
operations. |br|
You control those operations from the minibuffer.

**Note**: You can toggle the radio buttons and check boxes in the Find Tab
with Ctrl-Alt keys. For example, Ctrl-Alt-X (toggle-find-regex-option)
toggles the Regexp checkbox.

After typing Ctrl-F, type the search string, say "def", in the minibuffer.

Start the find by typing &lt;Return&gt;.

But suppose you want to replace "def" with "foo", instead of just finding
"foo".

Before typing &lt;Return&gt; type Shift-Ctrl-R. The minibuffer prompts for the
replacement string. Notice that the status area now shows “def” as the Find
string.

Type "foo" and type &lt;Return&gt; to start the find-next command.

When Leo finds the next instance of "def", it will select it. |br|
You may type any command.  The following are most useful:

- Ctrl-minus (replace-then-find) replaces the selected text.
- F3 (find-next) continues searching without making a replacement.
- F2 (find-previous) continues the search in reverse.
- Ctrl-G (keyboard-quit) ends the search.
</t>
<t tx="ekr.20131001100335.15939">The rst3 command converts an @rst tree containing `reStructuredText`_ (rST)
markup into a plain-text **intermediate file** containing *other* rST
markup.

The rst3 command converts headlines within @rst trees to rST markup
(in the intermediate file) denoting rST section headings.

Except for chapter titles, you *never* have to denote section headings with
explicit rST markup; |br|
you reorganize your documents by reorganizing your @rst tree!

The following paragraphs explain how to create documents step by step:
</t>
<t tx="ekr.20131001100335.15940">Leo has a flexible (perhaps *too* flexible) configuration system. It's best
to use this flexibility in a restricted way as follows:

1. The file leo/config/leoSettings.leo contains Leo's default settings.
   Don't change this file unless you are one of Leo's developers.
   
2. The file ~/myLeoSettings.leo contains your personal settings. Leo will
   not create this file automatically: you should create it yourself.
   Settings in myLeoSettings.leo override (or add to) the default settings
   in leoSettings.leo.
   
3. Any other .leo file may also contain settings. Such settings apply only
   to that file and override all other settings. It's best to use such
   settings sparingly.
   
As a result, settings may vary from one Leo file to another. This can be
confusing. These two commands can help:

- print-settings shows each setting and where it came from.
  
- print-bindings shows each key binding and where it came from.

**Important**: within any file, settings take effect **only** if they are
contained in an **@settings tree**, that is, are descendants of a node
whose headline is @settings. Nodes outside @settings trees do not affect
settings in any way.

Within @settings trees, you specify boolean settings with @bool nodes,
string settings with @string nodes, menus with @menus and @menu nodes, etc.
For exact details, please do study leoSettings.leo. You can open either
leoSettings.leo or myLeoSettings.leo from the Help menu. Within
leoSettings.leo:

- The node "About this file" explains about settings.
- The node "Candidates for settings in myLeoSettings.leo" highlights the
  settings you are most likely to want to customize.

</t>
<t tx="ekr.20131001100335.15942">Give differences between Leo and Emacs, Vim &amp; IPython.</t>
<t tx="ekr.20131001100335.15943">- Leo has shamelessly stolen all of Emacs's most important features: long
  command names, the minibuffer, typing completion and flexible key
  bindings.
  
- One set of Leo's default key bindings are similar to Emacs's defaults. If
  you like, editing text in Leo can feel exactly like editing text in
  Emacs.

- You script Leo in Python, not elisp.

- Emacs has no notion of nodes, cloned or otherwise. Emcas will never have
  anything like @file, @test, @button, @command or @url nodes (etc.!), not
  even in Emacs org-mode.
  
- Leo scripts have *easy* access all nodes via Leo's Document Object Model
  (DOM). Emacs has no DOM at all. In Emacs, everything is just text.
  
- Leo has no dired mode because it isn't needed. Once you have created an
  @file node (or @auto or @edit node), there is no need to drill down to
  that file.
</t>
<t tx="ekr.20131001100335.15944">- One set of Leo's default key bindings are similar to Vim's defaults. If
  you like, editing text in Leo can feel somewhat (not exactly) like
  editing text in Emacs.  Leo has a vim-like command mode, but it's
  still a work in progress.

- You script Leo in Python, not Vim's scripting language.

- Vim has no notion of nodes, cloned or otherwise. Vim will never have
  anything like @file, @test, @button, @command or @url nodes (etc.!), not
  even in Vim's outline-mode.
  
- Leo scripts have *easy* access all nodes via Leo's Document Object Model
  (DOM). Vim has no DOM at all; everything is just text.
</t>
<t tx="ekr.20131001100335.15945"></t>
<t tx="ekr.20131001100335.15946">Leo’s minibuffer appears at the bottom of Leo’s main window. You use the
minibuffer to execute commands by name, and also to accumulate arguments to
commands.

Alt-X (full-command) puts the cursor in the minibuffer.

You could type the full command name in the minibuffer, followed by the
&lt;Return&gt; key to invoke the command, but that would be *way* too much work.
Instead, you can avoid most typing using **tab completion**. With tab
completion, there is no need to remember the exact names of Leo’s commands.

For example, suppose you want to print out the list of Leo’s commands. You
might remember only that there are several related commands and that they
all start with "print". Just type::

    &lt;Alt-X&gt;pri&lt;Tab&gt;

You will see "print-" in the minibuffer. This is the longest common prefix
of all the command names that start with "pri". The Completion tab in the log pane
shows all the commands that start with "print-".

Now just type "c&lt;Tab&gt;" and you will see the print-commands command in the
minibuffer.

Finally, &lt;Return&gt; executes the command.

The output of the print-commands command appears in the commands tab, and
focus returns to the body pane.

Summary:

- &lt;Return&gt; executes the command
- &lt;Tab&gt; shows all valid completions.
- &lt;BackSpace&gt; shows more alternatives.
- Ctrl-G exits the minibuffer and puts focus in the body pane.
</t>
<t tx="ekr.20131001100335.15947">F1 (help) shows a help message appears in the viewrendered pane.
Alt-0 (vr-toggle) hides or shows this pane.

F11 (help-for-command) shows the documentation for any Leo command. F11
prompts for the name of a Leo command in the minibuffer. Use tab completion
to see the list of all commands that start with a given prefix.

F12 (help-for-python) shows the documentation from Python's help system.
Typing completion is not available: type the full name of any Python
module, class, function or statement.

These commands clarify which settings are in effect, and where they came
from::

    print-bindings
    print-settings

These commands discuss special topics::

    help-for-abbreviations
    help-for-autocompletion
    help-for-bindings
    help-for-debugging-commands
    help-for-dynamic-abbreviations
    help-for-find-commands
    help-for-minibuffer
    help-for-regular-expressions

Using Leo, especially for programming, requires some learning initially.
Please feel free to `ask for help`_ at any time.
</t>
<t tx="ekr.20131002055813.15973">Here is a slightly reduced screenshot of Leo's main window:

.. image:: screen-shots/render-svg-sources.png
   :alt: Screenshot
   :scale: 80 %
   
.. index::
    pair: Body pane; Tutorial
    pair: Expansion box; Tutorial
    pair: Icon area; Tutorial
    pair: Log pane; Tutorial
    pair: Main Window; Tutorial
    pair: Outline pane; Tutorial
    pair: Status line; Tutorial

Leo's main window consists of
an **icon area** just below the menus,
an **outline pane** at the top left,
a **log pane** at the top right,
a **body pane** at the bottom left,
and an optional **viewrendered pane** at the bottom right.
The **minibuffer** and **status line** lie at the bottom of the main window.

The log pane contains several tabs. The **Log tab** shows messages from
Leo, the **Find Tab** shows the status of Leo's Find/Replace commands.
Other tabs may also appear in the log pane: The **Spell Tab** controls
Leo's spell-checking. The **Completion Tab** shows available typing
completions.

.. index::
    pair: Icon box; Tutorial
    pair: Node; Tutorial
    pair: Headline; Tutorial
    pair: Body text; Tutorial

Leo stores all data in **nodes**. Nodes have **headlines**, shown in
the outline pane, and **body text**. The body pane shows the body text of
the **presently selected node**, the node whose headline is selected in the
outline pane.  Headlines have an **icon box** indicating a nodes status.
For example, the icon box has a black border when the node has been changed.
</t>
<t tx="ekr.20131002055813.19036">You may select, expand and contract outline nodes with the mouse as usual,
but using arrow keys is *highly recommended*.

When focus is in the outline pane, *plain* arrows keys change the selected node:

- Right-arrow (expand-and-go-right) expands a node or selects its first child.
- Left-arrow (contract-or-go-left) contracts a node if its children are visible,
  and selects the node's parent otherwise. 
- Up-arrow (goto-prev-visible) selects the next *visible* outline node.
- Down-arrow (goto-next-visible) selects the previous *visible* outline node.
  
When focus is in the outline pane, Shift-arrow keys move the selected node
in the direction of the arrow, if possible.

Regardless of focus, Alt-arrow and Alt-Shift-arrow keys work on outline nodes:

- Alt-Home (goto-first-visible-node) selects the first outline node.
- Alt-End (goto-last-visible-node) selects the last *visible* outline node.
- Alt-arrow keys select the outline pane, and then act just like the plain
  arrow keys when the outline pane has focus.
- Alt-Shift-arrow keys select the outline pane and move the selected node.

The following commands work anywhere, regardless of focus:

- Ctrl-D (move-outline-down) moves the selected node down.
- Ctrl-L (move-outline-left) moves the selected node left.
- Ctrl-R (move-outline-right) moves the selected node right.
- Ctrl-U (move-outline-up) moves the selected node up.
</t>
<t tx="ekr.20131002055813.19037">When focus is in any of Leo's text panes (body pane, log pane, headlines),
Leo work like most text editors:

- Plain arrow keys move the cursor up, down, left or right.
- Ctrl-LeftArrow and Ctrl-RightArrow move the cursor by words.
- Home and End move the cursor to the beginning or end of a line.
- Ctrl-Home moves the cursor to the beginning of the body text.
- Ctrl-End moves the cursor to the end of the body text.
- PageDown and PageUp move the cursor up or down one page.

**Note**: As usual, adding the Shift key modifier to any of the keys above
moves the cursor and extends the selected text.
</t>
<t tx="ekr.20131002055813.19835">Ctrl-I or Insert (insert-node) inserts a new node into the outline.

Regardless of focus, Ctrl-H (edit-headline) begins editing the headline of
the selected node.  |br|
When editing a headline, &lt;Return&gt; (end-edit-headline) ends the editing,
leaving the focus in the body pane.

Ctrl-Shift-C (copy-node) copies the outline and all it's descendants,
placing the node on the clipboard. |br|
Ctrl-Shift-X (cut-node) cuts the outline and all its descendants, placing
the node on the clipboard. |br|
Ctrl-Shift-V (paste-node) pastes a node (and its descendants) from the
clipboard after the presently selected node.

Ctrl-{ (promote) makes all the children of a headline siblings of the
headline. |br|
Ctrl-} (demote) makes all following siblings of a headline children of the
headline. |br|
The demote and promote commands are useful for gathering nodes together before
moving or cutting them.

Ctrl-M (mark) toggles the mark on a node. |br|
Marked nodes have a vertical red bar in their icon area.

</t>
<t tx="ekr.20131002055813.19837">Leo has unlimited undo--Leo remembers *all* changes you make to outline
structure or the contents of any node since you restarted Leo.

Ctrl-Z (undo) undoes the last change. Another Ctrl-Z undoes the
previous change, etc. 

Ctrl-Shift-Z (redo) undoes the effect of the last undo, etc.

The first two entries of the Edit menu show what the next undo or redo
operation will be.
</t>
<t tx="ekr.20131002211347.6456">Every Leo command has a **command name**. In this document, keystrokes that
invoke a command will be followed by the command name in parentheses.

For example, Ctrl-S (save-file) saves a Leo file.

The full-command (Alt-X) command executes any other command by typing its
full name. For full details see `The minibuffer &amp; completions`_.
</t>
<t tx="ekr.20131003040744.18221">Leo stores outline data on your file system in **.leo files**.

Rather than storing all your data in the .leo file, you may store parts of
your outline data in **external files**, files on your file system.

**@file nodes** create external files. @file nodes have headlines starting
with @file followed by a file name::

    @file leoNodes.py
    @file ../../notes.text
    
.. index::
    pair: Dirty node; Tutorial

Leo reads external files automatically when you open Leo outline, and
writes all **dirty** (changed) external files when you save any Leo
outline.

The **@all** directive tells Leo to write the **@file tree** (the @file
node and all its descendants) to the external file in **outline order**,
the order in which the nodes appear in the outline pane when all nodes are
expanded. Non-programmers will typically use the @all directive;
programmers typically use the @others directive, as discussed in the
`programming tutorial`_.

When writing @file nodes, Leo adds **sentinel comments** to external files.
Sentinels embed Leo's outline structure into external files.

If you don't want sentinels in your sources, skip head to
the `Using @auto nodes`_ part of Leo's `programming tutorial`_.
</t>
<t tx="ekr.20131003040744.18222">The @others directive, and markup called section references (see below),
tell Leo how to create external files.

**Essential Terms**:

- A **section name** is any text of the form: &lt;&lt; any text &gt;&gt;.
  (&gt;&gt; must not appear in "any text".)
- A **section definition node** is any node whose headline starts with a
  section name.
- A **section reference** is a section name that appears in body text.

Leo creates external files containing @others directives by writing the
*expansion* of the @file node. |br|
The **expansion** of *any* node is
then ode's body text after making these text **substitutions**:

1. Leo replaces @others with the *expansion* of all descendant nodes
   **except** section definition nodes. That's how @others got its name.

2. Leo replaces section references by the *expansion* of the body text of
   the corresponding section definition node.
   
Whitespace is significant before @others and section references. Leo adds
the leading whitespace appearing before each @others directive or section
reference to every line of their expansion. As a result, Leo can generate
external files even for Python.  The following cute trick works::

    if 1:
        &lt;&lt; a section &gt;&gt;
    if 0:
        @others

**Notes**:

- Any node may contain a single @others directive. No node may contain more
  than one @others directive.

- Nodes that *aren't* section definition nodes are included in the expansion
  of the *nearest* ancestor node containing an @others directive.

- An **orphan node** is a descendant of an @file node not included in any
  substitution. Leo refuses to write external files containing orphan
  nodes. Instead, Leo writes the @file tree to the .leo file itself,
  thereby preserving all data.

**Example 1**: The body of the @file node for a typical Python module will
look something like::

    '''A docstring.'''
    &lt;&lt; imports &gt;&gt;
    @others
    if __name__ == '__main__':
        main()
        
**Example 2**:  Here is a typical Python class definition in Leo::

    class MyClass:
        '''A docstring.'''
        @others
</t>
<t tx="ekr.20131004064408.16020">.. index::
   pair: Directive; Tutorial

**Directives** control Leo's operations.
Directives start with '@' in the leftmost column.

Directives may appear either in headlines or body text.

Directives apply until overridden by the same (or related) directive in a
descendant node.

Some commonly used general-purpose directives:

.. index::
    pair: @color; Tutorial
    pair: @nocolor; Tutorial
    pair: @killcolor; Tutorial

::

    @color
    @killcolor
    @nocolor

These control whether to syntax color text. 

Nodes may contain multiple color directives.

Nodes containing multiple color directives do not affect coloring of
descendant nodes.
    
.. index::
    pair: @language; Tutorial

::

    @language python
    @language c
    @language rest # restructured text
    @language plain # plain text: no syntax coloring.
    
These control which language to use when syntax coloring text.

.. index::
    pair: @pagewidth; Tutorial
    
::

    @pagewidth 100
    
Sets the page width used when formatting paragraphs.

.. index::
    pair: @tabwidth; Tutorial
    pair: Negative tab width; Tutorial

::

    @tabwidth -4
    @tabwidth 8
    
Sets the width of tabs.

Negative tab widths cause Leo to convert tabs to
spaces and are highly recommended for Python programming.

..  .. index::
    ..  pair: @wrap; Tutorial
    ..  pair: @nowrap; Tutorial
    
::

    @nowrap
    @wrap

These enable or disable line wrapping in the body pane.
</t>
<t tx="ekr.20131004073415.16044">..  .. index::
    ..  pair: Clone; Tutorial
    
A **clone** is a node that appears in more than one place in a Leo outline. |br|
Clones are marked with a small red arrow in its icon box.

.. .. image:: images/box13.GIF
..    :scale 200 %
..    :alt: Leo Icon Box With Clone Mark

All clones of a node are actually *the same node*. |br|
Any change to one clone affects all clones. |br|
Inserting, moving or deleting any child of a clone will change all other clones on the screen.

Clones allow data to be stored in *arbitrarily many* places within an outline.

Please take a few moments to experiment with clones:

- Create a node whose headline is A.
- Ctrl-` (clone-node) clones node A.
- Type some text into the body of A.
- All clones of A now have the same body.
- Insert a node, say B, as a child of any of the A nodes.
- All the A nodes now have a B child.
- See what happens if you clone B.
- See what happens if you insert, delete or move nodes that are children of A.
- When you delete a node's penultimate clone,
  the last clone becomes a regular node again.

</t>
<t tx="ekr.20131004191204.16079">Alt-0 (vr-toggle) hides or shows the viewrendered pane.

&lt;Return&gt; puts focus in the body when it is in the outline pane. |br|
Alt-T (focus-to-tree) puts focus in the outline pane.  |br|
Ctrl-T (toggle-active-pane) toggles focus between the outline and body panes.

You may open multiple Leo outlines in different tabs within the same main
window. |br|
Ctrl-Tab (tab-cycle-next) switches between outline tabs.

Ctrl-N (new) creates a new outline in a new tab. |br|
Ctrl-O (open-outline) opens an existing .leo file. |br|
Ctrl-S (save-file) saves the outline. |br|
Ctrl-Q (exit-leo) exits Leo.  Leo will prompt you to save any unsaved outlines.
</t>
<t tx="ekr.20131005214621.16088"></t>
<t tx="ekr.20131005214621.16089">Leo uses a TOC that *looks* like a Sphinx toc but is built by hand.</t>
<t tx="ekr.20131005214621.16090">- Every command has a name.
- You may execute any command by name from the minibuffer.
- Many commands are bound to keystrokes.
- You may bind multiple keystrokes to a single command and change bindings to your taste.
- Leo has commands to create, change and reorganize outlines.
- Within the body pane, Leo uses standard key bindings to move the cursor.
- Ctrl-F starts the find command. Use the minibuffer to complete the command.
- Leo's configuration files specify all settings, including key bindings.
- Leo directives control how Leo works.
- @all creates an external file from all the nodes of an outline.
- Enable plugins using @enabled-plugins nodes in an @settings tree.
</t>
<t tx="ekr.20131005214621.16128">- The rst3 command converts an @rst tree to an external rST text file.

- Settings starting with "rst3" govern how the rst3 command works.

- Within @rst trees, headlines become rST sections. |br|
  Sections levels in the generated rST correspond to outline levels in Leo.

- You can reorganize your rST documents without changing any rST markup in
  your outline.
  
- The rst3 command works acts on the nearest ancestor @rst node, if any, or
  on all descendant @rst nodes.
  
- @rst-no-head nodes insert text (or markup) without an rST headline.

- @rst-ignore nodes are a way of commenting out text.

- The rst3 command provides *many* other capabilities. For details, see
  `the rst3 chapter`_.</t>
<t tx="ekr.20131005214621.16130">This is a reference for all of Leo's directives.

This sections assumes you are *thoroughly* familiar with `Leo's tutorial`_.

</t>
<t tx="ekr.20131007143750.16070">#################
Leo's Cheat Sheet
#################

.. |br| raw:: html

   &lt;br /&gt;
   
.. _`Directives reference`: directives.html
.. _`Commands Reference`: commands.html
.. _`userAttributes`: customizing.html#adding-extensible-attributes-to-nodes-and-leo-files
.. _`Customizing Leo`: customizing.html

.. contents::
    :depth: 4
</t>
<t tx="ekr.20131007143750.16074">This sections lists the ivars, properties, functions and methods most
commonly used in Leo scripts.

**Very important**: use Alt-1 (toggle-autocompleter) and Alt-2
(toggle-calltips) to recreate these lists as you type.
</t>
<t tx="ekr.20131007143750.16111"></t>
<t tx="ekr.20131008041326.16053">A plugin is a Python file in Leo's plugins folder.

Every plugin should have a top-level init function that returns True if the
plugin has been initialized properly. The init function typically:

1. Registers an onCreate event handler, called when Leo creates a new window.
2. Calls g.plugin_signon(__name__)

For example::

    def init():
        if &lt;&lt; all imports successful &gt;&gt;:
            g.registerHandler('after-create-leo-frame',onCreate)
            g.plugin_signon(__name__)
            return True
        else:
            return False
   
Plugins do *not* have automatic access to c, g and p.

Plugins define g by importing it::

    import leo.core.leoGlobals as g
    
Plugins gain access to c using event handlers::

    controllers = {}
    
    def init():
        g.registerHandler('after-create-leo-frame',onCreate)
        return True
        
    def onCreate (tag, keys):
        global controllers
        c = keys.get('c')
        if c:
            hash = c.hash()
            if hash not in controllers.keys():
                controllers(hash) = PluginController(c)
            
    def eventHander(tag,keys):
        global controllers
        c = keys.get('c')
        if c:
            controller = controllers.get(c.hash())
            controller.handleEvent()
            
Some plugins inject ivars into the Commands class rather than using
a global controllers dict::

    def onCreate (tag, keys):
        c = keys.get('c')
        if c:
            c.my_plugin_controller = ControllerClass(c)
            
    def eventHander(tag,keys):
        c = keys.get('c')
        if c:
            c.my_plugin_controller.handleEvent()

Once c is determined, the presently selected position is simply c.p.
</t>
<t tx="ekr.20131008041326.16054">..  .. index::
    ..  pair: @first; Tutorial

The @first directive forces lines to appear before the first sentinel of a
external file. For example::

    @first #! /usr/bin/env python
    @first # -*- coding: utf-8 -*-
    
..  .. index::
    ..  pair: @last; Tutorial
    
Similarly, @last forces lines to appear after the last sentinel.
</t>
<t tx="ekr.20131008041326.16055">..  .. index::
    ..  pair: @path; Tutorial

Rather than specifying long paths in @file nodes, you can specify a path in
an ancestor @path node.

For example, suppose three nodes have the following headlines::

    @path a
        @path b
            @file c/d.py

The @file node creates the file a/b/c/d.py

Within @path and @&lt;file&gt; paths, {{exp}} gets evaluated with the following
predefined symbols: c, g, p, os and sys.  For example::

    @file {{os.path.abspath(os.curdir)}}/abc.py
</t>
<t tx="ekr.20131008041326.16056">Use @auto instead of @file when you don't want to add sentinels in the file.

.. index::
    pair: Importer; Tutorial

When reading @auto files, Leo **importers** create an outline from the
external file. Importers create nodes for each class, method and function
in the external file.

Notes:

- Leo determines the language using the file's extension.

- Importers exist for C, C#, elisp, html, .ini files, Java, Javascript,
  Pascal, PHP, Python, TypeScript, vimoutliner files and xml.

- If no importer exists for a file, Leo reads the entire file into an @edit
  node.

</t>
<t tx="ekr.20131008041326.16058">Leo's unit test commands (&lt;Alt-X&gt;run&lt;tab&gt; gives the full list)
create unit tests from the body text of @test nodes.

- The headline gives the name of the test::

    @test test that g is predefined
    
- The body contains the unit test::

    assert g
    
- The unit test commands convert the body to a subclass of
  unittest.TestCase.  This saves a lot of typing.
  
- The unit test commands predefine c, g, and p as usual.

- 'self' is predefined as the test itself, that is, the instance of
  unittest.TestCase created by the @test node. For example::
  
    self.assertTrue(g)

.. _`Leo's unit-testing reference`: unitTesting.html
    
For more details, see `Leo's unit-testing reference`_.
</t>
<t tx="ekr.20131008041326.16065"></t>
<t tx="ekr.20131008041326.16066">Clones are nodes appearing multiple places in the outline.

    - Changes to one clone affect all other clones.
    - All clones of a node are *exactly the same node*.

Views allow multiple views of data to exist in a single outline.

    - A view is simply a collection of nodes.
    - Because of clones, a node may appear in many views at once.
    - View focus attention on tasks and reduce searching for nodes.

Leo expands abbreviations as you type.

    - Abbreviations range from simple shortcuts to multi-line templates
      containing fields.
    - Type ",," to move to the next field.
    - Abbreviations can also insert the result of executing code.
    
Ctrl-left-clicking any URL opens the URL.
</t>
<t tx="ekr.20131008041326.16079">#############
Preliminaries
#############

.. contents::
    :depth: 2
</t>
<t tx="ekr.20131008041326.16080"></t>
<t tx="ekr.20131008041326.16082">#################
Leo's Users Guide
#################

.. toctree::
   :maxdepth: 2

   customizing
   rstplugin3
   plugins
   directives
   commands
</t>
<t tx="ekr.20131008041326.16091">@language rest
</t>
<t tx="ekr.20131008041326.16092"></t>
<t tx="ekr.20131008041326.16094">##############
Installing Leo
##############

.. Links used in this document...

.. _`Leo's download page`:  http://sourceforge.net/project/showfiles.php?group_id=3458&amp;package_id=29106
.. _`Leo's help forum`:     http://groups.google.com/group/leo-editor
.. _`PyEnchant`:            https://sourceforge.net/projects/pyenchant/
.. _`PyQt`:                 http://www.riverbankcomputing.com/software/pyqt/intro
.. _`Python`:               http://www.python.org
.. _`Running Leo`:          running.html
.. _`ask for help`:         https://groups.google.com/forum/#!forum/leo-editor
.. _`bzr`:                  http://bazaar.canonical.com/

.. index:: Installing Leo

This chapter tells how to install and run Leo on Windows or Linux.
Leo can be installed on MacOS, but the process is difficult and not recommended.

**Important**: If you have *any* problems installing Leo,
please ask for help on `Leo's help forum`_.

.. contents::
    :depth: 2
    
</t>
<t tx="ekr.20131008041326.16099">###################
Advanced Topics
###################

.. toctree::
   :maxdepth: 2

   coloring
   writingPlugins
   unitTesting
   debuggers
   
.. toctree::
   :maxdepth: 1

   atShadow
   design
   scripting-miscellany
   theory
   leonine-world
</t>
<t tx="ekr.20131008041326.16100">######################
Leo and Other Programs
######################

.. toctree::
   :maxdepth: 2

   emacs
   IPythonBridge
   leoBridge
   vimBindings
   zodb

</t>
<t tx="ekr.20131008041326.16109">.. Gives details about expanding @others and section references.</t>
<t tx="ekr.20131008041326.16140">##############
Running Leo
##############

.. index:: Running Leo

This chapter tells how to run Leo and discusses Leo's command-line
options.

.. contents::
    :depth: 2
    
</t>
<t tx="ekr.20131008041326.16151">You can run Leo from a Python interpreter as follows::

    import leo
    leo.run() # runs Leo, opening a new outline or,
    leo.run(fileName=aFileName) # runs Leo, opening the given file name.

Another way to run Leo is as follows::

    cd &lt;path-to-launchLeo.py&gt;
    python launchLeo.py %*

Here are some tips that may make running Leo easier:

**Linux**
    
The following shell script will allow you to open foo.leo files by typing leo foo::

    #!/bin/sh 
    python &lt;leopath&gt;launchLeo.py $1

where &lt;leopath&gt; is the path to the directory containing the leo directory. 

**Windows**

You can associate Leo with .leo files using a batch file. Put the
following .bat file in c:\\Windows::

    &lt;path-to-python&gt;/python &lt;path-to-leo&gt;/launchLeo.py %*

Here &lt;path-to-leo&gt; is the path to the directory *containing* the leo directory,
that is, the directory containing launchLeo.py.
</t>
<t tx="ekr.20131008041326.16152">The first time you start Leo, a dialog will ask you for a unique identifier. If
you are using a source code control system such as bzr, use your bzr login name.
Otherwise your initials will do.

Leo stores this identifier in the file .leoID.txt. Leo attempts to create
leoID.txt in the .leo sub-directory of your home directory, then in Leo's config
directory, and finally in Leo's core directory. You can change this identifier
at any time by editing .leoID.txt.
</t>
<t tx="ekr.20131008041326.16153" rst_http_attribute="5d71002858460000003c6120636c6173733d22746172676574222069643d22687474702d6e6f64652d6d61726b65722d333722206e616d653d22687474702d6e6f64652d6d61726b65722d3337223e710158040000003c2f613e71025d71032858260000003c64697620636c6173733d2273656374696f6e222069643d22672d726566696e64616c6c223e710458060000003c2f6469763e71055d710628584f0000003c64697620636c6173733d2273656374696f6e222069643d2266756e6374696f6e732d666f722d66696e64696e672d616e642d6368616e67696e672d746578742d66726f6d2d73637269707473223e710758060000003c2f6469763e71085d710928583f0000003c64697620636c6173733d22646f63756d656e74222069643d22636861707465722d372d736372697074696e672d6c656f2d776974682d707974686f6e223e710a58060000003c2f6469763e710b5d710c2858060000003c626f64793e710d58070000003c2f626f64793e710e5d710f2858430000003c68746d6c20786d6c6e733d22687474703a2f2f7777772e77332e6f72672f313939392f7868746d6c2220786d6c3a6c616e673d22656e22206c616e673d22656e223e711058070000003c2f68746d6c3e71114e656565656558070000003c2f6469763e0a711258070000003c2f6469763e0a711358350000003c64697620636c6173733d2273656374696f6e222069643d2272756e6e696e672d6c656f2d696e2d62617463682d6d6f6465223e0a7114586c0000003c68313e3c6120636c6173733d22746f632d6261636b7265662220687265663d22236964313922206e616d653d2272756e6e696e672d6c656f2d696e2d62617463682d6d6f6465223e52756e6e696e67204c656f20696e206261746368206d6f64653c2f613e3c2f68313e0a7115652e">On startup, Leo looks for two arguments of the form::

    --script scriptFile

If found, Leo enters batch mode. In batch mode Leo does not show any windows.
Leo assumes the scriptFile contains a Python script and executes the contents of
that file using Leo's Execute Script command. By default, Leo sends all
output to the console window. Scripts in the scriptFile may disable or enable
this output by calling app.log.disable or app.log.enable

Scripts in the scriptFile may execute any of Leo's commands except the Edit Body
and Edit Headline commands. Those commands require interaction with the user.
For example, the following batch script reads a Leo file and prints all the
headlines in that file::

    path = r"&lt;path-to-folder-containing-the-leo-folder&gt;\\leo\\test\\test.leo"

    g.app.log.disable() # disable reading messages while opening the file
    flag,newFrame = g.openWithFileName(path,None)
    g.app.log.enable() # re-enable the log.

    for p in newFrame.c.all_positions():
        g.es(g.toEncodedString(p.h,"utf-8"))
</t>
<t tx="ekr.20131008041326.16154">Leo sends more detailed error messages to stderr,
the output stream that goes to the console window. In Linux and MacOS
environments, python programs normally execute with the console window visible.
On Windows, can run Leo with the console window visible by associating .leo
files with python.exe *not* pythonw.exe. 

.. For full instructions about how
.. to do this, see `Associating Leo with .leo Files`_.
</t>
<t tx="ekr.20131008041326.16155">Python's HOME environment variable specifies Leo's HOME directory.
See http://docs.python.org/lib/os-procinfo.html for details.

Leo uses os.expanduser('~') to determine the HOME directory if no HOME environment variable exists.

Leo puts several files in your HOME/.leo directory:
.leoID.txt, .leoRecentFiles.txt, and myLeoSettings.leo.
</t>
<t tx="ekr.20131008041326.16156">Leo supports the following command-line options. As usual, you can see the
list by typing the following in a console window::

    leo -h

or::

    leo --help

You will get something like the following::

    Usage: launchLeo.py [options]
    
    Options:
      -h, --help            show this help message and exit
      --fullscreen          start fullscreen (Qt only)
      --ipython             enable ipython support
      --gui=GUI             gui to use (qt/qttabs)
      --maximized           start maximized (Qt only)
      --minimized           start minimized
      --no-cache            disable reading of cached files
      --no-plugins          disable all plugins
      --no-splash           disable the splash screen
      --screen-shot=SCREENSHOT_FN
                            take a screen shot and then exit
      --script=SCRIPT       execute a script and then exit
      --script-window=SCRIPT_WINDOW
                            open a window for scripts
      --select=SELECT       headline or gnx of node to select
      --session-restore     restore previously saved session tabs at startup
      --session-save        save session tabs on exit
      --silent              disable all log messages
      -v, --version         print version number and exit
      --window-size=WINDOW_SIZE
                            initial window size in height x width format
</t>
<t tx="ekr.20131008041326.16177">This section discusses the most important milestones in history of Leo.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20131008041326.16178"></t>
<t tx="ekr.20131008041326.16203">##################
The Basics of Leo
##################

This chapter introduces Leo's basic operations for creating and
changing outlines. Commands can be executed using keystrokes, or by
name.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20131008041326.16204">.. |br| raw:: html

   &lt;br /&gt;

.. _Leo:                    http://leoeditor.com/
.. _`ask for help`:         https://groups.google.com/forum/#!forum/leo-editor
.. _`programming tutorial`: tutorial-programming.html
.. _`Using @auto nodes`:    tutorial-programming.html#using-auto-nodes
</t>
<t tx="ekr.20131008041326.16222">###################
Using Leo as a PIM
###################

This chapter tells how you can use Leo as a Personal Information Manager.

It introduces `clones`_: one of Leo's most unusual and powerful features
for organizing data.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20131008041326.16241">########################################
Creating Documents with the rst3 Command
########################################

.. _`LaTeX`: http://www.latex-project.org/

This part of the tutorial tell how to Leo's rst3 command to create HTML,
PDF, `LaTeX`_ and other kinds of documents.

Leo's web site and all of Leo's documentation were generated by the rst3
command.

.. contents::
    :depth: 3
</t>
<t tx="ekr.20131008041326.16245">####################
Programming with Leo
####################

.. _`ask for help`: https://groups.google.com/forum/#!forum/leo-editor

Now we come to the programming features that distinguish Leo from all other
programming environments.

Please study this section carefully if you intend to use Leo for programming.

If you get stuck, please `ask for help`_ immediately.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20131008041326.16246">- Leo creates external files by replacing @others and section references
  with their expansions. 

- @first places lines before the first sentinel lines of a file.

- @path specifies a common prefix for the file names of @file and @auto nodes.

- @edit reads an entire external file into a single outline node.

- @auto imports an external file into an outline, creating nodes for
  functions, methods and classes.
  
- Use @edit or @auto to avoid adding Leo sentinels to external files.

- leo/core/LeoPyRef.leo contains all of Leo's core source code.</t>
<t tx="ekr.20131008041326.16248">.. |br| raw:: html

   &lt;br /&gt;

</t>
<t tx="ekr.20131008041326.16250">.. |br| raw:: html

   &lt;br /&gt;

.. _`Leo's Users Guide`:    leo_toc.html
.. _`Sphinx`:               http://sphinx.pocoo.org/
.. _`The rst3 chapter`:     tutorial-rst3.html
.. _`ask for help`:         https://groups.google.com/forum/#!forum/leo-editor
.. _`docutils`:             http://docutils.sourceforge.net
.. _`reStructuredText`:     http://docutils.sourceforge.net/rst.html
.. _`the rst3 chapter`:     tutorial-rst3.html
</t>
<t tx="ekr.20131008041326.16252">.. |br| raw:: html

   &lt;br /&gt;

.. _`event handlers`:
.. _`Leo's scripting chapter`:</t>
<t tx="ekr.20131008041326.16253">.. _`PyQt`: http://www.riverbankcomputing.com/software/pyqt/intro

Leo 4.9 featured the completed transition to the `PyQt`_ application
framework, the introduction of the viewrendered pane, and
autocompletion.
</t>
<t tx="ekr.20131008041326.16341">##########
Appendices
##########
   
.. contents::
    :depth: 3
</t>
<t tx="ekr.20131009050634.17610"></t>
<t tx="ekr.20131009050634.17616"></t>
<t tx="ekr.20131009050634.17622"></t>
<t tx="ekr.20131009050634.17623"># Used only if generate_rst is True.</t>
<t tx="ekr.20131009050634.17625"># True: generate rst markup from @code and @doc parts.</t>
<t tx="ekr.20131009050634.17627"># True: generate rst markup. False: generate plain text.</t>
<t tx="ekr.20131009050634.17630"># Can be set by @rst-no-head headlines.</t>
<t tx="ekr.20131009050634.17631"></t>
<t tx="ekr.20131009050634.17658"></t>
<t tx="ekr.20131009052848.6456"></t>
<t tx="ekr.20131009065148.31758">####################
Directives Reference
####################

.. contents::
    :depth: 2
</t>
<t tx="ekr.20131009065148.31760">#########################
Exploring Leo's Code Base
#########################

.. |br| raw:: html

   &lt;br /&gt;
   
This chapter is for anyone who wants to understand Leo's code base,
including those who want to be one of Leo's implementors.

You already know that leoFind.py and leoUndo.py implement Leo's find and
undo command, and so on.

This chapter focuses on the *process* of finding your way around Leo's
code, not the myriad details you will find within Leo's code.

It's actually very easy! Try it. You'll see.

Reading this chapter should take about 20 minutes.

.. contents::
    :depth: 3
</t>
<t tx="ekr.20131009100732.16737">Leo highlights URLs whenever syntax is coloring is enabled.

Ctrl-Left-Click (open-url-under-cursor) opens the URL under the cursor.

The open-url command opens a URL appearing either in the 
headline or the first line of body text.

If a headline starts with @url, the rest of the headline is take to be a url.

Leo opens URLs that look like file names using os.startfile. |br|
Leo opens all other URLs with your default web browser. |br|
Any scheme (http, mailto, ftp, file, etc.) supported by your browser is valid.

.. _`See the Appendix`: appendices.html#valid-url-s

URL's should contain no spaces: use %20 instead of spaces. |br|
`See the Appendix`_ for a complete description of valid URLs.
</t>
<t tx="ekr.20131009100732.16748">Create an \@rst node. This node and its descendants will contain your
document.

The headline of the \@rst node has the form::

        @rst &lt;filename&gt;

By default, the rst3 command will write two files: the **output file**
(&lt;filename&gt;) and the intermediate file (&lt;filename&gt;.txt).

For example, the rst3 command applied to @rst abc.html will write abc.html
and abc.html.txt.

When the rst3 command writes an @rst tree:

1. Each node becomes an rST/Sphinx section.

   The level of each section corresponds to the level of the node in the
   headline. Children of the @rst node create level 1 sections.
   Grandchildren of the \@rst node create level 2 sections, and so on.

2. The headline of each node becomes the section heading.

3. The body text of each node becomes the contents of the node's section.

</t>
<t tx="ekr.20131009100732.16750">Put something like this in the body of the @rst node::

    #############
    War and Peace
    #############

**Note**: You must use '#' as shown to mark the title. Don't use any other
underlining character.

Put introductory words in the body of the @rst node itself::

    Well, Prince, so Genoa and Lucca are now just family estates of the
    Buonapartes. But I warn you, if you don't tell me that this means war,
    if you still try to defend the infamies and horrors perpetrated by that
    Antichrist--I really believe he is Antichrist--I will have nothing more
    to do with you and you are no longer my friend, no longer my 'faithful
    slave,' as you call yourself! But how do you do? I see I have
    frightened you--sit down and tell me all the news.
</t>
<t tx="ekr.20131009100732.16751">Now you write your novel, short story, documentation or whatever. As
always, you organize your work with outlines.

Use @rst-no-head nodes to add text without creating a new rST section.

Use @rst-ignore nodes to comment out text.
</t>
<t tx="ekr.20131009100732.16752">&lt;Alt-X&gt;rst3&lt;Return&gt; runs the rst3 command.

If the present node is an @rst node, or a descendant node of an @rst node,
the rst3 command applies to the nearest ancestor @rst node. Otherwise, the
rst3 command applies to all descendant @rst trees.

When using docutils, the rst3 command will call docutils automatically to
create the output files.

When using sphinx, run sphinx's "make" utility after running the rst3
command to create the final output files.
</t>
<t tx="ekr.20131009100732.16753">You now know enough to get started with the rst3 command. Some possible
next steps are:

1. Look at Leo's own documentation in LeoDocs.leo. Discover how the nodes
   in this tree correspond to the documentation you see before you.

2. Create your own @rst nodes. Run the rst3 command on them and see what
   happens. If you get stuck, please `ask for help`_.</t>
<t tx="ekr.20131009100732.16754">To use docutils as your markup engine, use this settings::

    @bool rst3_call_docutils = True
    
otherwise, use::

    @bool rst3_call_docutils = False

In both cases, use this setting::

    @bool rst3_write_intermediate_file = True
</t>
<t tx="ekr.20131009100732.16755">Headlines that start with '@rst-' control the rst3 command. The three most
useful are:

.. glossary::

\@rst-no-head &lt;ignored-text&gt;

    Causes the rst3 command to copy just the body text of the node. In
    other words, the node's body text become part of the previous section.
    Leo's docs use such nodes for rST links and other "invisible" markup.

\@rst-ignore &lt;ignored-text&gt;

    The rst3 command ignores any \@rst-ignore node. Neither the headline
    nor the body text becomes part of the output. You can use such nodes
    for notes that you do not want to become part of the actual document.

\@rst-ignore-tree &lt;ignored-text&gt;

    The rst3 command ignores the \@rst-ignore-tree node and all its
    descendants.
</t>
<t tx="ekr.20131009100732.16760">Leo optionally expands abbreviations as you type.

Abbreviations typically end with something like ";;" so they won't trigger
by accident.

You define abbreviations in @data abbreviations nodes or @data
global-abbreviations nodes. |br| None come predefined, but leoSettings.leo
contains example abbreviations in the node::

    @@data abbreviations examples

Abbreviations can simply be shortcuts::

    ncn;;=@nocolor
    
Abbreviations can span multiple lines. Continued lines start with \\:, like
this::

    form;;=&lt;form action="main_submit" method="get" accept-charset="utf-8"&gt;
    \:&lt;p&gt;&lt;input type="submit" value="Continue &amp;rarr;"&gt;&lt;/p&gt;
    \:&lt;/form&gt;\n

Abbreviations can define templates in which &lt;\|a-field-name\|&gt; denotes a field
to be filled in::

    input;;=&lt;input type="text/submit/hidden/button"
    \:name="&lt;|name|&gt;"
    \:value="" id="&lt;|id|&gt;"&gt;\n

Typing ",," after inserting a template selects the next field.

Abbreviations can execute **abbreviation scripts**, delimited by {\|{ and
}\|}::

    date;;={|{import time ; x=time.asctime()}|}
    ts;;={|{import time ; x=time.strftime("%Y%m%d%H%M%S")}|}
    
For example, typing ts;; gives::

    20131009171117
    
It's even possible to define a context in which abbreviation scripts execute.

See the leoSettings.leo for full details, including applicable settings.
</t>
<t tx="ekr.20131009100732.19038">.. _`Plugins`:          plugins.html
.. _`bookmarks.py`:     plugins.html#bookmarks-py
.. _`contextmenu.py`:   plugins.html#contextmenu-py
.. _`mod_scripting.py`: plugins.html#mod-scripting-py
.. _`quicksearch.py`:   plugins.html#quicksearch-py
.. _`todo.py`:          plugins.html#todo-py
.. _`valuespace.py`:    plugins.html#valuespace-py
.. _`viewrendered.py`:  plugins.html#viewrendered-py

`Plugins`_ are Python programs that extend what Leo can do.

Plugins reside in the leo/plugins folder.

Enable plugins by adding their file names in @enabled-plugins nodes an @settings tree. |br|
The @enabled-plugins bundled in leoSettings.leo contains a list of default (recommended) plugins.

Programmers have contributed dozens of plugins, including:

- `bookmarks.py`_: manages and shows bookmarks.

- `contextmenu.py`_: shows a context menu when you right-click a headline.

- `mod_scripting.py`_: supports @button and @command nodes.

- `quicksearch.py`_: Adds Nav tab for searching.

- `todo.py`_: provides to-do list and simple project-management capabilities.

- `valuespace.py`_: adds outline-oriented spreadsheet capabilities.

- `viewrendered.py`_: creates the rendering pane and renders content in it.
</t>
<t tx="ekr.20131009100732.19039">Open bookmarks in a list, and show bookmarks in a pane.
</t>
<t tx="ekr.20131009100732.19040">Supports outline-based calculations similar to spreadsheets.
</t>
<t tx="ekr.20131010160850.17454"></t>
<t tx="ekr.20131011050613.16815">The LoadManager (LM) class (in leoApp.py) is responsible for initing all
objects and settings. This is a complex process. Here is the big picture:

- The LM reads each local (non-settings) file twice.
  The first load discovers the settings to be used in the second load.
  This ensures that proper settings are *available* during the second load.

- Ctors init settings "early", before calling the ctors for subsidiary objects.
  This ensures that proper settings are *in effect* for subsidiary ctors.
</t>
<t tx="ekr.20131011050613.16860">In Leo, each class hides (encapsulates) the details of its internal
workings from user (client) classes. This design principle has been
spectacularly successful. Leo's overall design has remained remarkably
stable for 20 years, even as the internal details of many classes have
radically changed.

The distinction between gui-dependent and gui-independent is important.
Almost all gui-dependent code resides in the plugins folder. Leo's core
code is almost completely gui independent.

Leo's core typically assumes that w (an abstract widget) is a subclass of
the baseTextWidget class. This class implements the DummyHighLevelInterface
interface. Actually, w is usually a LeoQTextBrowser or leoQtBaseTextWidget
object, defined in qtGui.py. These classes provide thin wrappers for
corresponding Qt widgets.

Wrapper classes are useful, regardless of gui independence:

- Wrapper classes often simplify the corresponding code in Leo's code.
- Wrapper classes provide convenient methods for debugging and tracing.
</t>
<t tx="ekr.20131011050613.16862">Once you know approximately where to look, it is easy to use traces to
discover what is going on. To trace the last n (default 4) callers of any
function::

    g.trace(g.callers(n))
    
Many complex methods define a trace variable::

    trace = False and not g.unitTesting
    
A good rule of thumb: the more complex a method is, the more useful its
traces are likely to be.

You can also to use g.pdb() to single-step through the code.
I typically use g.pdb() only for deep mysteries!

**Note**: you must run Leo from a console window to use either g.trace or
g.pdb. I recommend always running Leo from a console.</t>
<t tx="ekr.20131011050613.16866">Several modules contain long comments::

    &lt;&lt; about new sentinels &gt;&gt; (leoAtFile.py)
    &lt;&lt; about the leoBridge module &gt;&gt; (leoBridge.py)
    &lt;&lt; how to write a new importer &gt;&gt; (leoImport.py)
    &lt;&lt; How Leo implements unlimited undo &gt;&gt; (leoUndo.py)
    &lt;&lt; about gui classes and gui plugins &gt;&gt;
    &lt;&lt; About handling events &gt;&gt; (leoFrame.py)
    &lt;&lt; Theory of operation of find/change &gt;&gt; (leoFind.py)
    &lt;&lt; Key bindings, an overview &gt;&gt; (leoKeys.py)
    &lt;&lt; about 'internal' bindings &gt;&gt; (leoKeys.py)
    &lt;&lt; about key dicts &gt;&gt; (leoKeys.py)
    
These comments may be helpful, but do *not* assume that they are accurate.

When in doubt, trust the code, not the comments.
</t>
<t tx="ekr.20131011050613.16868">You can learn *anything* about Leo, provided that you can cause Leo to
execute the relevant code. That's usually very easy!

- It should be straightforward to isolate the module or modules involved.
- The next several sections give hints about finding interesting code.
- Once you find a bit of interesting code, use g.pdb or g.trace to study it.

The following sections provide more details...
</t>
<t tx="ekr.20131011050613.16870">The following methods and their helpers all have useful traces:

- leoQtEventFilter.eventFilter (qtGui.py) and helpers create keystrokes 
  (LeoKeyEvents) from QKeyEvent events.

- k.masterKeyHandler (leoKeys.py) receives LeoKeyEvents from eventFilter
  and invokes one of Leo's commands based on the users bindings.

- k.getArg handles commands like Ctrl-F (search-with-present-options)
  that prompt the user for input.
</t>
<t tx="ekr.20131011050613.16871">c.outerUpdate and helpers eliminate flicker by redrawing the screen only at
the end of each command.

c.outerUpdate contains several sophisticated and useful traces.

qtGui.set_focus (qtGui.py) is the only place that actually explicitly sets
focus in Leo. Enabling a trace there can be useful.
</t>
<t tx="ekr.20131011050613.16876">The following methods are surprisingly fragile. Change them only after
careful thought. Make *sure* to run all unit tests after changing them in
any way:

- leoTree.select and c.selectPosition switch nodes.

- c.endEditing ends editing in a headline and updates undo data.

- leoBody.onBodyChanged updates undo data when body text changes.

- baseNativeTree.onHeadChanged (baseNativeTree.py) updates undo data.

  **Note**: This method overrides leoTree.onHeadChanged (leoFrame.py),
  which is not used.

In addition, *all* event handling in baseNativeTree.py is extremely
fragile. Don't even think about changing this code unless you know exactly
what you are doing.
</t>
<t tx="ekr.20131012060912.16768">Leo creates commands in two ways:

1. Using the @g.command(command-name) decorator.

2. Using tables, usually getPublicCommands methods in various classes.

For example, to find the code for the sort-lines command, search for
sort-lines. You will find::

    'sort-lines':    self.sortLines,
    
Now search for "def sortLines" and you have arrived.</t>
<t tx="ekr.20131012060912.16769">The following sections discuss topics that may not be apparent from reading
the sources.
</t>
<t tx="ekr.20131012060912.16770">Leo's key handling is complex because it does inherently complex things:

- Code in various places translate user key bindings to dictionaries.

- eventFilter and its helpers translates incoming QKeyEvents to LeoKeyEvents.

- k.masterKeyHandler associates incoming LeoKeyEvents with
  mode-and-pane-dependent bindings.
  
Much of this complexity is a direct result in the flexibility given to
users in specifying key bindings.
</t>
<t tx="ekr.20131012060912.16775">Leo generators are `Python generators`_. Leo generators traverse (step
through) Leo outlines node by node:
**Leo generators yield a sequence of positions.**

The Commands (commander) and position classes define several generators,
discussed later in this chapter. c.all_positions() traverses
the outline in outline order.  The following prints a properly-indented
list of all headlines::

    for p in c.all_positions():
        print(' '*p.level()+p.h)
        
Leo generators **yield** (return a sequence of) positions. They do *not*
return actual lists; this saves lots of space for large outlines.
In fact, this "sequence of positions" is actually a sequence of a
**single, constantly changing** position.
This is a very important space optimization.
  
When a generator is finished, this single position becomes an **empty
position**. p.v is None for empty positions. There are the right and wrong
ways to test for empty positions::

    if not p:       # Right
    if not p.v:     # Right
    if p is None:   # Wrong!
    
The `scripting portion`_ of `Leo's cheat sheet`_ lists all of Leo's
generators.
  </t>
<t tx="ekr.20131012060912.16788">g.es can send it's output to tabs other than the log tab::

    c.frame.log.selectTab('Test')
        # Create Test or make it visible.

    g.es('Test',color='blue',tabName='Test')
        # Write to the test tab.

Plugins and scripts may call the c.frame.canvas.createCanvas method to create a
log tab containing a graphics widget. Here is an example script::

    log = c.frame.log ; tag = 'my-canvas'
    w = log.canvasDict.get(tag)
    if not w:
        w = log.createCanvas(tag)
        w.configure(bg='yellow')
    log.selectTab(tag)
</t>
<t tx="ekr.20131012191145.16789">For any commander c:

+------------------------------+--------------------------------------------+
| **Property**                 | **Value**                                  |
+------------------------------+--------------------------------------------+
| c.p                          | the presently selected position            |
+------------------------------+--------------------------------------------+
| **Ivar**                     | **Value**                                  |
+------------------------------+--------------------------------------------+
| c.frame                      | the leoFrame representing the main window. |
+------------------------------+--------------------------------------------+
| c.frame.body                 | the leoBody representing the body pane.    |
+------------------------------+--------------------------------------------+
| c.frame.body.bodyCtrl        | a leoQTextEditWidget.                      |
+------------------------------+--------------------------------------------+
| c.frame.body.bodyCtrl.widget | a LeoQTextBrowser (a QTextBrowser)         |
+------------------------------+--------------------------------------------+
| c.frame.tree                 | a leoQtTree, representing the tree pane    |
+------------------------------+--------------------------------------------+
| c.frame.tree.treeWidget      | a LeoQTreeWidget (a QTreeWidget)           |
+------------------------------+--------------------------------------------+
| c.user_dict                  | a Python dictionary for use by scripts and |
|                              | plugins. Does not persist when Leo exists. |
+------------------------------+--------------------------------------------+</t>
<t tx="ekr.20131013060803.16851">@language python

# Should be run from an empty .leo file.
# Such traces might be part of the tutorial, but aren't at present.

g.cls()

def print_p(p):
    c,result = p.v.context,[]
    v,n = p.v,p.childIndex()
    for data in p.stack:
        v,n = data
        result.append('(%s %s)' % (n,v.h))
    return ','.join(result)

for p in c.all_positions():
    print('(%s %s) p.stack: %s' % (p.childIndex(),p.h,print_p(p)))
</t>
<t tx="ekr.20131013060803.16852">Here is the obligatory "Hello World!" script::

    g.es('Hello World!')
    
Ctrl-B (execute-script) executes the body text of the selected node as a Python script. |br|
If text is selected, execute-script executes only the selected text.

g.es prints its arguments to Leo's log pane.

..  You can use Ctrl-B even if you are reading this in leoDocs.leo!

g seems to be undefined, yet this script *does* work without error, because...
</t>
<t tx="ekr.20131014050027.16801">A **position** represents a specific outline node at an exact location
in the outline. Positions are instances of the position class, defined
in leoNodes.py. Methods of the position class provide safe ways to
insert, delete and move outline nodes. The `scripting portion`_ of
`Leo's cheat sheet`_ lists the most important methods of the position
class.

- The vnode at position p is p.v.

- Because all clones share the same vnode, |br|
  many positions may have the same p.v field.

- p.b, p.h and p.u are synonyms for p.v.b, p.v.h and p.v.u.

- For any commander c, c.p is the presently selected node.

**positions usually become invalid when outline structure changes**.
Scripts should store positions for later use only if the script does not
cause the outline to change in any way.

- c.positionExists(p) returns True if p is (still) valid in c's outline.

The next section describes generators. Generators are a great way of
gaining access to outline nodes.
</t>
<t tx="ekr.20131014053720.16809">As mentioned previously,
**positions become invalid whenever nodes are inserted, deleted or moved**.

It is valid to capture positions *temporarily*, *provided* that the outline
does not changed while the captured positions are being used. Here is the
proper way::

    aList = [p.copy() for p in c.all_positions()]
        # aList is valid until the outline changes.
        
The p.copy() method returns a *separate* position that does not change when
p changes. Beginners erroneously try to capture positions like this::

    aList = [p for p in c.all_positions()] # Wrong!
    
This is wrong. Leo's generators use a single position, and yield that
*same* position for every node in the outline. Furthermore, that position
will be empty when the generator ends, so every member of aList will be the
(same) empty position!



</t>
<t tx="ekr.20131014053720.16810">This section discusses vnodes; the next discusses positions. To script Leo
properly, you *must* understand how vnodes and positions are related.

**vnodes** are instances of the vnode class, defined in leoNodes.py. Each
vnode represents *all* the data associated with an outline node, including
*private* data carrying its outline structure. For each vnode v:

- v.b is the (outline) node's body text.

- v.h is the node's headline.

- v.u is the nodes **user data**, discussed later in this chapter.

..  - v.children is a list of all child vnodes of v.
..  - v.parents is a list of all parent vnodes of v. |br|
..    (v is a clone if and only if len(v.parents) &gt; 1
..  - Scripts **absolutely must not change** v.parents and v.children!

**All cloned outline nodes share a common vnode**. Conversely, |br| each
vnode represents *all* the clones of the corresponding outline node.

Because a *single* vnode can represent *many* outline nodes, it is awkward
to use vnodes directly. This is where positions come in: **positions
simplify access to vnodes**...</t>
<t tx="ekr.20131014053720.16816">The .leo files in Leo's distribution contain many @button nodes (many
disabled), that do repetitive chores. Here is one, @button
promote-child-bodies, from LeoDocs.leo::

    '''Copy the body text of all children to the parent's body text.'''

    # Great for creating what's new nodes.
    result = [p.b]
    b = c.undoer.beforeChangeNodeContents(p)
    for child in p.children():
        if child.b:
            result.append('\n- %s\n\n%s\n' % (child.h,child.b))
        else:
            result.append('\n- %s\n\n' % (child.h))
    p.b = ''.join(result)
    c.undoer.afterChangeNodeContents(p,'promote-child-bodies',b)

This creates a fully undoable promote-child-bodies command.</t>
<t tx="ekr.20131015035606.16778">When focus is in the outline pane::

    Right-arrow (expand-and-go-right)
    Left-arrow (contract-or-go-left)
    Up-arrow (goto-prev-visible) 
    Down-arrow (goto-next-visible)
    
Regardless of focus::

    Alt-Home (goto-first-visible-node) 
    Alt-End (goto-last-visible-node)
    Alt-Right-arrow (expand-and-go-right)
    Alt-Left-arrow (contract-or-go-left)
    Alt-Up-arrow (goto-prev-visible) 
    Alt-Down-arrow (goto-next-visible)
</t>
<t tx="ekr.20131015035606.16780">When focus is in any of Leo's text panes (body pane, log pane, headlines):

    +-------------------+-----------------------+
    | **Key**           | **Move Cursor**       |
    +-------------------+-----------------------+
    | Arrow keys        | one character         |
    +-------------------+-----------------------+
    | Ctrl-LeftArrow    | back one word         |
    +-------------------+-----------------------+
    | Ctrl-RightArrow   | forward one word      |
    +-------------------+-----------------------+
    | Home              | beginning of line     |
    +-------------------+-----------------------+
    | End               | end of line           |
    +-------------------+-----------------------+
    | Ctrl-Home         | beginning of the body |
    +-------------------+-----------------------+
    | Ctrl-End          | end of body           |
    +-------------------+-----------------------+
    | PageDown          | down one page         |
    +-------------------+-----------------------+
    | PageUp            | up one page           |
    +-------------------+-----------------------+
    
Adding the Shift key modifier to any of the keys above
moves the cursor and extends the selected text.
</t>
<t tx="ekr.20131015035606.16786">Directives starting with '@ in the leftmost column
    
See the `Directives reference`_ for full details::

    @                       # starts doc part
    @c                      # ends doc part
    @color
    @doc                    # starts doc part
    @killcolor
    @nocolor
    @language python
    @language c
    @language rest          # restructured text
    @language plain         # plain text: no syntax coloring.
    @lineending lineending
    @pagewidth 100
    @raw, @end_raw          # @file only.
    @tabwidth -4            # use spaces
    @tabwidth 8             # use tabs
    @nowrap
    @wrap
    
Leading whitespace is allowed (and significant) for::

    @all
    @others
    </t>
<t tx="ekr.20131015035606.16788">For documentation see node: "About this file" in leoSettings.leo.

- Key bindings:     @shortcuts
- Visual settings:  @data qt-gui-plugin-style-sheet
- Enabling plugins: @enabled-plugins

To disable a binding for a key, bind it to do-nothing::

    do-nothing = Insert
    
This overrides the following default binding in leoSettings.leo::

    insert-node = Insert
</t>
<t tx="ekr.20131015035606.16799">\@&lt;file&gt; nodes create external files::

    @asis &lt;filename&gt;    
    @auto &lt;filename&gt;    
    @edit &lt;filename&gt;
    @file &lt;filename&gt;
    @nosent &lt;filename&gt;  
    @shadow &lt;filename&gt;
    
See the `Directives reference`_ for full details.
    
**Section names** have the form::

    &lt;&lt; any text, except double closing angle brackets &gt;&gt;
    
**Section-definition nodes** have headlines starting with a section name.

Leo performs **expansions** for all @&lt;file&gt; nodes except @asis.

Expansion of @all:

- Leo replaces @all by the *unexpanded* body text of *all* nodes.

Expansion of section names and @others:

- Leo replaces section names in body text by the *expanded*
  text of the corresponding section definition node.
  
- Leo replaces @others with the *expanded* text of all nodes
  that *aren't* section-definition nodes.
</t>
<t tx="ekr.20131015035606.16800">When focus is in the outline::

    Shift-Down-arrow (move-outline-down) 
    Shift-Left-arrow (move-outline-left) 
    Shift-Right-arrow (move-outline-right) 
    Shift-Up-arrow (move-outline-up)

Regardless of focus::

    Alt-Shift-Down-arrow (move-outline-down) 
    Alt-Shift-Left-arrow (move-outline-left) 
    Alt-Shift-Right-arrow (move-outline-right) 
    Alt-Shift-Up-arrow (move-outline-up)
    Ctrl-D (move-outline-down)
    Ctrl-L (move-outline-left) 
    Ctrl-R (move-outline-right)
    Ctrl-U (move-outline-up)
</t>
<t tx="ekr.20131015035606.16801">For much more information, see the `Commands Reference`_.

Files::

    Ctrl-N (new) 
    Ctrl-O (open-outline)
    Ctrl-S (save-file) 
    Ctrl-Q (exit-leo)

Focus::

    Alt-T (focus-to-tree) 
    Ctrl-T (toggle-active-pane)
    Ctrl-Tab (tab-cycle-next)
    
Help::

    Alt-0 (vr-toggle)
    F1 (help) 
    F11 (help-for-command) 
    F12 (help-for-python)
    print-bindings
    print-settings
    help-for-...

Find/Replace::

    Ctrl-F (search-with-present-options) 
    Shift-Ctrl-R (replace-string)
    Ctrl-minus (replace-then-find) 
    F3 (find-next) 
    F2 (find-previous)
    
Minibuffer::

    Alt-X (full-command)
    Ctrl-G (keyboard-quit)

Nodes::

    Ctrl-I or Insert (insert-node)
    Ctrl-H (edit-headline)
    &lt;Return&gt; (when editing a headline) (end-edit-headline)
    Ctrl-Shift-C (copy-node)
    Ctrl-Shift-X (cut-node) 
    Ctrl-Shift-V (paste-node) 
    Ctrl-{ (promote)
    Ctrl-} (demote)
    Ctrl-M (mark) 

Undo::

    Ctrl-Z (undo)
    Ctrl-Shift-Z (redo)
</t>
<t tx="ekr.20131015091948.16784">#############################
A Miscellany of Leo Scripting
#############################

This chapter covers miscellaneous topics related to Leo scripts.

You might call this a FAQ for scripts...

.. contents::
    :depth: 3
</t>
<t tx="ekr.20131015104133.16763"></t>
<t tx="ekr.20131015104133.16766">#####################################
Downloading, Installing &amp; Running Leo
#####################################

.. This page exists simply to organize the main TOC.

.. toctree::
   :maxdepth: 2

   download
   installing
   running
</t>
<t tx="ekr.20131016021541.16893">- execute-script predefines c, g and p.
- c is a commander, g is the leoGlobals module, and p is the current position.
- Vnodes contain all outline data.
- Positions provide easy access to vnodes.
- Positions become invalid when outline nodes are inserted, deleted or moved.
- Generators visit all or parts of the outline, in a specified order.
- Generators yield a *single* position whose value constantly changes.
- p.copy() yields a new position that does not change when p changes.
- Alt-1 enables autocompletion.
- Leo's autocompleter understands symbols such as c, g, g.app, etc.
- @button nodes create scripts that can be applied to any outline node.
- @test nodes create unit tests (subclasses of unittest.TestCase) from body text.</t>
<t tx="ekr.20131016021541.16894">Use @edit instead of @file to place the entire contents of an external file
into a single outline node. Leo writes no sentinel when writing @edit
files.</t>
<t tx="ekr.20131016083406.16724">@language python
import os
trace = True
g.cls()
c.setComplexCommand('make-sphinx')
c.save()
aList = c.rstCommands.rst3()
if aList:
    path = g.os_path_finalize_join(g.app.loadDir,'..','doc','html')
    os.chdir(path)
    if len(aList) &gt; 1: g.execute_shell_commands('make clean',trace=trace)
    g.execute_shell_commands('make html',trace=trace)
    fn = aList[0].h.strip() if len(aList) == 1 else 'leo_toc.html'
    fn = g.os_path_finalize_join(path,'_build','html',g.os_path_basename(fn))
    if g.os_path_exists(fn):
        # Don't wait for this command to exit!
        g.execute_shell_commands(['&amp;%s' % (fn)],trace=trace)
</t>
<t tx="ekr.20131016084446.16726">The `scripting portion`_ of `Leo's cheat sheet`_ contains much more
information about scripting, including lists of Leo's generators and useful
methods of the commander and position classes. 

`Leo's Directive Reference`_ discusses all directives in great detail.
It would be a good idea to skim this chapter to see what it contains.</t>
<t tx="ekr.20131016103844.16730">See the docstring of these plugins for more details:

- bookmarks.py: Manages URL's used as bookmarks.
- contextmenu.py: Brings up context menu when user right-clicks a headline.
- mod_scripting.py: Supports @button and @command nodes.
- quicksearch.py: Adds Nav tab for searching.
- todo.py: Manages to-do lists and simple project management.
- valuepace.py: Creates an outline-oriented spreadsheet.
- viewrendered.py: Creates a rendering pane. Automatically loaded by Leo's help commands.
</t>
<t tx="ekr.20131017051340.16732">These are not included on the web, but may be of interest to those
reading LeoDocs.leo.</t>
<t tx="ekr.20131017051340.16733">This chapter uses the following outline (with all nodes expaneded) as an
ongoing example::

    + A (clone)
      + B
        - C
      - D
    - E
    + A (clone)
      + B
        - C
      - D
    - F
    
Only the A nodes are clones of each other.
    
c.all_positions, when applied to the example tree above, yields::

    A, B, C, D, E, A, B, C, D, F.
</t>
<t tx="ekr.20131017051340.16735">This script::

    def print_p_stack(p):
        c,result = p.v.context,[]
        v,n = p.v,p.childIndex()
        for data in p.stack:
            v,n = data
            result.append('(%s %s)' % (n,v.h))
        return ','.join(result)
    
    for p in c.all_positions():
        print('(%s %s) p.stack: %s' % (
            p.childIndex(),p.h,print_p_stack(p)))
            
yields the following when applied to the example
outline::
    
    (0 A) p.stack:
    (0 B) p.stack: (0 A)
    (0 C) p.stack: (0 A),(0 B)
    (1 D) p.stack: (0 A)
    (1 E) p.stack:
    (2 A) p.stack:
    (0 B) p.stack: (2 A)
    (0 C) p.stack: (2 A),(0 B)
    (1 D) p.stack: (2 A)
    (3 F) p.stack:

Top-level nodes::

    (0 A) p.stack:
    (1 E) p.stack:
    (2 A) p.stack:
    (3 F) p.stack:

B::

    (0 B) p.stack: (0 A)
    (0 B) p.stack: (2 A)

C::

    (0 C) p.stack: (0 A),(0 B)
    (0 C) p.stack: (2 A),(0 B)

All Leo generators use a single, ever-changing, position object::

    for p in c.all_positions():
        print('id(p): %s id(p.v): %s (%s %s) p.stack: %s' % (
            id(p),id(p.v),p.childIndex(),p.h,print_p_stack(p)))

The output is something like::

    id(p): 214733232 id(p.v): 192725360 (0 A) p.stack:
    id(p): 214733232 id(p.v): 192725488 (0 B) p.stack: (0 A)
    id(p): 214733232 id(p.v): 192725552 (0 C) p.stack: (0 A),(0 B)
    id(p): 214733232 id(p.v): 192725520 (1 D) p.stack: (0 A)
    id(p): 214733232 id(p.v): 192725392 (1 E) p.stack:
    id(p): 214733232 id(p.v): 192725360 (2 A) p.stack:
    id(p): 214733232 id(p.v): 192725488 (0 B) p.stack: (2 A)
    id(p): 214733232 id(p.v): 192725552 (0 C) p.stack: (2 A),(0 B)
    id(p): 214733232 id(p.v): 192725520 (1 D) p.stack: (2 A)
    id(p): 214733232 id(p.v): 192725584 (3 F) p.stack:
    
A::

    id(p): 214733232 id(p.v): 192725360 (0 A) p.stack:
    id(p): 214733232 id(p.v): 192725360 (2 A) p.stack:
    
B::

    id(p): 214733232 id(p.v): 192725552 (0 C) p.stack: (0 A),(0 B)
    id(p): 214733232 id(p.v): 192725552 (0 C) p.stack: (2 A),(0 B)

C::

    id(p): 214733232 id(p.v): 192725552 (0 C) p.stack: (0 A),(0 B)
    id(p): 214733232 id(p.v): 192725552 (0 C) p.stack: (2 A),(0 B)

D::

    id(p): 214733232 id(p.v): 192725520 (1 D) p.stack: (0 A)
    id(p): 214733232 id(p.v): 192725520 (1 D) p.stack: (2 A)
    
Each Leo outline contains a hidden vnode, c.hiddenRootNode::

    c.hiddenRootVnode.children: [A, E, A, F]
    A.children: [B]
    B.children: [C]
    C.children: []
    D.children: []
    E.children: []
    F.children: []
    
    c.hiddenRootVnode.parents: []
    A.parents: [c.hiddenRootVnode,c.hiddenRootVnode]
    B.parents: [A]
    C.parents: [B]
    D.parents: [A]
    E.parents: [c.hiddenRootVnode]
    F.parents: [c.hiddenRootVnode]
</t>
<t tx="ekr.20131017051340.16779">#######################
The leoInspect Module
#######################

The leoInspect module provides answers to questions about Python
source code such as:

- Where are all assignments to 'w' in leoEditCommands.py?

- Which of those assignments are "unusual" in some way?

The leoInspect module grew out of a re-imagining of the new-pylint
project, which has been a "hobby" project of mine for several years.
Rather than attempting global "proofs" of difficult propositions, as
new-pylint does, the leoInspect module answers specific questions
about modules, functions, classes, methods and statements. We can use
such answers while debugging, or as documentation, or especially as
the foundation for *fast* unit tests.

The leoInspect module provides answers to questions about Python
source code. leoInspect is an elegant and easy-to-use front end for
Python's AST (Abstract Syntax Tree) trees *and* a window into a richly
connected set of semantic data built *from* AST trees.

The simplicity of the leoInspect module could be called "third
generation" simplicity. Several implementation Ahas lie behind it.

.. contents::
    :depth: 2
</t>
<t tx="ekr.20131017051340.16780">Mathematica's expressions inspired the design of the query language:
simple and task oriented. All details in the background. leoInspect
makes *Python* the query language! Let's see how.

All queries start with a call to leoInspect.module::

    import leo.core.leoInspect as inspect
    o = inspect.module('leoApp.py')
    
The call to inspect.module creates a **query object** o representing
all the data contained in the AST for leoApp.py. But this query object
*also* represents a **context**, a module, class, function, method or
statement.

For any context o, we can use **getters** to get lists of other contexts::

    aList = o.calls()      # All function/method calls in context o.
    aList = o.classes()    # All classes in context o.
    aList = o.functions()  # All functions in context o.
    aList = o.statements() # All the statements in context o.
    
Assignments and calls are especially important for queries. The following
getters return the assignments related to some name s::

    aList = o.assignments_to(s)
    aList = o.assignments_using(s)
    aList = o.calls_to(s)
    aList = o.call_args_of(s)
    
The o.name getter returns the name of any module, class, method,
function or var::

    s = o.name()
    
The o.format getter returns a human-readable representation of a
context's AST tree::

    s = o.format()
    
These getters generally make it unnecessary to access AST trees
directly: ASTs are merely part of the "plumbing" of the leoInspect
module. However, the o.tree getter returns the actual AST tree if you
really need it::

    ast_tree = o.tree()

Let's see how to create actual queries. Here is a script to discover
all assignments to 'w' in leoEditCommands.py is::

    import leo.core.leoInspect as inspect
    m = inspect.module('leoEditCommands.py')
    for a in m.assignments_to('w'):
        print(a.format())
        
It is easy to "zero in" on particular classes or method using the
o.name getter. The following script prints all assignments to the
'files' ivar of the LoadManager class in leoApp.py::

    import leo.core.leoInspect as inspect
    m = inspect.module('leoApp.py')
    for theClass in m.classes():
        if theClass.name() == 'LoadManager':
            for a in m.assignments_to('files'):
                print(a.format())

We have seen that the getters hide all the messy details of Python AST
trees. This is a revolution in using AST trees!
</t>
<t tx="ekr.20131017051340.16781">Could one create a lint-like programming using leoInspect? Perhaps,
but much more work would be required. Indeed, pylint is an extremely
capable program. It can make complex deductions that are presently far
beyond leoInspect's capabilities.

However, leoInspect is an elegant front end. It might serve
as the basis of more complex analysis. Multi-pass algorithms are often
*faster* and more elegant than single-pass algorithms, so the "extra"
overhead of the leoInspect prepass is probably not significant. What
matters are the deductions that can be made using leoInspect.Context
data.

Speed is not an obstacle for a lint-like tool based on leoInspect.
Indeed, the module getter creates *all* the context data in a very
fast pass over the modules AST tree. It takes about 4.6 seconds to
create the context data for all 34 of Leo's source files. Because
getters are extremely fast, even complex queries will be fast. A
multiple-pass query will typically take about 0.1 sec per pass. Using
AstFormatter in the InspectTraverser class adds a negligible amount of
time, less than 10% of the total tree-traversal time.
</t>
<t tx="ekr.20131017051340.16782">The assignments_to, assignments_using and the new calls_to getters all
specify a **pattern** to be matched against the the lhs of assignments
(or against function names in the calls_to getter).  At present, the
pattern must match as a plain word match, but it would be more natural
to use regex matches.  That's coming.

Three new getters would give leoInspect the ability to replace
refactored code:

- o.token_range: Returns pointers the list of tokens comprising o.

- o.text: Returns o's source text (a string).

- o.text_range: Returns the starting and ending offsets of the text in the file.

These getters are non-trivial to do, but a reasonable design is in place.
</t>
<t tx="ekr.20131017051340.16783">.. _`this post`: http://groups.google.com/group/leo-editor/browse_thread/thread/62f0e7b84a25e0d0/39f848ad8a96bcbc

The module getter creates *all* the data used by the other getters.
This data is a richly-linked set of Context objects. Getters are very
fast because the getter of an object o merely returns one of o's
ivars.

The o.format getter is an exception. It traverses o's AST to create
the human-readable representation of o.

The AstFormatter class is a straightforward recursive descent algorithm.

The InspectTraverser.do_Attribute method uses the *formatting* code to
compute the value of the attribute. This replaces complex
AST-traversal code with a call to the formatter.

</t>
<t tx="ekr.20131017051340.16784">Getters all follow roughly the same pattern.  For example::

    def assignments_to (self,s,all=True):
        
        format,result = self.formatter.format,[]
    
        for assn in self.assignments(all=all):
            tree = assn.tree()
            kind = self.ast_kind(tree)
            if kind == 'Assign':
                for target in tree.targets:
                    lhs = format(target)
                    if s == lhs:
                        result.append(assn)
                        break
            else:
                assert kind == 'AugAssign',kind
                lhs = format(tree.target)
                if s == lhs:
                    result.append(assn)
    
        return result
        
This is AST-traversal code. Indeed, the tree getter returns an AST,
and ast_kind is an internal getter that returns the AST type for an
AST node.

This code is elegant. It uses the assignments getter to get the list
of all assignments in this context and all contained (descendant)
contexts. All public getters are members of the base Context class, so
this code code "just works" for *all* contexts. Furthermore,
assignments are StatementContext objects, so they "just work" as
elements returned by the getter. Comparing this code with the code
found in pylint shows how elegant this code truly is.

No simpler code is possible. AST trees for assignments are a bit
different from AST trees for augmented assignments. Once the type of
assignment is identified, the code simply *formats* the left hand side
(lhs) of the assignment, and compares s with the lhs. If there is a
match, the entire assignment is appended to the result.
</t>
<t tx="ekr.20131017051340.16785">This section describes the how the unfinished o.token_range getter will work.

There are two parts to the problem...
</t>
<t tx="ekr.20131017051340.16786">For each node N of a module's tree, we want to inject the following
two new ivars:

- N.end_lineno: the line number of the last character of the token.

- N.end_col_offset: the (byte) offset of the last character of the token.

**Important**: tree structure is irrelevant when computing these fields: we
simply want a **sorted** list of (N.lineno,No.col_offset, N) tuples!

The prepass will use ast.walk(root), to generate the list.  After
sorting the list, the prepass will inject inject N.end_lineno and
N.end_col_offset ivars into each node N by stepping through the list.
The ending values of the previous node on the list are the the same as
the beginning values of the next node on the list.

This prepass need only be done once per module.
</t>
<t tx="ekr.20131017051340.16787">To compute token_range for a *particular* N, we want to discover
values M.end_lineno and M.end_col_offset for M, the **last** token in
N's entire tree.

token_range will do the prepass on the modules tree if necessary.
token_range will then call ast.walk(N) to discover all of N's nodes,
sort the list, and return the last element of the list!

token_range will, by its design, include *all* text in the range,
including comments.
</t>
<t tx="ekr.20131017051340.16815">Calltips show the expected arguments to functions and methods:

- Alt-2 (toggle-calltpips) enables and disables calltips.
- '(' shows calltips, when @language python is in effect.
- &lt;Return&gt; or Ctrl-G (keyboard-quit) exits calltips.

Calltips work for any Python function or method, including Python's
global functions. Examples::

    g.toUnicode(            g.toUnicode(s, encoding, reportErrors=False
    c.widgetWantsFocusNow(  c.widgetWantsFocusNow(w
    reduce(                 reduce(function, sequence[, initial]) -&gt; value
</t>
<t tx="ekr.20131017051340.16816">@language rest

This section contains supplementary documentation.

It will not be of interest for most users of Leo.</t>
<t tx="ekr.20131017051340.16831">###############
IPython and Leo
###############

.. _`run Leo in a console window`: installing.html#running-leo-from-a-console-window

Leo's ipython plugin provides two-way communication (a bridge) between Leo and
IPython: you can run Leo scripts from IPython, and IPython scripts from Leo. To
use this plugin, you must `run Leo in a console window`_. When this plugin is
enabled, Leo's start-ipython command starts IPython_ in this console.

Remarkably, Leo and IPython run simultaneously in the same process,
yet their separate event loops do not interfere with each other.
Scripts run from IPython *immediately* change Leo,
*exactly* as if the script were run from Leo.
Conversely, scripts run from Leo *immediately* affect the IPython interpreter.
As a result, Leo might be considered an `IPython Notebook`_.

The bridge between Leo and IPython is powerful because it is simple. Indeed,

1. **You can run any IPython script from Leo**.
On the Leo side, a single statement::

    ip = IPython.ipapi.get()

assigns ip to IPython's _ip variable. The ip variable allows scripts running in
Leo to do *anything* that an IPython script can do.

2. **You can run any Leo script from IPython**. 
The --ipython command-line option (or the ipython-new command) injects a single object named '_leo' into the IPython namespace. 
IPython scripts access Leo's c and g objects as
follows::

    c,g = _leo.c, _leo.g

The c and g variables allow scripts running in IPython to do *anything* that a
Leo script can do. 

This is basically everything that is required for IPython-Leo interaction.
However, you probably wont use 'c' and 'g' directly, but use a series of
convenience wrappers described in this document that make interactive work
painless and powerful.

.. contents::
    :depth: 2


</t>
<t tx="ekr.20131017051340.16832">.. Links

.. _ipython:                http://ipython.scipy.org/
.. _IPython:                http://ipython.scipy.org/
.. _`IPython Notebook`:     http://projects.scipy.org/ipython/ipython/wiki/NoteBook
.. _extensionAPI:           http://ipython.scipy.org/moin/IpythonExtensionApi
.. _`The Ipython Extension API`: extensionAPI_
.. _`Scripting Leo with Python`:    scripting.html

.. _`run Leo in a console window`:  installing.html#running-leo-from-a-console-window
.. _`console window`:               installing.html#running-leo-from-a-console-window
</t>
<t tx="ekr.20131017051340.16833">ILeo, or leo-ipython bridge, creates a two-way communication channel between Leo
and IPython. The level of integration is much deeper than conventional
integration in IDEs; most notably, you are able to store and manipulate **data**
in Leo nodes, in addition to mere program code - essentially making ILeo a
hierarchical spreadsheet, albeit with non-grid view of the data. The
possibilities of this are endless, and the approach can be applied in wide range
of problem domains with very little actual coding.

IPython users are accustomed to using things like %edit to produce non-trivial
functions/classes (i.e. something that they don't want to enter directly on the
interactive prompt, but creating a proper script/module involves too much
overhead). In ILeo, this task consists just going to the Leo window, creating a node
and writing the code there, and pressing alt+I (push-to-ipython).

Obviously, you can save the Leo document as usual - this is a great advantage
of ILeo over using %edit, you can save your experimental scripts all at one
time, without having to organize them into script/module files (before you
really want to, of course!)
</t>
<t tx="ekr.20131017051340.16834">You need at least Leo 4.4.8, and IPython 0.8.3

The ILeo concept is still being developed actively, so if you want to get access
to latest features you can get IPython from Launchpad by installing bzr and
doing::

    bzr branch lp:ipython
    cd ipython
    python setupegg.py develop

You need to enable the 'ipython.py' plugin in Leo: 

- Help -&gt; Open LeoSettings.leo

- Edit @settings--&gt;Plugins--&gt;@enabled-plugins, add/uncomment 'ipython.py'

- Alternatively, you can add @settings--&gt;@enabled-plugins with body ipython.py to your leo document.

- Restart Leo. Be sure that you have the console window open
  (`run Leo in a console window`_, or double-click leo.py on windows)

- When using the Qt ui, add --ipython argument to command line (e.g. launchLeo.py --ipython).

- Press alt+shift+i OR alt-x start-ipython to launch IPython in the console that
  started leo. You can start entering IPython commands normally, and Leo will keep
  running at the same time.

- Note that you can just press alt-I (push-to-ipython) - it will start IPython
  if it has not been previously started. However, when you open a new leo
  document, you have to execute start-ipython (alt+shift+I) again to tell
  IPython that the new commands should target the new document. IPython session
  will not be restarted, only the leo commander object is updated in the
  existing session.

- If you want to specify command line arguments to IPython (e.g. to choose a
  profile, or to start in 'pylab' mode), add this to your @settings:
  '@string ipython_argv = ipython -pylab' (where -pylab is the command line argument)
</t>
<t tx="ekr.20131017051340.16835">IPython code
------------

Just enter IPython commands on a Leo node and press alt-I to execute
push-to-ipython in order to execute the script in IPython. 'commands' is
interpreted loosely here - you can enter function and class definitions, in
addition to the things you would usually enter at IPython prompt - calculations,
system commands etc.

Everything that would be legal to enter on IPython prompt is legal to execute
from ILeo.

Results will be shows in Leo log window for convenience, in addition to the console.

Suppose that a node had the following contents::

    1+2
    print "hello"
    3+4

    def f(x):
        return x.upper()

    f('hello world')

If you press alt+I on that node, you will see the following in Leo log window (IPython tab)::

    In: 1+2
    &lt;2&gt; 3
    In: 3+4
    &lt;4&gt; 7
    In: f('hello world')
    &lt;6&gt; 'HELLO WORLD'

(numbers like &lt;6&gt; mean IPython output history indices; the actual object can be
referenced with _6 as usual in IPython).


Plain Python code
-----------------

If the headline of the node ends with capital P, alt-I will not run the code
through IPython translation mechanism but use the direct python 'exec' statement
(in IPython user namespace) to execute the code. It wont be shown in IPython
history, and sometimes it is safer (and more efficient) to execute things as
plain Python statements. Large class definitions are good candidates for P
nodes.
</t>
<t tx="ekr.20131017051340.16836">The real fun starts when you start entering text to leo nodes, and are using
that as data (input/output) for your IPython work.

Accessing Leo nodes happens through the variable **wb** (short for "WorkBook")
that exist in the IPython user namespace. Nodes that are directly accessible are
the ones that have simple names which could also be Python variable names;
'foo_1' will be accessible directly from IPython, whereas 'my scripts' will not.
If you want to access a node with arbitrary headline, add a child node '@a foo'
(@a stands for 'anchor'). Then, the parent of '@a foo' is accessible through
'wb.foo'.

You can see what nodes are accessible be entering (in IPython) wb.&lt;TAB&gt;. Example::

    [C:leo/core]|12&gt; wb.
    wb.b           wb.tempfile    wb.rfile       wb.NewHeadline
    wb.bar         wb.Docs        wb.strlist     wb.csvr    
    [C:leo/core]|12&gt; wb.tempfile
                &lt;12&gt; &lt;ipy_leo.LeoNode object at 0x044B6D90&gt;

So here, we meet the 'LeoNode' class that is your key to manipulating Leo
content from IPython!

LeoNode
-------

Suppose that we had a node with headline 'spam' and body::

    ['12',2222+32]

we can access it from IPython (or from scripts entered into other Leo nodes!) by doing::

    C:leo/core]|19&gt; wb.spam.v
               &lt;19&gt; ['12', 2254]

'v' attribute stands for 'value', which means the node contents will be run
through 'eval' and everything you would be able to enter into IPython prompt
will be converted to objects. This mechanism can be extended far beyond direct
evaluation (see '@cl definitions').

'v' attribute also has a setter, i.e. you can do::

    wb.spam.v = "mystring"

Which will result in the node 'spam' having the following text::

    'mystring'

What assignment to 'v' does can be configured through generic functions
('simplegeneric' module, see ipy_leo.py for examples).

Besides v, you can set the body text directly through::

    wb.spam.b = "some\nstring", 

headline by::

    wb.spam.h = 'new_headline' 

(obviously you must access the node through wb.new_headline from that point
onwards), and access the contents as string list (IPython SList) through
'wb.spam.l'.

If you do 'wb.foo.v = 12' when node named 'foo' does not exist, the node titled
'foo' will be automatically created and assigned body 12.

LeoNode also supports go() that focuses the node in the Leo window, and ipush()
that simulates pressing alt+I on the node (beware of the possible recursion!).

You can access unknownAttributes by .uA property dictionary. Unknown attributes
allow you to store arbitrary (pickleable) python objects in the Leo nodes; the
attributes are stored when you save the .leo document, and recreated when you
open the document again. The attributes are not visible anywhere, but can be
used for domain-specific metadata. Example::

    [C:leo/core]|12&gt; wb.spam.uA['coords'] = (12,222)
    [C:leo/core]|13&gt; wb.spam.uA
                &lt;13&gt; {'coords': (12, 222)}    

Accessing children with iteration and dict notation
---------------------------------------------------

Sometimes, you may want to treat a node as a 'database', where the nodes
children represent elements in the database. You can create a new child node for
node 'spam', with headline 'foo bar' like this::

    wb.spam['foo bar'] = "Hello"

And assign a new value for it by doing::

    wb.spam['foo bar'].v = "Hello again"

Note how you can't use .v when you first create the node - i.e. the node needs
to be initialized by simple assignment, that will be interpreted as assignment
to '.v'. This is a conscious design choice.

If you try to do wb.spam['bar'] = 'Hello', ILeo will assign '@k bar' as the
headline for the child instead, because 'bar' is a legal python name (and as
such would be incorporated in the workbook namespace). This is done to avoid
crowding the workbook namespace with extraneous items. The item will still be
accessible as wb.spam['bar']

LeoNodes are iterable, so to see the headlines of all the children of 'spam' do::

    for n in wb.spam:
        print n.h
</t>
<t tx="ekr.20131017051340.16837">If the first line in the body text is of the form '@cl sometext', IPython will
evaluate 'sometext' and call the result with the rest of the body when you do
'wb.foo.v' or press alt+I on the node. An example is in place here. Suppose that we have defined a class (I
use the term class in a non-python sense here)::

    def rfile(body,node):
        """ @cl rfile 

        produces a StringIO (file like obj) of the rest of the body """

        import StringIO
        return StringIO.StringIO(body)

(note that node is ignored here - but it could be used to access headline,
children etc.),

Now, let's say you have node 'spam' with text::

    @cl rfile
    hello
    world
    and whatever

Now, in IPython, we can do this::

    [C:leo/core]|22&gt; f = wb.spam.v
    [C:leo/core]|23&gt; f
                &lt;23&gt; &lt;StringIO.StringIO instance at 0x04E7E490&gt;
    [C:leo/core]|24&gt; f.readline()
                &lt;24&gt; u'hello\n'
    [C:leo/core]|25&gt; f.readline()
                &lt;25&gt; u'world\n'
    [C:leo/core]|26&gt; f.readline()
                &lt;26&gt; u'and whatever'
    [C:leo/core]|27&gt; f.readline()
                &lt;27&gt; u''    

You should declare new @cl types to make ILeo as convenient your problem domain
as possible. For example, a "@cl etree" could return the elementtree object for
xml content.

In the preceding examples, the return value matter. That, of course, is optional.
You can just use the @cl node as a convenient syntax for "run this body text through 
a function". 

Consider this example::

    def remote(body, node):
        out = sshdo(body)
        c = node.append()
        c.b = "@nocolor\n" + out
        c.h = "Command output"

(sshdo(s) is a just a trivial function implemented using paramiko, that
returns the output from command run over ssh on remote host).

After running the above node (by, say, wb.require('remote_impl') if the function is 
declared in a node named 'remote_impl'), you can create nodes that have various 
little sysadmin tasks (grep the logs, gather data, kick out all the users) like this::

    @cl remote
    cd /var/log
    ls -l
    echo " --- temp ---"
    cd /var/tmp
    ls -l

Press alt+I on the node to run it. The output will be written to
"Command output" child node.
</t>
<t tx="ekr.20131017051340.16838">@ipy-startup
------------

If this node exist, the *direct children* of this will be pushed to IPython when
ILeo is started (you press alt+shift-i). Use it to push your own @cl
definitions, import the modules you will be using elsewhere in the document, etc.

The contents of of the node itself will be ignored.


@ipy-results
------------

If you press alt+I on a node that has @cl, it will be evaluated and the result
will be put into this node. Otherwise, it will just be displayed in log tab.

@ipy-root
---------

You can set up a subportion of the leo document as a "sandbox" for your IPython
work. Only the nodes under @ipy-root will be visible through the 'wb' variable.

Also, when you create a new node (wb.foo.v = 'stuff'), the node foo will be created as
a child of this node. 

@a nodes
--------

You can attach these as children of existing nodes to provide a way to access
nodes with arbitrary headlines, or to provide aliases to other nodes. If
multiple @a nodes are attached as children of a node, all the names can be used
to access the same object.
</t>
<t tx="ekr.20131017051340.16839">Sometimes you may decide to launch Leo when an IPython session is already
running. This is typically the case when IPython is launched from/as another
application (Turbogears/Django shell, Sage, etc.), or you only decide later on
that you might want to roll up some scripts or edit your variables in Leo.

Luckily, this is quite easy, if not automatic (yet) using IPython's %run command
that runs python code in the IPython process. The only special consideration is
that we need to run IPython.Shell.hijack_tk() to prevent Leo Tk mainloop from
blocking IPython in %run. Here we launch an embedded Leo instance, and create a
macro 'embleo' for later use (so that we don't have to repeat these steps)::

    IPython 0.8.3.bzr.r57   [on Py 2.5.1]
    [C:opt/Console2]|2&gt; import IPython.Shell
    [C:opt/Console2]|3&gt; IPython.Shell.hijack_tk()
    [C:opt/Console2]|4&gt; cd c:/leo.repo/trunk
    [c:leo/leo.repo/trunk]|5&gt; %run launchLeo.py

    reading settings in C:\leo\leo\config\leoSettings.leo

    ... Leo is starting at this point, but IPython prompt returns ...

    [c:leo/leo.repo/trunk]|6&gt; macro embleo 2-5

    [c:leo/leo.repo/trunk]|7&gt; store embleo
    Stored 'embleo' (Macro)

Now, in Leo, you only need to press Alt+Shift+I (launch-ipython) to actually
make the document visible in IPython. Despite the name, launch-ipython will not
create a new instance of IPython; if an IPython session already exists, it will
be automatically used by ILeo.
</t>
<t tx="ekr.20131017051340.16840">Sometimes, you might want to configure what alt+I on a node does. You can do
that by creating your own push function and expose it using
ipy_leo.expose_ileo_push(f, priority). The function should check whether the
node should by handled by the function and raise IPython.ipapi.TryNext if it
will not do the handling, giving the next function in the chain a chance to see
whether it should handle the push.

This example would print an uppercase version of node body if the node headline ends
with U (yes, this is completely useless!)::

    def push_upcase(node):
        if not node.h.endswith('U'):
            raise TryNext
        print node.b.upper()

    ipy_leo.expose_ileo_push(push_upcase, 12)

(the priority should be between 0-100, with 0 being the highest (first one to
try) - typically, you don't need to care about it and can usually omit the
argument altogether)
</t>
<t tx="ekr.20131017051340.16841">Get list of all headlines of all the nodes in leo::

    [node.h for node in wb]

Create node with headline 'baz', empty body::

    wb.baz

Create 10 child nodes for baz, where i is headline and 'Hello ' + i is body::

    for i in range(10):
        wb.baz[i] = 'Hello %d' % i

Create 5 child nodes for the current node (note the use of special _p variable,
which means "current node") and moves focus to node number 5::

    for i in range(10):
        _p[i] = 'hello %d' % d
    _p[5].go()

Sort contents of a node in alphabetical order (after pushing this to
IPython, you can sort a node 'foo' in-place by doing sort_node(wb.foo))::

    def sort_node(n):
        lines = n.l
        lines.sort()
        n.l = lines
</t>
<t tx="ekr.20131017051340.16842">If you install matplotlib and numpy, you can use ILeo to interactively edit and
view your data. This is convenient for storing potentially valuable information
in Leo document, and yields an interactive system that is comparable in
convenience to various commercial mathematical packages (at least if you compare
it against plain IPython, that forgets the data on exit unless explicitly saved
to data files or %store:d).

Startup
-------

It's probably safest to rely on TkAgg back end, to avoid two event loops running
in the same process. TkAgg is the default, so the only thing you need to do is
to install numpy and matplotlib::

    easy_install numpy
    easy_install matplotlib

Finally, you need to start up IPython with '-pylab' option. You can accomplish
this by having the following under some @settings node::

    @string ipython_argv = ipython -pylab

Then, you just need to press alt+I to launch IPython.

Usage
-----

The simplest use case is probably pushing an existing array to Leo for editing.
Let's generate a simple array and edit it::

    [c:/ipython]|51&gt; a = arange(12).reshape(3,4)
    [c:/ipython]|52&gt; a
    array([[ 0,  1,  2,  3],
           [ 4,  5,  6,  7],
           [ 8,  9, 10, 11]])
    [c:/ipython]|53&gt; %lee a

This (the magic command %lee, or 'leo edit') will open variable 'a' for editing
in Leo, in a convenient pretty-printed format. You can press alt+I on the node
to push it back to IPython.

If you want to store the variable in a node with a different name (myarr), you can do::

    [c:/ipython]|54&gt; wb.myarr.v = a

Then, you can always get the value of this array with wb.myarr.v. E.g. you could
have a node that plots the array, with content::

    # press alt+i here to plot testarr

    plot(wb.myarr.v)

And, as per instructions, pressing alt+I will launch a new Tk window with the
plotted representation of the array!
</t>
<t tx="ekr.20131017051340.16843">%mb
---

Execute leo minibuffer command. Tab completion works. Example::

    mb open-outline

%lee
----

Stands for "LEo Edit". Allows you to open file(s), and even objects in Leo for editing. Examples::

    lee *.txt

Opens all txt files in @auto nodes

::

    lee MyMacro

Opens the macro MyMacro for editing. Press alt-I to push the edited macro back to IPython.

::

  s = 'hello word'
  lee s

Opens the variable s for editing. Press alt+I to push the new value to IPython.

::

    lee hist   

Opens IPython interactive history (both input and output) in Leo.
</t>
<t tx="ekr.20131017051340.16844">This idea got started when I (Ville M. Vainio) saw this post by Edward Ream
(the author of Leo) on IPython developer mailing list:

    http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html

I was using FreeMind as mind mapping software, and so I had an immediate
use case for Leo (which, incidentally, is superior to FreeMind as mind
mapper). The wheels started rolling, I got obsessed with the power of this
concept (everything clicked together), and Edwards excitement paralleled
mine. Everything was mind-bogglingly easy/trivial, something that is
typical of all promising technologies.

The goal of close cooperation between Leo and IPython went from vague dream
to completed reality over the span of about 10 days.
</t>
<t tx="ekr.20131017051340.16847">@language python

</t>
<t tx="ekr.20131017051340.16850">@language python
</t>
<t tx="ekr.20131017094004.16739"></t>
<t tx="ekr.20131017174814.17479">.. _`Leo's tutorial`: tutorial.html
.. _`ask for help`:   https://groups.google.com/forum/#!forum/leo-editor
.. _`Directed Acyclic Graphs`: https://en.wikipedia.org/wiki/Directed_acyclic_graph
.. _`group of developers and users`: https://groups.google.com/forum/#!forum/leo-editor
.. _`The Leonine world`: leonine-world.html

Leo is a fundamentally different way of using and organizing data, programs
and scripts. Leo has been under active development for 15 years and has an
active `group of developers and users`_.

You won't learn all about Leo in a day or two. `Leo's tutorial`_
explains the basic features. You can learn more advanced features
later. Please `ask for help`_ immediately if you get stuck.

Leo has shamelessly stolen the best features of Emacs, including the
minibuffer and many Emacs-like commands. But Leo goes *far* beyond
other editors:

- Leo *completely integrates* Python scripting and outlines, not just the
  outline's data, but the outline structure as well.

- Features such as @test nodes and @button nodes can not even be *thought*
  in traditional editors. Leo implements such features easily; other editors
  could only simulate them--laboriously and unnaturally.
   
- Leo's outlines are based `Directed Acyclic Graphs`_. As a result, Leo can
  organize data in completely new ways.
  
These features combine to accelerate your work flow in a unique
**Leonine** way, described more fully in `The Leonine world`_.
  
In the next sections, Leo's users tell, in their own words, why they think
Leo is something truly special...
  </t>
<t tx="ekr.20131018100353.16706">Clones can greatly accelerate your work flow. To start a project, clone
nodes related to the project and drag them at or near the top level, where
you can get at them easily. When the project is complete, just delete the
clones. This work flow is surprisingly effective:

- The original nodes never move, but they change whenever their clones do.

- There is nothing to "put back in place" when you are done. Just delete the
  clones.
  
Used this way, **clones create views**: when you gather cloned nodes
together for a project, you are, in effect, creating a project-oriented
view of the outline. This view **focuses your attention** on only those
nodes that are relevant to the task at hand.
</t>
<t tx="ekr.20131019035402.17557"></t>
<t tx="ekr.20131019035402.17573">#################
The Leonine World
#################

**Leonine** refers to Leo's unique way of organizing data and
programs. This has many implications:

**Browsing**: Leo remembers your outline organization. Class browsers
don't. Doh!

**The big picture**: Outline nodes hide messy details, revealing the big
picture *at all times*.

**Programming**: Leo outlines naturally organize programs into modules,
classes and functions. Leonine sources are their own design document. How
you organize outlines is a choice in a new design space.

**User-defined types**: Headlines naturally describe a node's contents:
**headlines naturally define types**. Leo's core supports types such as
@button, @rst, @suite, @url, etc. Plugins define @bookmark, @graph, @html
and @task types. Scripts can easily define other types.

**Testing**: Leo's @test nodes creates a unique unit-testing framework:

- @test nodes focus on the real test code.
- It is easy to run only the @test nodes in a particular suboutline.
- @test scripts can easily use data in their children.

**Work flow**: Clones accelerate your work flow by focusing your attention
on the task at hand. Once you have gathered the relevant nodes, there is no
need to keep searching for them. You can change the clones, and the
original nodes change as well. This is a great way to fix bugs or to write
books.

**Databases**: Leo's clones create new opportunities for scriptable
databases. In my brother Speed's outlines, suboutlines *are* SQL queries!
</t>
<t tx="ekr.20131019061259.16677"></t>
<t tx="ekr.20131019061259.16683"></t>
<t tx="ekr.20131019061259.16684"></t>
<t tx="ekr.20131019061259.16686">execute-script predefines::

    c: The commander of the present outline.
    g: The leo.core.leoGlobals module.
    p: The presently selected position, c.p.
    
@test scripts predefine all the above, plus::

    self: The instance of unittest.TestCase
</t>
<t tx="ekr.20131019061259.16687">::

    c.all_positions()
    c.all_unique_positions()
    p.children()
    p.parents()
    p.self_and_parents()
    p.self_and_siblings()
    p.following_siblings()
    p.subtree()
    p.self_and_subtree()
</t>
<t tx="ekr.20131019061259.16688">::

    c.frame         c's outer frame, a leoFrame instance.
    c.user_dict     a temporary dict for use of scripts and plugins.
    c.redraw()
    c.positionExists(p)

Here is a partial list of the **official ivars** of any leoFrame f::

    f.c                     is the frame’s commander.
    f.body                  is a leoBody instance.
    f.body.bodyCtl          is a leoQTextEditWidget instance.
    f.body.bodyCtrl.widget  is a LeoQTextBrowser(QTextBrowser) instance.
    f.log                   is a leoLog instance.
    f.tree                  is a leoQtTree instance.
    f.tree.treeWidget       is a LeoQTreeWidget (a QTreeWidget) instance.
    
Use autocompletion to explore these objects!
</t>
<t tx="ekr.20131019061259.16690">::

    v.b: v's body text.
    v.h: v's headline text.
    v.u: v.unknownAttributes, a persistent Python dictionary.
    
v.u (uA's or unknownAttributes or userAttributes) allow plugins or scripts
to associate persistant data with vnodes. For details see the section about
`userAttributes`_ in the `Customizing Leo`_ chapter.
</t>
<t tx="ekr.20131019061259.16691">**Properties**::

    p.b: same as p.v.b.
    p.h: same as p.v.h.
    p.u: same as p.v.u.

**Getters**::

    p.back()
    p.children()
    p.firstChild()
    p.hasBack()
    p.hasChildren()
    p.hasNext()
    p.hasParent()
    p.hasThreadBack()
    p.hasThreadNext()
    p.isAncestorOf(p2)
    p.isAnyAtFileNode()
    p.isAt...Node()
    p.isCloned()
    p.isDirty()
    p.isExpanded()
    p.isMarked()
    p.isRoot()
    p.isVisible()
    p.lastChild()
    p.level()
    p.next()
    p.nodeAfterTree()
    p.nthChild()
    p.numberOfChildren()
    p.parent()
    p.parents()
    p.threadBack()
    p.threadNext()
    p.visBack()
    p.visNext()
    
**Setters**::

    p.setDirty()
    p.setMarked()

**Operations on nodes**::

    p.clone()
    p.contract()
    p.doDelete(new_position)
    p.expand()
    p.insertAfter()
    p.insertAsNthChild(n)
    p.insertBefore()
    p.moveAfter(p2)
    p.moveToNthChildOf(parent,n)
    p.moveToRoot(oldRoot=None)
        # oldRoot **must** be the old root position if it exists.
        
**Moving positions**

The following move positions *themselves*: they change the node to which a
position refers. They do *not* change outline structure in any way! Use
these when generators are not flexible enough::

    p.moveAfter(p2)
    p.moveToBack()
    p.moveToFirstChild()
    p.moveToFirstChildOf(p2)
    p.moveToLastChild()
    p.moveToLastChildOf(p2)
    p.moveToLastNode()
    p.moveToNext()
    p.moveToNodeAfterTree(p2)
    p.moveToNthChild()
    p.moveToNthChildOf(p2)
    p.moveToParent()
    p.moveToRoot()
    p.moveToThreadBack()
    p.moveToThreadNext()
    p.moveToVisBack(c)
    p.moveToVisNext(c)
</t>
<t tx="ekr.20131019061259.16692">For full details, see @file leoGlobals.py in LeoPyRef.leo.

**g vars**::

    g.app
    g.app.gui
    g.app.windowlist
    g.unitTesting
    g.user_dict  # a temporary dict for use of scripts and plugins.
    
**g decorator**::

    @g.command(command-name)
    
**g functions** (the most interesting: there are many more in leoGlobals.py)::
    
    g.angleBrackets()
    g.app.commanders()
    g.app.gui.guiName()
    g.es(*args,**keys)
    g.es_print(*args,**keys)
    g.es_exception()
    g.getScript(c,p,
        useSelectedText=True,
        forcePythonSentinels=True,
        useSentinels=True)
    g.openWithFileName(fileName,old_c=None,gui=None)
    g.os_path_... # Wrappers for os.path methods.
    g.pdb(message='')
    g.toEncodedString(s,encoding='utf-8',reportErrors=False)
    g.toUnicode(s, encoding='utf-8',reportErrors=False)
    g.trace(*args,**keys)
    g.warning(*args,**keys)
</t>
<t tx="ekr.20131019061259.16693"></t>
<t tx="ekr.20131019184243.16660">@language rest

Python is an easy to learn, powerful programming language. It has efficient
high-level data structures and a simple but effective approach to
object-oriented programming. Python’s elegant syntax and dynamic typing,
together with its interpreted nature, make it an ideal language for
scripting and rapid application development in many areas on most
platforms.

The Python interpreter and the extensive standard library are freely
available in source or binary form for all major platforms from the Python
Web site, http://www.python.org/, and may be freely distributed. The same
site also contains distributions of and pointers to many free third party
Python modules, programs and tools, and additional documentation.

The Python interpreter is easily extended with new functions and data types
implemented in C or C++ (or other languages callable from C). Python is
also suitable as an extension language for customizable applications.

This tutorial introduces the reader informally to the basic concepts and
features of the Python language and system. It helps to have a Python
interpreter handy for hands-on experience, but all examples are
self-contained, so the tutorial can be read off-line as well.
</t>
<t tx="ekr.20131019184243.16661">What GNU Emacs Is

GNU Emacs is a free, portable, extensible text editor. That it is free
means specifically that the source code is freely copyable and
redistributable. That it is portable means that it runs on many machines
under many different operating systems, so that you can probably count on
being able to use the same editor no matter what machine you're using. That
it is extensible means that you can not only customize all aspects of its
usage (from key bindings through fonts, colors, windows, mousage and
menus), but you can program Emacs to do entirely new things that its
designers never thought of.

Because of all this, Emacs is an extremely successful program, and does
more for you than any other editor. It's particularly good for programmers.
If you use a common programming language, Emacs probably provides a mode
that makes it especially easy to edit code in that language, providing
context sensitive indentation and layout. It also probably allows you to
compile your programs inside Emacs, with links from error messages to
source code; debug your programs inside Emacs, with links to the source;
interact directly with the language interpretor (where appropriate); manage
change logs; jump directly to a location in the source by symbol (function
or variable name); and interact with your revision control system.

Emacs also provides mail readers, news readers, World Wide Web, gopher, and
FTP clients, spell checking, and a Rogerian therapist, all of which are
also useful for programming. But in this document we'll concentrate on the
basics of Emacs usage for programmers.

What GNU Emacs Is Not

First and foremost, GNU Emacs is not a WYSIWYG word processor. This is
primarily because it's designed as a programmer's editor, but Emacs is also
used to edit documents by people who use non-WYSIWYG typesetters like TeX
and Troff.

Actually, this is about the only thing I can think of that GNU Emacs is
not.</t>
<t tx="ekr.20131019184243.16701"></t>
<t tx="peckj.20130813123907.6841" str_ctime="1376412039.0" str_mtime="1376412039.0" str_atime="1376414164.0">Documenting new plugins is important for users to be able understand
and use the features they add. To that effect, there are a few
documentation steps that should not be overlooked.

- Document the plugin thoroughly in the plugin's docstring. This
  allows the documentation to be accessed from the Plugins menu.
  
- Document any new commands with a proper docstring. This allows the
  minibuffer command `help-for-command` to provide help for the
  command.
  
- In `leo/doc/sphinx-docs/sphinxDocs.leo`, to the node `@file
  leo.plugins.rst`, add the following snippet (preferably in
  alphabetical order), with the name of the plugin modified to the
  name of your plugin (here `ipython`). This allows the API docs to be
  automatically updated::

    :mod:`ipython` Module
    ---------------------
    
    .. automodule:: leo.plugins.ipython
        :members:
        :undoc-members:
        :show-inheritance:
</t>
<t tx="shadow.20080825171547.9">**Question**: I must follow a coding standard when writing source code. It
includes a maximum line length restriction. How can I know the length of a
line when it gets written to the external file?

**Answer**: If a node belongs to a external file hierarchy, its body might get
indented when it is written to the external file. It happens when an
\@others directive or a section name appears indented in a higher-level
node body. While (**line**, **col**) in status area show the line and column
containing the body text's cursor, **fcol** shows the cursor coordinate
relative to the external file, not to the current node. The relation
**fcol &gt;= col** is always true.
</t>
<t tx="sps.20100708203040.19008">@language python
import os
pos = c.find_h("Users Guide")[0]
c.selectPosition(pos)
c.k.simulateCommand('rst3')
&lt;&lt; html manual &gt;&gt;
&lt;&lt; pdf manual &gt;&gt;
</t>
<t tx="sps.20100708203040.19009">d = c.scanAllDirectives(p)
mandir = d.get('path') + "/html"
g.es(mandir)
os.chdir(mandir)
os.system('make html')
</t>
<t tx="sps.20100708203040.19010"># you probably need to install several packages 
# to create pdf (e.g. jadetex)
mandir = d.get('path') + "/html"
g.es(mandir)
os.chdir(mandir)
os.system('make latex')
os.chdir('_build/latex')
os.system('../../fixup.pl &lt; Leodocumentation.tex &gt; LeoDoc.tex')
os.system('make LeoDoc.pdf')
</t>
<t tx="sps.20100708213227.44914"></t>
<t tx="ville.20090705224948.5734">import os
pos = c.find_h("Users Guide")[0]
c.selectPosition(pos)
c.k.simulateCommand('rst3')
&lt;&lt; html manual &gt;&gt;
# no pdf manual creation, perhaps too "involved" for many
</t>
<t tx="ville.20090705225609.5736">mandir = g.app.leoDir + "/doc/html"
g.es(mandir)
os.chdir(mandir)
os.system('make html')
</t>
<t tx="ville.20090705225609.5738"># you probably need to install several packages 
# to create pdf (e.g. jadetex)
mandir = g.app.leoDir + "/doc/html"
g.es(mandir)
os.chdir(mandir)
os.system('make latex')
os.chdir('_build/latex')
os.system('make all-pdf')
</t>
<t tx="vivainio.20080302174639.1">Leo's --ipython command-line option enables two-way communication
(**ILeo**, the **IPython bridge**) between Leo and IPython: you can run Leo
scripts from IPython, and IPython scripts from Leo.

The level of integration is much deeper than conventional integration in
IDEs. Most notably, you are able to store and manipulate *data* in Leo
nodes, in addition to mere program code--essentially making ILeo a
hierarchical spreadsheet, albeit with non-grid view of the data. The
possibilities of this are endless, and the approach can be applied in wide
range of problem domains with very little actual coding.
</t>
<t tx="vivainio.20080302174639.2">To run Leo's IPython bridge:

1. Install IPython 0.8.3 or above.

2. `run Leo in a console window`_ with the --ipython command-line option
   enabled. This option starts an instance of the IPython shell in the
   console. Leo and IPython run simultaneously and independently. Their
   separate event loops do not interfere with each other.
</t>
</tnodes>
</leo_file>