Chapter 5: Using Leo's Commands

This chapter is discusses all of Leo's menu commands. It is organized by menu, and by function within each menu. Unless otherwise mentioned, everything in this chapter applies to both leo.py and the Windows version of Leo.

A note about typography: in this chapter command names and menu names will be capitalized, just as they would be in a menu. This convention allows us to write, for example, the Save A Copy As command, rather than having to use distracting quotation marks, like the "Save A Copy As" command.

The File Menu

Loading, saving and restoring files
Communicating with external editors
Tangling an outline: producing derived files
Tangling and untangling: the interface with the IDE
Untangling: updating an outline
Import files into Leo
Exporting files from Leo
Quitting Leo

The Edit Menu

Cutting, pasting and selecting text
Executing Python scripts in body text
Shifting body text
Extracting sections from body text
Converting leading tabs and spaces in body text
Finding matching brackets and parentheses
Finding and changing text
Finding locations in outlines corresponding to line in derived files
Reformatting paragraphs
Setting preferences and leoConfig.txt

The Outline Menu

Creating and deleting headlines
Expanding and contracting headlines
Moving and reorganizing headlines
Marking headlines
Cloning nodes

The Window Menu

Resizing panes
Cascading & minimizing windows
Toggling the active pane and the orientation of the Leo window

The Help Menu

Getting Leo's version
Reading documentation
Configuring Leo

The File Menu

Loading, saving and restoring files
Communicating with external editors
Tangling an outline: producing derived files
Tangling and untangling: the interface with the IDE
Untangling: updating an outline
Import files into Leo
Exporting files from Leo
Quitting Leo

Loading, saving and restoring files

The New command creates a new Leo main window.

The Open command opens an existing Leo file and shows it in a main window.   The Open command updates @file nodes from changes to the derived files.  That is, Leo automatically untangles @file trees when reading a .leo file.

The Close command closes the topmost Leo window, and gives you an opportunity to save your work if you haven't yet done so.

The Save, Save As and Save A Copy As commands save the topmost Leo window to a file. The Save commands write derived files for all changed @file trees. That is, Leo automatically tangles all changed @file trees when writing a .leo file.  However, Leo never tangles @file nodes that contain orphan or @ignore nodes; instead, Leo issues a warning and writes the @file tree to the outline (.leo) file.

The Revert command reloads a file, discarding any changes made to the file since it was last saved.

New in leo.py 2.5, the Recent Files command: The Recent Files command brings up a submenu containing a list of recently opened files. Choosing an item in this submenu opens the selected file or brings it to the front. Leo adds files to this submenu even if leoConfig.txt is missing or read-only, but those additions will not be remembered unless leoConfig.txt is present and write enabled.

Communicating with external editors

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 in the Open With submenu. This would typically be done in a hook routine, using the createOpenWithMenuFromTable routine described in Chapter 8, Customizing Leo. The @file customizeLeo.py node in LeoPy.leo gives a complete example of handling the Open With menu.

Tangling an outline: producing derived files

The Save commands automatically create derived files from @file trees.

The following explicit commands create derived files from @root. 

The Tangle, Tangle All and Tangle Marked commands create derived files from portions of an outline. These commands indent and format the derived files so that they are easy to read and so that it is clear what sections produced the code. The .c file in the Examples folder shows the code produced by the Tangle commands.

The three Tangle commands are identical except for how much of the outline is tangled. The Tangle command tangles only the selected portion of the outline, the Tangle All command tangles the entire outline, and the Tangle Marked command tangles only marked headlines.

Derived files can be any kind of text files, from source text files, to "make" or "help" files to HTML or XML files.

The Tangle commands create a derived file, call it F, from each @root node. This process is much like macro expansion. The contents of F are simply the body text of the @root node, with each section reference replaced by its definition. Substitution continues until all references to sections are replaced with their definitions.

By default, Tangle commands look for section definitions only in the suboutline containing the @root directive being tangled. That is, all sections are assumed to be defined either in the body text of the headline, say h, containing the @root directive, or in the body texts of the descendants of h.

The @unit directive changes the default scope of the tangle command, while the @ignore directive causes the tangle commands to ignore a subtree. For more details, see the discussion of the @unit and @ignore commands in Chapter 3.

