Index: ossp-pkg/sugar/sugar.txt RCS File: /v/ossp/cvs/ossp-pkg/sugar/Attic/sugar.txt,v rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/sugar/Attic/sugar.txt,v' 2>/dev/null --- sugar.txt 2000/09/14 15:51:52 1.1 +++ sugar.txt 2000/09/26 07:48:43 1.2 @@ -2,94 +2,164 @@ Sugar -- The Markup Language With Invisible Syntactic Sugar =========================================================== - Ralf S. Engelschall - Christian Reiber + Ralf S. Engelschall ,&{br} + Christian Reiber - Genesis: March 12th, 1999 - Last Update: June 20th, 2000 + ++ | Genesis: | 12-Mar-1999 | + | Last Update: | 26-Sep-2000 | Introduction ------------ - Sugar is a markup language and corresponding translator tool for - technical documentations which uses mostly invisible markup tags (the - so-called "syntactic sugar"). The general idea is that the markup text - looks already like the textual output of the translator phase, i.e., - the sugar source can be already treated as its text format version. - Additionally the Sugar markup language is considered intuitive enough - to be recognized easily, so not writing technical documentation - because of horrible markup languages is no longer an excuse. + Sugar is a markup language and corresponding translator tool for technical + documentations 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 format version. 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. 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, i.e., a paragraph of text (without any - blank lines) where each line starts at the same indentation position. + ++ | | | | + | | ::= | * | + | | ::= | \| | + | | ::= | <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 tags of the Sugar markup language are described in the following: + The Sugar markup language consists of markup tags grouped into a few + classes: - o Formatting: + o ..Visual Formatting:.. - __ 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) - - o Links and References: - - -->text(scheme:path) external hyperlink via URL - -->text(ref) internal hyperlink via anchor-name - (+ref+) internal anchor definition - - - o Headers (by underlining a piece of text): - - ======= 1.level - ------- 2.level - - - - - 3.level - - - - 4.level + 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 + | ||->||[//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/). - o Lists: (identified by first non-blank character in line) + 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. - o - * unordered - o. -. *. ordered (digit start selectable with 1., 2., 3., ...) - words :: glossary-style - - o Tables: - - ++ | | | - | foo | !!bar | quux - | foo | baz - bar | quux - | bazfoo - fjfjkwq - rwrqwd sddksjk - | dsdjks - | foo - | dsdsds + ++ | 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 can be used 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 indicated by + ||\||| characters. 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 row, or (in case the first regular row is not a complete + one, that is has multi-column cells) it can be an empty row (all cells + are specified for indication but are left blank). + + Example: + + || ++ | | | | + | foo | !!bar | quux | + | foo | baz + bar | quux | + | bazfoo + fjfjkwq + rwrqwd sddksjk + | dsdjks + | foo | + | dsdsds | o Special Formatting: @@ -99,11 +169,12 @@ o Escaping and Special Characters: - \- em-dash (ger. "Gedankenstrich") + -- 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): @@ -444,3 +515,10 @@ - UNBEDINGT Unicode und UTF-8 unterstutezen von anfang an! +Idea for homogenous tags: +- any XX tags can be repeated multiple times, ie XXXXX is valid also +- any begin XX tag at the end of a paragraph wraps around its scope, ie + it is applied to the whole paragraph as it would stand at the start + of the block (marged out?). +Results: +- headlines are marked equally with blocks