.. rst3: filename: html/glossary.html

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

.. |br| raw:: html

   <br />

.. 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`` or ``@code``
    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``, ``@auto``, ``@clean``,
    ``@edit``, ``@file``, ``@shadow``, ``@thin``.
    
    We often refer to outline nodes by the directives they contain. For
    example, an ``@file`` node is a node whose headline starts with
    ``@file``.

.. 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
    nodes if an importer exists for the give filetype.

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

.. index::
    pair: ``@first``; Glossary

``@first <text>``
    This directive inserts a line 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**: Within any ``@<file>`` node, any line containing matched
    ``<<`` and ``>>`` characters is a section reference. 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/LeoPyRef.leo``
    
    This file should change only when adding new external files to Leo.
    Developers should use a local copy of LeoPyRef.leo (usually called
    ``leoPy.leo``) for their own work.

.. index::
    pair: reStructuredText; Glossary
    pair: rST; Glossary

.. _`rST primer`: https://docutils.sourceforge.net/docs/user/rst/quickstart.html


reStructuredText (rST)
    A 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 between ``<<`` and ``>>``. Section names may contain any character
    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

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