.. rst3: filename: html/leomarkup.html

#####################
Leo's Markup Language
#####################

.. index::
    pair: Markup; Reference
    pair: Section Reference; Reference
    pair: @others; Reference

Leo's **markup** tells Leo how to create external files from ``@file`` trees. Markup may appear in any body text, and *must* appear in the body of the ``@file`` node itself.

There are two kinds of markup: **section references** (``<< this is my section >>``) and the **@others** directive. Section references refer to **named nodes**, nodes whose *headlines* look like a section reference. ``@others`` refers to all *other* (unnamed) nodes. Here is the body text of a typical ``@file`` node for a python file:

.. code-block:: python

    """A docstring"""
    << imports >>
    @others
    if __name__ == '__main__':
        main()
    @language python
    @tabwidth -4

A child node must define the ``<< imports >>`` node. Other children will typically define classes, methods, functions and data.

When writing this file, Leo writes:

- The docstring.
- The *body text* of the ``<< imports>>`` node.
- The body text of all *other* nodes, in outline order.
- The lines after the ``@others`` directive.

Leo's markup applies to scripts as well as external files. Leo's ``execute-script`` command **composes** the script from the selected node, using Leo's markup. For example: this body text defines the top-level part of a script:

.. code-block:: python

    """My script"""
    << imports >>
    class Controller:
        # Child nodes define the methods of this class.
        @others
    Controller(c).run # c *is* defined.

**Important**: Leo recognizes section references *everywhere*, even inside strings or comments.

*Note*: Section names are case insensitive and blanks are ignored within section names.
The following sections are equivalent:

.. code-block:: python

    << a section >>
    << A Section >>
    <<a s e c t i o n>>