.. rst3: filename: html/glossary.html

#########
Glossary
#########

.. Links
.. _`Customizing Leo`:              customizing.html
.. _`git repository`:               https://github.com/leo-editor/leo-editor
.. _`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:

.. contents:: Contents
    :depth: 2
    :local:

\@
++++

.. 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: @<file> node; Glossary

\@<file> node
    A node whose headline starts with @asis, @clean, @edit, @file, @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 <filename>
    Creates an external file containing no Leo sentinels directly from the @asis tree.

.. index::
    pair: @auto; Glossary

\@auto <filename>

    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

\@chapter

    An @chapter tree represents a chapter.

.. index::
    pair: @color; Glossary
    
.. index::
    pair: @clean; Glossary

\@clean

    Creates an external file without sentinels. Section references and the @all and @others directives are valid in @clean trees.

\@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 <filename>

    Reads an entire external file into a single node.

.. index::
    pair: @encoding; Glossary

\@encoding <encoding>

    Specifies the Unicode encoding for an external file.

.. index::
    pair: @file; Glossary

\@file <filename>

    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 <text>

    The @first directive allows you to place one or more lines at the *very start* of an external file, before the first sentinel. The @first directive must appear at the *very start* of body text. 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 <language name>

    Specifies the source language, which affects syntax coloring and the comments delimiters used in external files and syntax coloring.

.. index::
    pair: @last; Glossary

\@last <text>

    Allows you to place lines at the very end of external files, after the last sentinel. This directive must appear at the *very end* of body text. For example::

        @first <?php
        ...
        @last ?>

.. 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 external files without sentinels. Unlike @clean, @nosent trees
    are never updated from from external files.

.. 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 <n>

   Sets the page width used by the reformat-paragraph command.
   This directive also controls how @doc parts are broken into lines.

..  .. index::
    ..  pair: \@path; Glossary

@path <path>

  Sets the path prefix for relative filenames for descendant \@<file> directives.

.. index::
    pair: @tabwidth; Glossary

\@tabwidth <n>

    Sets the width of tabs. Negative tab widths cause Leo to convert tabs to
    spaces.

.. index::
    pair: @thin; Glossary

\@thin <filename>

    A synonym for @file.

.. index::
    pair: @wrap; Glossary

\@wrap

    Enables line wrapping in Leo's body pane.

A - C
+++++

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

D - G
+++++

.. 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: Dirty Node; Glossary

Dirty Node

    A node whose headline or body text has changed.

.. 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`: https://www.cs.tufts.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 <\< and >\> is a section
    reference, regardless of context. To use <\< and >\> 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 @<file> node.

.. index::
    pair: gnx; Glossary
    pair: Global Node Index; Glossary
    
.. _`format of external files`: appendices.html#format-of-external-files
    
Gnx (Global Node Index)

    A unique, immutable string permanently associated with each vnode.
    See `format of external files`_.

.. index::
    pair: Grandchild; Glossary

Grandchild

    The child of a child of a node.

H - L
+++++

.. 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 & 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.

M - O
+++++

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

P - R
+++++

.. 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: FAQ; Glossary

Reference .leo file

`leoeditor/leo/core` contains a **reference .leo file**: **LeoPyRef.leo**.
This file should change only when adding new external files to Leo.
Developers should use a local copy of LeoPyRef.leo (conventionally called
**leoPy.leo**) for their own work.


.. 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 @<file> tree.

S - Z
+++++

.. 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 <\< and >\>. Section names may contain any characters
    except newlines and ">>".

.. 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
    pair: Sentinel Lines; 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: uA; Glossary

.. _`extensible attributes`: customizing.html#adding-extensible-attributes-to-nodes-and-leo-files
    
uA
    
    uA's (User Attributes) are persistent Python dicts that allows scripts
    and plugins to associate additional data with each node. See
    `extensible attributes`_.

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