Untangling: updating an outline

The Load command automatically updates @file trees from derived files.

The following explicit commands update @root trees from changes made to derived files.

The Untangle, Untangle All and Untangle Marked commands are the reverse of the corresponding Tangle commands. They update an outline based on changes made to one or more derived files. There are exceptionally useful commands.

For example, suppose you create a new part of the outline and Tangle it for the first time. When you compile the resulting derived files for the first you are likely to get many syntax errors. You could fix those errors in the outline and Tangle the outline again, but there is a much easier way: you fix the errors in the derived files using the compiler's editor, then run the untangle command on the part of the outline that created the derived file. The Untangle command updates the selected outline to match the changes in the derived files. It's as simple as that. By the way, the Untangle command marks all the nodes in the outline that it updates, and you can examine all such nodes with the Go To Next Marked command in the Outline menu.

You cannot use Untangle to update doc parts, or leading comments in code parts or "trivial" whitespace in code parts. This is a limitation of the Untangle command that cannot be fixed; Untangle has no way of knowing whether leading comments came from doc parts or are just leading comments.

Untangle never changes the structure of an outline; it never inserts, deletes or moves nodes. Don't attempt to change the structure of an outline by modifying derived files; it won't work. Also, never delete, move or alter the sentinel lines in derived files written by the Tangle command. Such lines start with /// followed by a section name.

If you change the section name in a sentinel line Untangle will not update the code in the outline (with the old name) that generated the renamed section. Untangle now warns about sections that appear in a derived file but not in the outline. Untangle has no trouble with changed section references in derived files; it is only changed sentinel lines that cause problems.

Cloned nodes that generate code in several files may cause problems for Untangle if not all the code is changed the same way in derived files. If Untangle is run separately on these derived files, Untangle will update all cloned nodes each time it is run, so only the code in the last Untangle run will take effect. Therefore, the only reliable way to update text in cloned nodes is to make the change in the .leo file rather than the derived files.

Tangling and untangling: the interface with the IDE

This section applies only to @root trees only, not to @file trees.

When using the Tangle and Untangle commands there are several issues to be aware of concerning your IDE (Integrated Development Environment). This section applies particularly to the Borland IDE; similar remarks apply to other IDE's.

Assuming you have added a .cpp file to your project, you update the file with the Tangle command. When you switch to the IDE you will get a dialog asking whether you want to update the file. Say yes and rebuild or remake.

You won't get the dialog unless the file is already open in the IDE. There is a bug in the Borland IDE: the dialog doesn't come to the front, so it can be easy to miss.

Now suppose you compile the file and get 20 errors all over the .cpp file. You fix the errors _in the IDE_, save the file, switch to Leo, and run the Untangle command. All your changes will appear in the outline! Each changed node will be marked by the Untangle command.

If you like you can use the Go To Next Marked command to find each changed node.

Importing Files into Leo Outlines

Note: the following describe the import and export commands found in leo.py.  This documentation notes differences with the Windows version of Leo.

The Import to @file command creates an @file node from a file.  The Import to @root command creates an @root node from a file.  These commands do not attempt to do perfect translations; they merely automate the bulk of the drudgery.  The Import to @root command is called Import Files in the Borland/Windows version of Leo.  The Import to @file command does not exist in the Borland/Windows version of Leo.

The Import CWEB Files command creates an @file node from a CWEB file.  This command does not exist in the Borland/Windows version of Leo.

The Import noweb Files command creates an @file node from a CWEB file.  The Borland/Windows version of this command creates an @root node.

The Import Flattened Outline command (called Import MORE Text in the Borland/Windows version of Leo) converts plain text written in MORE format to an outline. This command brings up a dialog which will accept at most one file. If that file contains MORE-format text it creates an outline corresponding to that text.

MORE is a now- defunct Macintosh outliner program. MORE represents outlines as follows. Headlines are denoted by a leading + or - character, preceding by zero or more tabs that denote the level of the headline. Body text follows its headline, with no indentation. The original MORE format did not escape lines in the body text that started with + or -. Leo escapes such characters by preceding +, - or backslash with a backslash.

Exporting files from Leo outlines

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.  See the previous section for a discussion of the MORE format.

The Remove Sentinels command removes all sentinel lines from a file derived from an @file node.

