Format of External Files

This section describe the format of external files. Leo's sentinel lines are comments, and this section describes those comments.

External files created by @file use gnx's in @+node sentinels. Such gnx's permanently and uniquely identify nodes. Gnx's have the form:

    id.yyyymmddhhmmss
    id.yyyymmddhhmmss.n

The second form is used if two gnx's would otherwise be identical.

id is a string unique to a developer, e.g., a git id.
yyyymmddhhmmss is the node's creation date.
n is an integer.

Closing sentinels are required for section references and the @all and @others directives, collectively known as embedding constructs. Proof: These constructs do not terminate the node in which they appear. Without a closing sentinel there would be no way to know where the construct ended and the following lines of the enclosing node began.

New sentinels do not include @nonl or @nl. As a result, body text always ends with at least one newline.

Here are the sentinels used by Leo, in alphabetical order. Unless otherwise noted, the documentation applies to all versions of Leo. In the following discussion, gnx denotes a gnx as described above.

@<<

A sentinel of the form @<<section_name>> represents a section reference.

If the reference does not end the line, the sentinel line ending the expansion is followed by the remainder of the reference line. This allows the Read code to recreate the reference line exactly.
@@

The @@ sentinel represents any line starting with @ in body text except @whitespace, @doc and @others. Examples:
```
@@nocolor
@@pagewidth 80
@@tabwidth 4
@@code
```
@afterref

Marks non-whitespace text appearing after a section references. As of Leo 6.6, Leo no longer writes afterref sentinels. However, Leo will always read such sentinels correctly.
@+all

Marks the start of text generated by the @all directive.
@-all

Marks the end of text generated by the @all directive.
@at and @doc

The @+doc @+at sentinels indicate the start of a doc parts.
@+body (Leo 3.x only)

Marks the start of body text.
@-body (Leo 3.x only)

Marks the end of body text.
@delims

The @delims directive inserts @@delims sentinels into the external file. The new delimiter strings continue in effect until the next @@delims sentinel in the external file or until the end of the external file. Adding, deleting or changing @@delim sentinels will destroy Leo's ability to read the external file. Mistakes in using the @delims directives have no effect on Leo, though such mistakes will thoroughly mess up a external file as far as compilers, HTML renderers, etc. are concerned.
@section-delims (Leo 6.6+)

The @section-delims directive inserts @@section-delims sentinels into the external file. The directive must appear in the root @<file> node.
@+leo

Marks the start of any external file. This sentinel has the form:
```
<opening_delim>@leo<closing_delim>
```
The read code uses single-line comments if <closing_delim> is empty. The write code generates single-line comments if possible.

The @+leo sentinel contains other information. For example:
```
<opening_delim>@leo-ver=4-thin<closing_delim>
```
@-leo

Marks the end of the Leo file. Nothing but whitespace should follow this directive.
@+node

Mark the start and end of a node:
```
@+node:gnx:<headline>
```
@nonl (Leo 3.x only)

Suppresses a newline in the outline.
@others

The @+others sentinel indicates the start of the expansion of an @+others
directive, which continues until the matching @-others sentinel.
@verbatim

@verbatim indicates that the next line of the external file is not a sentinel. This escape convention allows body text to contain lines that would otherwise be considered sentinel lines.