Here is the first draft for a proper introduction the Leo's rST
capabilities.
I think the story orientation helped a lot.
Comments please
reStructuredText_ (rST) is a popular markup language for
writing documents. rST is simple, yet powerful. All of Leo's
documentation is written in rST, and then processed via the
docutils_ and Sphinx_ processors to produce Leo's web pages.
Leo makes writing rST documents easier. A *lot* easier.
There are several reasons for this.
1. Leo outlines help organize rST source code in all the
usual ways. You always clearly see the structure of even
book-length documents. You can rearrange and reorganize
chapters, sections and paragraphs effortlessly. You can use
clones to create multiple views of your writing for yourself
and your readers. These capabilities, all by themselves,
would make Leo an excellent choice for editing rST
documents.
2. Leo fixes the clumsiest part of rST markup, namely the
markup for headings. Without Leo, you must underline heading
lines manually. The underlining character indicates the
level of a heading. Changing the level of a heading is
clumsy and error prone: you must change the underlining
character properly. Changing the level of several headings
is a headache.
Leo gets rid of all this bother. Within an outline that gets
written to an external rST file, Leo's headlines become
section headings. When writing external rST files, **Leo
generates underlining for headers automatically** based on
the outline level of the outline nodes. When you rearrange
your outline Leo will recompute the rST markup needed to
recreate the outline structure in the external rST file. In
most cases, you won't even see the rST markup for headings!
3. Leo allows you to import existing into Leo outlines so
that the structure implied by the headings in the rST file
is reflected in the imported Leo outline. The file you would
get by writing the resulting outline will be equivalent to
the original file. This is called **rST round-tripping**.
Leo outlines preserve the structure and content of the
original rST files. Because of rST round tripping, you can
easily use Leo modify other people's rST files.
Note: there may be *minor* variations the first time you
import an existing rST file, but these differences will not
affect the meaning of the rST file. After the first import,
the only changes when writing the imported rST file will be
changes *you* make.
The three features just discussed (Leo's organizational
capabilities, automatic generation of markup for rST
headings, and rST round-tripping) are useful for anyone
using reStructuredText. In addition Leo provides additional
capabilities for power users:
4. So far, we have implied that the outlines that Leo writes
to external rST files contain nothing but text and rST
markup. That's not the whole story. Nodes can contain
options (in either headline and body text) that change the
way that Leo writes to the external rST file. We'll discuss
these options in detail later, but here are a few examples.
- A headline that starts with @rst-no-head does not create
an rST heading.
- Body text that starts with::
@rst-option code_mode = True
causes the body text of the node to be displayed as an rST
code block.
There are many other options. The take-away message is that
Leo allows you to change, on a node-by-node basis, how Leo
will generate rST markup for each node. The various rST
options provide an almost bewildering array of possibilities
for formatting text. And there are more such options pending.
5. The rST options just discussed will suffice to create
just about any kind of rST output. But for those desiring
the ultimate in flexibility, it is relatively
straightforward to create Leo outlines or external files
using scripts. For example, you might want to write a script
to format source code to rST markup. A script can give you
complete control over such formatting. This chapter
concludes by telling you how to write such scripts.
Edward
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/leo-editor?hl=en
-~----------~----~----~----~------~----~------~--~---
