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

    @first # -*- coding: utf-8 -*-
    '''whatever.py'''
    << imports >>
    @others
    # That's all, folks
    @language python
    @tabwidth -4
    
A child node must define the << import >> node. Other children will typically define classes, methods, functions and data.

When writing this file, Leo writes the first two lines::

    @first # -*- coding: utf-8 -*-
    '''whatever.py'''
    
followed by the *body text* of the << imports>> node, followed by the body text of all *other* nodes, in outline order, followed by the comment *# That's all, folks*.

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

    '''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.
See `this FAQ entry <FAQ.html#what-about-code-that-looks-like-a-section-reference>`_.

