*allout.txt* Handling Allout files ALLOUT EDITING IN VIM François Pinard pinard@iro.umontreal.ca Allout files are a handy synoptic (or tree-like) representation of a document. Such files were originally introduced as a GNU Emacs mode. Vim offers tools and help for browsing or editing these Allout files. 1. Allout concepts |allout-concepts| 2. File format |allout-files| 3. Activation |allout-activation| 4. Navigation |allout-navigation| 5. Folding |allout-folding| 6. Topics |allout-topics| 7. Levels and margins |allout-levels| 8. Similar tools |allout-references| The `allout-vim' package may be downloaded from: http://fp-etc.progiciels-bpi.ca/allout-vim/ while installation directives may be found at: http://fp-etc.progiciels-bpi.ca/allout-vim/README This file you are reading is also available on the Web as: http://fp-etc.progiciels-bpi.ca/allout-vim/doc.txt While syntax colouring of Allout files should work in almost any Vim, Allout specific commands and mappings require a Python-enabled Vim. ============================================================================== 1. Allout concepts *allout-concepts* A document may be structured as a tree of nodes. A book may be made up of chapters, then sections and sub-sections, presenting a sequence of ideas, themselves holding paragraphs, then sentences, etc. A node corresponds to a chapter, section, sub-section, idea, etc. A node bears a topic, an optional textual contents, and optional sub-nodes. The topic is a one-line description of the overall contents of the node (so, there is never a newline within a topic). The text is the actual verbose documentation for that node, and if present, it is a sequence of one or more complete lines, possibly running over many paragraphs. When a node has sub-nodes, its textual contents should be seen either as some documentation specific to this node, as an introductory text for all the sub-nodes, or both. The level of a node expresses how far it is from the root of the documentation tree. The root itself is said to be at level 0, while other nodes use higher integral numbers. The root node is not the sub-node of any other node. Every other node is necessarily the sub-node of one and only one node at some lesser level. (This might be where Leo shines. The idea of cloning nodes so that the same text can reside in two different sub-trees and the cloned nodes texts stay in sync automatically.) Each topic, besides root, is qualifed through the use of a "bullet": a character chosen from a limited set. There are four kind of bullets: fixed, floating, numbered or link. Any bullet may be used at any node level, save for the rule that nodes at level 1 are required to use the `*' bullet. Fixed bullets are `*', `+' and `-'. Floating bullets are such that each level has its own floating preference: level 2 prefers `.', level 3 prefers `:', level 4 prefers `,', level 5 prefers `;', and the cycle repeats afterwards, so level 5 prefers `.', level 6 prefers ':', etc. A numbered bullet uses more than one character: it is `#' immediately followed by a number. The only link bullet is `@', it is meant to represent a reference to some other document. ============================================================================== 2. File format *allout-files* An Allout file is a sequential representation of an Allout documentation tree. The file lists all nodes, one after another, in depth-first order; that is, when a node contains many sub-nodes, the first sub-node is fully and recursively listed but, only then the second sub-node is fully and recurively listed, etc. Do not worry if you are not very familiar with formal tree wanderings, you'll soon find out that this is the most natural and easy way to represent a documentation tree. Each node is exposed as a mandatory topic line immediately followed by all of its textual contents, if any. The root node is a bit special, as if it has no textual contents, it may be without a topic line. As a slight abuse of language, whenever we use the word `topic' in the remainder of this documentation, we usually mean the whole topic line. And whenever we use the word `text', we usually mean the textual contents. For example, we could rephrase the first sentence of the previous paragraph by saying that each node is exposed as a required topic followed by optional text. A topic holds, from left to right, a prefix yielding information about the node level, the node bullet, a space, and the topic description. If the node has no topic description, the space preceding it is usually omitted. The prefix is the empty string for nodes at level 0 or 1, the string `.' at level 2, the string `. ' at level 3, and so on, adding one more space for each supplementary level. In this way, the relative horizontal position of bullets in successive topics gives good visual clues for comparing node levels, and identifying sub-node membership. The text is a sequence of lines, none of which is allowed to look like a topic line. There is no danger if all textual lines have a non-empty left margin. A handy and nice-looking convention, yet not a mandatory one, is to use `L+1' as the width of left margin while listing the text of a node at level `L'. Some people prefer sticking all the text to the left, and merely avoid starting any line with `*' or `.'. Note that if the first line of an Allout file is a topic line of level 1 or more, the root node is empty. Otherwise, the whole first line holds the topic description for the root node, and all following lines until another topic, if such lines exists, are the text of the root node. ============================================================================== 3. Activation *allout-activation* Allout mode is activated whenever the |'filetype'| option is set to the value `allout'. This may be achieved automatically for files having `.all' as an extension by the following commands: > :augroup filetypedetect : autocmd! BufNewFile,BufRead *.all setfiletype allout :augroup END < You might also want to activate syntax colouring, see |:syntax|. All Allout commands start with the ||, which is `\' if the user did not change it. We use this default leader in all examples of mapping, below. ============================================================================== 4. Navigation *allout-navigation* Allout editing adds a few navigation to all those Vim already has for wandering around in any buffer, and to those commands specialized for moving over folds in particular. Mapping equivalences: \j Allout_next_visible_topic \J Allout_last_visible_topic \k Allout_previous_visible_topic \K Allout_first_visible_topic \l Allout_next_sibling \L Allout_last_sibling \h Allout_previous_sibling \H Allout_first_sibling \u Allout_up_level \1 Allout_down_to_1st_child \2 Allout_down_to_2nd_child \3 Allout_down_to_3rd_child \4 Allout_down_to_4th_child \5 Allout_down_to_5th_child \6 Allout_down_to_6th_child \7 Allout_down_to_7th_child \8 Allout_down_to_8th_child \9 Allout_down_to_9th_child \^ Allout_beginning_of_text \$ Allout_end_of_text \v Allout_view_text \V Allout_view_level Commands "\j" and "\k" jump the cursor forward or backwards from topic to topic, regardless of the level of each topic. Commands "\J" and "\K" jump the cursor to the last or the first topic for the whole file. Commands "\l" and "\h" jump the cursor forward or backwards from topic to topic while keeping the same topic level, and only within sibling topics. Commands "\L" and "\H" jump the cursor on the last or the first sibling for all current siblings. All the above commands skip over closed folds. Commands "\u" (up) jumps the cursor back to the topic for which the current topic is a sub-topic. Commands "\1", "\2", etc. to "\9" go down to the first, second, etc. to ninth sub-topic of the current one. Commands "\^" and "\$" jump the cursor on the first or last line of the whole text for the current topic, yet excluding white lines. Command "\v" and "\V" both activates Visual line mode, "\v" for the text of the current node, "\V" for the whole sub-tree starting from the current node. ============================================================================== 5. Folding *allout-folding* Vim already has many facilities for folding a buffer, and Allout builds on them. First make sure you are already familiar with the folding concept by reading |usr_28.txt|. The few Allout specific commands for folding, described here, may suffice in practice for most needs. Mapping equivalences: \c Allout_hide_text \C Allout_hide_level \o Allout_show_text \O Allout_show_level \i Allout_show_children Command "\c" hides (closes) the current node text, yet the topic remains visible; while "\o" reveals (opens) that text. Command "\C" hides the sub-tree starting from the current node, yet the topic of the node stays visible; while "\O" fully reveals that sub-tree. Command "\i" hides the sub-tree starting from the current node, yet the current topic, as well as all immediate sub-topics, stay visible. Beware that a run of lines must contain two lines or more for being hidden. To deepen folding matters, peek at the |Folding| reference. Here are a few considerations which apply if you want to use normal Vim folding commands over an Allout buffer. The folding method uses an expression to define folds, so you may not create or delete folds on your own: you may only open or close existing folds. The fold level of topics is exactly their Allout level, but all texts use the same high value for a level. This choice for text has two nice effects: first is that any text is strongly _tied_ to the topic before any sub-topics; second is that it is possible to close the fold represented by text leaving sub-topics opened. ============================================================================== 6. Topics *allout-topics* A few commands help at creating nodes by inserting new topics, deleting them, and adjusting their bullets. Mapping equivalences: \= Allout_create_sibling \+ Allout_create_subtopic \- Allout_create_supertopic \d Allout_delete_text \D Allout_delete_level \ Allout_rebullet_topic \# Allout_number_siblings \~ Allout_revoke_numbering Commands "\=", "\+" and "\-" all create a new topic textually after the current text. However, they differ in how the level of the new topic is decided. While command "\=" reuses the current level (creating a sibling), command "\+" increases it by one (so creating a first child), and command "\-" decreases it by one (so creating an uncle). The bullet of the created topic is deduced from the bullet used in the topic for the previous sibling for the new node, if any (that is, the preceding topic at the level of the created topic). The cursor is left positioned on the newly created topic, as the user is likely to edit it right away. Command "\D" deletes the whole sub-tree starting from the current node, so it may indeed delete many topics at once, including their texts. Command "\d" only deletes the text of the current node. Command "\" command repairs a floating bullet in the topic for the current level, if it is not the preferred one at that level. Command "\#" changes all bullets for immediate sub-topics of the current node so they become numbered bullets, with the numeric value select so they effectively count sub-topics. Command "\~" turns all numbered bullets to floating bullets, for immediate sub-topics of the current node. ============================================================================== 7. Levels and margins *allout-levels* Many commands adjust or modify existing nodes in various ways. They allow for changing the level of a sub-tree, or slightly modifying either the topic or the text of a node. In Visual mode, all commands from this section alter their normal behaviour and work on highlighted lines only. Mapping equivalences: \| Allout_adjust_margin \0 Allout_remove_margin \> Allout_shift_in \< Allout_shift_out \_ Allout_space_topic Command "\|" works on the text of the current node, rigidly shifting it left or right so the common left margin merely frees the bullet of the above topic. Command "\0" (that's a zero) rigidly shift the text of the current node left so the common left margin becomes null. Commands "\>" and "\<" act on the whole sub-tree rooted at the current node, and textually shift that sub-tree right or left. While shifting in a level-1 tree, its bullet is considered floating despite it was `*' to start with. When shifting out a level-1 tree, the topic bullet is lost, both the topic and text are added to the text for the level-0 root. Command "\_" forces a white line before the topic. ============================================================================== 8. Similar tools *allout-references* Allout files handily represent a documentation tree and are best handled with fold editing. There are other such tools. Most use their own format, formats have their own tools, so we do not try to precisely distinguish between tools and formats here. This section is meant to list a few of them. Suggestions for additions are welcome. Emacs Outline Outline mode is standard in Emacs, as a minor mode that can be activated over any major mode. It predates Allout, and let the user specify a regular expression for matching topic lines. The textual length of the match indicates the level of the represented node. Emacs Allout Allout mode is also standard in Emacs, and while the topic format is more rigid, the command set is extended. If one preloads the `allout' module in Emacs, later activatiion of the Outline mode is intercepted and activates Allout mode instead. I would like that Allout files stay inter-operable between Vim and Emacs. However, the command set does not try to be the same: key bindings were adapted for being more natural to Vim users, and similar commands may behave a bit differently. TVO - The Vim Outliner TVO is quite similar to Allout and predates it, yet it uses a different file format, and has a different, likely richer set of facilities and commands. Some commands should be familiar to users of the Outline features of Microsoft Word. For TVO, see: http://vim.sourceforge.net/scripts/script.php?script_id=517 I did not know this tool existed before I wrote Allout-Vim. But I now see that there are many good ideas to be stolen from TVO! :-) Leo Leo is a self-contained folding editor written in Python and using a Tk editor. It is much more powerful than Allout, yet slower and more complex. It can be made to use Vim instead of Tk as an editor. vim:tw=78:ts=8:ft=help:norl: