.. @+leo-ver=5-thin
.. @+node:ekr.20100805001344.7253: * @file directives.txt
.. @@language rest
.. @@tabwidth -4

.. @+at @rst-options
..  call_docutils=False
..  code_mode=False
..  generate_rst=True
..  http_server_support = False
..  show_organizer_nodes=True
..  show_headlines=True
..  show_leo_directives=True
..  stylesheet_path=..\doc
..  write_intermediate_file = True
..  verbose=True
.. @@c

.. @+all
.. @+node:ekr.20050828061213: ** @rst html/directives.html
###############
Leo's Reference
###############

This chapter is a reference for all of Leo's directives.

This chapter does *not* teach how to use Leo. It assumes you are *thoroughly*
familiar with `Leo's tutorial`_.

.. contents::
    :depth: 5

.. @+node:ekr.20050828160132: *3* @rst-no-head links
.. Links to other chapters
.. _front:                      front.html
.. _`Leo's tutorial`:           intro.html
.. _`Leo and reStructuredText`: rstplugin3.html
.. _`History of Leo`:           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
.. @+node:ekr.20100806170836.4392: *3* Part 1: \@<file> directives
.. index::
    pair: @<file>; Reference

This section discusses the \@<file> 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         | yes: note 3      | 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.

**Note 3**: Outline structure created in \@edit nodes is not saved in the
external file.

Within @path and @<file> 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.

.. @+node:ekr.20100806170836.4393: *4* \@asis <path>
.. 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.
.. @+node:ekr.20100806170836.4396: *4* \@auto <path>
.. 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.
.. @+node:ekr.20100806170836.4395: *4* \@edit <path>
.. 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, Leo writes expands section references, \@all and
\@others just as with \@file trees. However, Leo writes no sentinels, so the
structure created by sections references, \@all and \@others is not preserved.
.. @+node:ekr.20100806170836.4403: *4* \@file <path> (aka @thin)
.. 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.
.. @+node:ekr.20100806170836.4399: *4* \@nosent <path>
.. index::
    pair: @nosent; Reference

The \@nosent <filename> 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.
.. @+node:ekr.20100806170836.4402: *4* \@shadow <path>
.. 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.
.. @+node:ekr.20100806170836.4411: *3* Part 2: \@all and \@others
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.
.. @+node:ekr.20100806170836.4398: *3* Part 3: Syntax coloring directives
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.
.. @+node:ekr.20100806170836.4408: *3* Part 4: Dangerous directives
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 <1, 2 or three comment delims>

    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 <1 or 2 comment delims>

    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 <-- -->
        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.
.. @+node:ekr.20100804133903.7262: *3* Part 5: All other directives
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 <encoding>

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

    Places lines at the very start of an external file, before any Leo
    sentinels. \@first lines must be the very first lines in an \@<file> 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 @<file> 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 <language name>

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

    Places lines at the very end of external files.

    This directive must occur at the very end of top-level \@<file> nodes. More
    than one \@last directive may exist. For example::

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

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

   Sets the page width used to break doc parts into lines.
   <n> 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 <path>

   Sets the **path prefix** for relative filenames for all \@<file> tree.

   This directive may appear in headlines or body text, and may
   appear in top-level \@<file> 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 @<file> 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 <n>

  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.
.. @-all
.. @-leo