Quitting Leo

The Quit command causes Leo to exit. You will be prompted to save any file that has been altered but not saved.

The Edit Menu

Undoing changes
Cutting, pasting and selecting text
Shifting body text
Extracting sections from body text
Converting leading tabs and spaces in body text
Finding and changing text
Finding locations in outlines corresponding to line in derived files
Reformatting paragraphs
Setting preferences and leoConfig.txt

Undoing changes

For leo.py version 2.0 and above. leo.py supports unlimited Undo and Redo. All outline operations, including the Change All command and all operations and commands that affect body text may be undone and redone. Only the "Read @file Nodes" command is undoable; it clears the undo state. This command raises a dialog to allow the user to cancel.

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.

For all Borland versions.  The body pane supports unlimited undo. However, you can not undo an operation affecting body text after selecting a new headline. You can undo or redo the last operation involving the outline itself. You can not undo operations affecting headline text.

Cutting, pasting and selecting text and outlines

Leo supports the standard editing commands that appear in the edit menu: Undo, Cut, Copy, Paste and Clear. These commands work with either headline (when a headlines text is being edited) or body text. Text may be cut, copied and pasted between headline text and body text.

The Cut Outline, Paste Outline, Copy Outline and Delete Outline commands work on nodes rather than text. For example, to delete a headline, select the headline and choose the Cut Outline or Delete Outline commands.

The Cut Outline and Copy Outline copy a text representation of the outline to the clipboard. This representation is the same as the file format with some information deleted. You may copy this text representation into a body pane (or into any other text editor) using the Paste command in the Edit menu.

Warning: In practice, it is almost wiser to move clones rather than cutting or pasting them. Cutting and pasting outlines preserves clones, but the links between clones only exist within the part of the outline that was pasted. Therefore, if you are cutting and pasting an outline containing clones it is best to cut and paste the _entire_ outline. Alternatively, you can paste part of an outline, then delete all clones.

The Select All command selects all text in the body pane.

Executing Python scripts in body text

The Execute Script command executes body text as a Python script. Leo execute the selected text, or the entire body text if no text is selected. Scripts are executed in a "pristine" environment, that is, with __builtins__ as both the local and global environments.

Shifting body test

The Shift Left and Shift Right commands shift selected lines in the body text left or right one tab position. The entire line is shifted if any characters of the line are selected.

Extracting nodes from body text

The Extract, Extract Section and Extract Section Names commands create child nodes whose headline is the first line of the selected body text.

The Extract command creates a new node whose headline is the first line of selected body text and whose body is all following lines of body text. All selected text is deleted from the original body text.

The Extract Section command creates a new node whose headline is the first line of selected text and whose body is @code followed by all the other lines of selected text. All selected text lines except the first line are deleted from the original body text. This command is enabled only if the first line contains a section name on a line by itself.

The Extract Section Names 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 and the body text of each created node is just @code followed by a newline.

Converting leading tabs and spaces in body text

New in leo.py v2.5. 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 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 tab width shown in the Preferences panel.

Finding matching brackets and parentheses

The Match Brackets command is enabled if the cursor is next to one of the following characters in the body pane: ( ) [ ] { } < >  This command looks for the matching character, searching backwards through the body text if the cursor is next to ) ] } or >   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.

Finding and changing text

The Edit menu contains four commands for searching and replacing text. The Find and Find Again commands search through the outline for text and the Change and Change, Then Find commands change selected text. The following is a screen shot of the Find/Change dialog:

The following check boxes options appear in the search dialog and control the operations of the find and change commands:

Batch

When checked, the Find and Change commands proceed without stopping. Output is sent to the log window regarding the progress of the command.

Ignore Case

When checked, the Find and Change commands ignore the case of alphabetic characters is ignored 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. The '*' character matches any sequence of zero or more characters. The '.' character matches any single character. The '^' character at the start of a pattern, or a '$' character at the end of a pattern matches a newline.

Examples:

The pattern "^abc$" matches lines that only contain "abc".

The pattern "^a" matches any line starting with "A".

The pattern "a$" matches any line ending with "a".

The pattern "^*$" matches any line at all.

Reverse

When checked, the Find and Change commands search backward through the file.

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.

