[Python-Dev] The impact of '@' on Leo

[Edward K. Ream]

> > The major concern I have with '@' syntax as it relates to Leo is the
> > potential for ongoing and never-ending conflicts between Leo's
directives
> > and @x constructs in Python.
>
> Can you give an example of a file that would be difficult to understand
> under that change? If you allow @foo inside a Python file, it is not
> Python anymore, is it?

There are two files involved.  The .leo file (an xml file) contains the
"marked up" code.  Leo turns this file into a visual outline containing zero
or more "derived files" that could be written in any language.

Here is the entire top-level node in the outline that represents the derived
file leoApp.py:

[Node starts]

@first # -*- coding: utf-8 -*-

@language python
@tabwidth -4

import leoGlobals as g
import os
import sys

class LeoApp:

    """A class representing the Leo application itself.

    Ivars of this class are Leo's global variables."""

    @others

[Node ends]

- The [Node starts] and [Node ends] are _not_ part of the node, they delimit
the node in this email.
- The @first directive makes sure that the first line of leoApp.py is # -*-
coding: utf-8 -*-
- The @language python and @tabwidth directives tell Leo how to syntax color
the text and how to handle tabs.
- The @others directive tells Leo to insert all descendent nodes.  In this
case, each descendent node contains a single method of the LeoApp class.
- There are other details to Leo's markup, but this gives you the general
feel.

Everything else is plain Python.  When saving the .leo file, Leo produces
leoApp.py following the rules of the markup.  In particular, Leo writes all
descendent nodes in place of the @others directive, indented the same as the
@others directive.  Most of these descendent nodes will contain few or no
Leo directives: descendent nodes inherit most directives from their
ancestors.

The problem is that Leo doesn't really understand _any_ language, except to
colorize it.  Most Leo directives must start with @ in the leftmost column,
but the @others and @all directives may contain leading whitespace.  If @foo
is both a valid Python construct and a valid Leo directive Leo will treat
@foo as a Leo directive even if it is "supposed" to be Python.

If @foo is not a valid Leo directive, Leo creates a "verbatim" sentinel line
in the derived file to indicate that the next line isn't a directive, even
though it sorta looks like one.  Like this:

#@verbatim
@foo

This is basically how Leo handle's languages with @ signs.  There is no
problem until @x in the language conflicts with a Leo directive, in which
case Leo doesn't have any way of distinguishing which usage was intended.

As I said in another post, Leo doesn't have escape conventions involving @
signs, and that has turned out well.  There have been requests to allow
strings other than "@" to delimit Leo directives, and that will probably
happen, but in general Leo really would rather stick to "@"

Edward
--------------------------------------------------------------------
Edward K. Ream   email:  edreamleo at charter.net
Leo: Literate Editor with Outlines
Leo: http://webpages.charter.net/edreamleo/front.html
--------------------------------------------------------------------