Sugar -- The Markup Language With Invisible Syntactic Sugar =========================================================== Ralf S. Engelschall ,&{br} Christian Reiber ++ | 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: ++ | | | | | | ::= | * | | | ::= | \| | | | ::= | <1d-block> \| <2d-block> | | <1d-block> | ::= | <1d-tag> | | <2d-block> | ::= | <2d-tag> | | <1d-tag> | ::= | "!!##!!" \| "!!\|\!!|" \| "!!``!!" \| "!!''!!" \| ... | | <2d-tag> | ::= | "!!**!!" \| ... | where 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 | | !!::!! | | 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
) \\ a backslash (there no block concept!) \X escapes following character X \{name} o Commands (all charblock until EOL): ##! ##include ##// line comment ##/* block comment anfang ##*/ block comment ende ##if ##elsif ##endif ##img ... ## [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 | ... |