Finding locations in outlines corresponding to line in derived files

New in leo.py v3.9.  The Go To Line Number command selects the locations in your outlines corresponding to a line in a derived file. The present version should be quite usable for its main purpose: tracking down lines corresponding to error messages. In particular, except for possible pathological cases, Leo should always put the cursor in the node containing the referenced line.

Reformatting paragraphs

New in leo.py v3.9. Whether importing text from an outside source, typing in text, or modifying text, eventually you end up with a block of text in which some lines are too long and some are too short. The Reformat Paragraph command will rearrange 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 the start and end of body text. 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 tangled (as part of a @root) or written (as part of a @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.

Be careful that you don't do this on source code! Of course, if you do reformat something that should have been left alone, then just Undo.

Note: Lines with hanging indentation are handled so that the 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.

Setting preferences and leoConfig.txt

The Set Colors command brings up a dialog specifying colors for syntax coloring. You can specify colors for each syntax coloring construct using a color wheel or by choosing one of the standard Tk color names. When a color becomes active Leo writes its value or color name to the log pane for your reference. This is useful when setting coloring options in leoConfig.txt.

The Set Font command brings allows you to specify the fonts used in the body pane, the outline pane (in headlines) and in the log pane. A font becomes active when you double-click its name, or check or uncheck any checkbox. When a font becomes "active", the new font appears in the panes whose check boxes are selected. Font sizes must be greater than 0 and less than 100 for them to become in effect. When you choose OK or Cancel Leo writes the fonts presently active in each pane to the log pane for your reference. This is useful when setting font options in leoConfig.txt.

The Preferences command brings up the preferences dialog. The Page Width option determines where Tangle will break lines. The other two global options control whether the Tangle and Untangle commands will execute a batch file when they are finished. The Default Target Language determines the default syntax coloring and the comment delimiters used by default when Tangling.

Leo converts tabs to blanks as you type when a negative tab width is specified.

The Preferences dialog is a modal dialog.  Preferences apply only to the window from which the Preferences dialog was launched.  Also, the Preferences dialog now has OK, Cancel and Revert buttons.  Closing the dialog by clicking the close icon at the top is equivalent to choosing the OK button.

Leo will override settings in .leo files if it finds a file called leoConfig.txt. Leo works just as before if it does not find a leoConfig.txt file. The Appendix shows an example of leoConfig.txt that shows all the options that may be set.

Leo looks for leoConfig.txt first in the directory specified by the Python variable called sys.leo_config_directory. You would typically set this variable in Python's sitecustomize.py file. If this variable does not exist, Leo looks in the directory from which Leo was loaded.

Settings in leoConfig.txt overrides preferences in .leo files, but only for those items actually in leoConfig.txt, so you can choose which settings you want to override. Also, a Leo ignores any setting in leoConfig.txt whose value is "ignore" (without the quotes). For example:

[override .leo file prefs]
tab_width = ignore

If a setting is overridden, it is not written to the .leo file when the outline is saved. Note that this does not change Leo's file format: all previous versions of Leo will be able to read such .leo files.

The preceding is probably all you need to know to use leoConfig.txt. Here are some details:

  1. When reading a .leo file, if a setting is found neither in leoConfig.txt nor in the .leo file, Leo uses a default, hard-coded value.
  2. Leo will update leoConfig.txt unless the read_only option is on in leoConfig.txt. Bug: there are problems when Leo does write leoConfig.txt: all comments are lost and options and sections are written in a random order. These are problems with Python's ConfigParser class.
  3. Provided the read_only option is off, Leo updates leoConfig.txt whenever it saves a .leo file or whenever the Preferences panel is closed without being cancelled. When updating leoConfig.txt, Leo will write only existing settings whose value is not "ignore".
  4. When Leo saves a .leo file, Leo will write a Preferences setting to the .leo file only if the setting will not be written when updating leoConfig.txt. In particular, changes made in the Preferences Panel will become permanent immediately if Leo the read_only option is off. Otherwise the change will become permanent when any .leo file is saved.

The Outline Menu

Creating and deleting headlines
Expanding and contracting headlines
Moving and reorganizing headlines
Marking headlines
Cloning nodes

Creating and deleting headlines

The Insert Headline command inserts a new headline after the presently selected headline, either as the next sibling or the first child of the presently selected headline if the presently selected headline has children and is expanded.

The Delete Node command deletes a headline and all its children.

Expanding and contracting headlines

The Expand command expands the currently selected node so that all its children are visible. The Expand All Subheads command expands the currently selected node so that all its offspring are visible. The Expand All command expands all the nodes of the entire tree.

Moving and reorganizing headlines

The Move Up, Move Down, Move Left and Move Right commands move the currently selected node in the indicated direction.

The Promote command makes all the children of a node siblings of the node. The Demote command makes all the siblings that follow a node into children of the node. For example, suppose we want to move a list of topics (headlines). Say:

	a
	b
	c

The easy way to do this is to create a new headline, temp, at the head of the list:

	temp
	a
	b
	c

Then use the demote command on temp to create:

	temp
		a
		b
		c

We can now move just the temp headline anywhere we please. Once the move is complete, we would choose promote to create:

	temp
	a
	b
	c

And finally we would remove temp.

Marking headlines

The Mark Headline command marks a headline with a red marker near the leader characters, while the Unmark Headline command removes such a mark. Only one of these commands appear in the Outline menu at any time: the Mark Headline command appears if the currently selected headline is unmarked. Otherwise, the Unmark Headline command appears. The Mark Subheads command marks all offspring of the currently selected node. The Unmark All command removes the marks from the entire tree.

The Mark Changed Items command marks all headlines whose headline or body text has been changed since the file was last saved. The Mark Changed Roots command marks all changed headlines whose body text contains the @root directive. This command is especially useful with the Tangle Marked command.

The Go To Next Mark command searches forward for the next marked headline, and makes that headline the current node if found.

Cloning nodes

The Clone command creates a clone of the currently selected node. The clone as placed as the next sibling of the currently selected node. The root node may not be cloned.

A cloned headline is a "hot copy" of an original node: the clone changes when the original node changes, including its headline and body text. Changes to the children, grandchildren, etc. of a node are simultaneously made to the corresponding nodes contained by all cloned nodes.

There is no real distinction made between the original node and its clones. All cloned nodes, including the original headline, are marked with a clone symbol . When the second-to-last cloned node is deleted, the remaining node becomes a regular node again.

Clones are useful for making alternate views of a program. For example, when I begin to fix a bug I clone all the sections of the code that relate to the bug, and place those cloned sections under a new headline whose name is the name of the bug I am fixing.

The Window Menu

Resizing panes
Cascading & minimizing windows
Opening and closing the log window
Toggling the active pane and the orientation of the Leo window

Resizing panes

The relative sizes of the outline and body pane can be changed by dragging the area between the two panes. The Equal Sized Panes command adjusts the sizes of the code and body pane of the topmost window so that they are the same height.

Cascading & minimizing windows

The Cascade command cleans up the screen by cascading all Leo windows. The Minimize All command minimizes all Leo windows.

Toggling the active pane and the orientation of the Leo window

The Toggle Active Pane command changes the pane that is currently active. If the outline pane was active, the body pane becomes active, and vice versa. This command makes it possible to switch between panes without using the mouse.

New in leo.py 3.0, Toggle Split Direction: This 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.

leoConfig.txt specifies the default direction. If leoConfig.txt does not exist, or does not specify the direction, the "vertical" orientation is used, just as in previous versions.

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 leoConfig.txt.

The Help Menu

Getting Leo's version

The About Leo command puts up a dialog box showing the version of Leo.

Reading documentation

The Online Home Page command opens Leo's home page at http://personalpages.tds.net/~edream/front.html.

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 in the folder containing leo.py. If sbooks.chm does not exist, you will be asked whether you want to download it from Leo's SourceForge web site. If you say yes, the page will open. You should then download sbooks.chm to the folder containing leo.py.

The Open LeoDocs.leo command opens the file leoDocs.leo.

Configuring Leo

The Open LeoConfig.leo command opens the file leoConfig.leo, the primary source file for the derived file leoConfig.txt. Use the Tangle All command to update leoConfig.txt from changes made to leoConfig.leo.

The Apply Settings command applies the settings in leoConfig.txt. Leo reads these settings when it begins execution, so the only time you would need to use this command is just after changing leoConfig.txt.