OSSP CVS Repository

ossp - Difference in ossp-pkg/sugar/sugar.txt versions 1.1 and 1.2
Not logged in
[Honeypot]  [Browse]  [Home]  [Login]  [Reports
[Search]  [Ticket]  [Timeline
  [History

ossp-pkg/sugar/sugar.txt 1.1 -> 1.2

--- 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 &nbsp;)
     \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

CVSTrac 2.0.1