--- 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 <rse@engelschall.com>
- Christian Reiber <chrei@en.muc.de>
+ Ralf S. Engelschall <rse@engelschall.com>,&{br}
+ Christian Reiber <chrei@en.muc.de>
- 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.
+ ++ | | | |
+ | <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 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 |
+ | <block> ||::|| | | 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 <br>)
\\ 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
|
