ossp-pkg/sugar/sugar.txt
Sugar -- The Markup Language With Invisible Syntactic Sugar
===========================================================
Ralf S. Engelschall <rse@engelschall.com>,&{br}
Christian Reiber <chrei@en.muc.de>
++ | Genesis: | 12-Mar-1999 |
| Last Update: | 08-Nov-2000 |
Introduction
------------
Sugar is a markup language and corresponding translator tool for
writing technical documentation that uses mostly invisible markup
tags (the so-called //syntactic sugar// in compiler construction folk
terminology).
The general idea is that the markup text looks already like the
textual output of the translator phase, that is, the Sugar source
can be already treated as its text output format ("ASCII WYSIWYG").
Additionally the Sugar markup language is considered intuitive enough
to be recognized easily, so writing technical documentation is mainly
just a matter of performing a brain dump.
So Sugars syntactic principle is "keep it simple'n'stupid" (KISS)
but still powerful enough to allow one to produce high-quality
output. Sugars goal is not to provide all features of a full featured
documentation system. Instead it provides only a few markup concepts
but those are streched to a maximum.
Sugar Grammar
-------------
A Sugar document is described by the following grammar:
++ | | | |
| <document> | ::= | <block>* |
| <block> | ::= | <tagged-block> \| <regular-block> |
| <tagged-block> | ::= | <1d-block> \| <2d-block> |
| <1d-block> | ::= | <1d-tag> <document> |
| <2d-block> | ::= | <2d-tag> <document> |
| <1d-tag> | ::= | "!!##!!" \| "!!\|\!!|" \| "!!``!!" \| "!!''!!" \| ... |
| <2d-tag> | ::= | "!!**!!" \| ... |
where <regular-block> is defined visually as a rectangular block
of continued text inside the document, that is a paragraph of
text (without any blank lines) where each line starts at the same
indentation position.
Markup Language
---------------
The Sugar markup language consists of markup tags grouped into a few
classes:
o ..Visual Formatting:..
For visual formatting of text the following <1d-tag> exists. They
can be used either inlined in a paragraph by using them twice (to
delimit begin and end) or for marking up a whole block by using them
in marched-out way (to delimit indented block).
++ | tag | formatting | application |
| !!__!! | underline | inline, block |
| !!**!! | bold | inline, block |
| !!//!! | italics | inline, block |
| !!''!! | code | inline, block |
| !!>>!! | indented | block |
| !!==!! | paragraph header | block |
| !!\!\!!! | verbatim | inline, block (charblock only until EOL) |
| !![[!! | boxed | inline, block |
| !!%%!! | centered | block |
| !!))!! | right flushed | block |
| !!((!! | left flushed | block |
Example:
!! This line contains //italics// and **bold** words.
>> '' And this paragraph contains
indented verbatim code.
And this line again is __non-indented__ text.
o ..Links and References:..
For referencing textual locations (both document internal and to
external documents), links can be specified.
++ | construct | description |
| !!->!![//text//]!!(!!//scheme//!!:!!//path//!!)!! |
external hyperlink via URL |
| !!->!!//text//!!(!!//ref//!!)!! |
internal hyperlink via anchor-name |
| !!(+!!//ref//!!+)!! |
internal anchor definition |
Example:
!! Header A (+hA+)
--------
This is text of header A. For B see ->header B(hB).
For Sugar go to ->(http://www.ossp.org/pkg/sugar/).
Header B (+hB)
--------
This is text of header B. For A see ->header A(hA).
For other neat things watch ->OSSP(http://www.ossp.org/).
o ..Headers:..
Up to four levels of headlines can be marked up by placing the
following character sequences (or any number of concatenated
repetitions of them) at the end of a text block:
++ | sequence | level |
| !!==!! | I. |
| !!--!! | II. |
| !!~~!! | III. |
| !!..!! | IV. |
Example:
!! A header line
=============
o ..List Environments:..
Three types of list environments can be used. They are identified
by the first non-blank word in the first line of each list item.
For ordered lists the start position is selectable by specifying an
explicit digit instead of the generic item character.
++ | construct | alternatives | type |
| !!-!! | !!o!!, !!*!! | unordered |
| !!-.!! | !!o.!!, !!*.!!, m/[0-9]+\./ | ordered |
| <block> !!::!! | | itemized |
Example:
!! A Sugar list:
1. foo
o. bar
- baz
- foobar
o. quux
o ..Table Environment:..
A generic table environment is provided for any type of data which
has to be rendered in a tabular layout. A table is a <2d-block>
starting with a !!++!! tag.
The contents of the <2d-block> consists of a 2-dimensional table
specified by cells. The table cells are seperated by ''|''
characters. Every row has to start with a ''|'' at the same
horizontal position. The number of columns is indicated by the
first table row. This first row can be either a complete (all cells
are specified) and regular (the contents is used) row, or (in case
the first //regular// row is not a complete one, that is, it has
multi-column cell spans), the first row can be an empty row (all
cells are specified for indication but are left blank).
The ''|'' marks can be placed arbitrary in each row, but if
multi-column spans exists, the surrounding ''|'' marks have to be
placed exactly at the same horizontal character position as the
first table row has (else the multi-column cells are ambiguous).
Empty rows can be indicated by using just the starting ''|'' mark.
Example:
!!
++ | | | |
| foo | !!bar | quux |
|
| foo | baz
bar | quux |
| bazfoo
fjfjkwq
rwrqwd sddksjk
| dsdjks
| foo |
| dsdsds |
____
o ..Special Formatting:..
'' quotemeta
## command (charblock until EOL)
`` shell command (charblock until EOL)
o ..Escaping and Special Characters:..
-- em-dash (ger. "Gedankenstrich")
\_ strong blank (prevents line break as in HTML's )
\n line break (as in HTML's <br>)
\\ a backslash (there no block concept!)
\X escapes following character X
\{name}
o Commands (all charblock until EOL):
##! <shebang>
##include
##// line comment
##/* block comment anfang
##*/ block comment ende
##if
##elsif
##endif
##img ...
##<formatierung> [range]
Sugar Output Formatting
-----------------------
The Sugar transformation tool parses a Sugar source text, transforms
it into an internal abstracted syntax tree and finally applies to it a
particular output formatting module in order to transform the abstract
syntax tree into target markup language. The target language then is
either already an end-user document (HTML, Text, etc.) or intended for
post-processing by external programs (LaTeX, PDF, etc.).
The following outputs are supported:
++ | sugar output | post-processor(s) | final output |
| Text | - | Text |
| HTML | - | HTML |
| Roff | nroff | Text |
| Lout | lout | Postscript |
| PDF | pdflib | PDF |
| LaTeX | latex, dvips | DVI, Postscript, PDF |
| XML | docbook | ... |
| POD | pod2xxx | ... |
