ossp-pkg/sugar/sugar.txt
1.1.1.1
Sugar -- The Markup Language With Invisible Syntactic Sugar
===========================================================
Ralf S. Engelschall <rse@engelschall.com>
Christian Reiber <chrei@en.muc.de>
Genesis: March 12th, 1999
Last Update: June 20th, 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 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.
Markup Language
---------------
The tags of the Sugar markup language are described in the following:
o 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
o Lists: (identified by first non-blank character in line)
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
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
o Commands (all charblock until EOL):
##! <shebang>
##include
##// line comment
##/* block comment anfang
##*/ block comment ende
##if
##elsif
##endif
##img ...
##<formatierung> [range]
_______________________________________________________________________________
1. Scanner erkennt die Intentation, strippt sie
weg, berechnet aber durch sie die "schliessenden
Klammern" zu den 2d-tags.
2. Scanner erkennt auch die Unterschiede zwischen
1d und 2d tags, da der Parser ja keinerlei
Unterscheidung treffen kann (spaces/indent nicht mehr da)
3. Scanner hat einen Look-Ahead von 1 Zeile plus
ihrem Indent
4. Das Parsen von Headern "(====)" geht einfach:
Der Scanner erkennt nur das "^========" und
ein Baumtransformator haengt spaeter
die Sohn-Sequenz "<paragraph> x ..... y <header>"
um in "<parapraph> <header> x ... y", d.h.
der transformator geht bis zum letzten Paraphraph
Knoten zurueck.
If the "text" on hyperlinks is missing in links, the reference is printed
instead. For internal links the text is chapter and pagenumber
(except for HTML, there exists real hyperlinks).
Stichworte:
Whatever | Irgendwas
---------- | -----------------------------
Brain Dump | VHIT (Vom Hirn ins Terminal)
Blabla | ASCII WYSIWYG
Design-Grundsaetze
------------------
1. KISS bei der Sprache (Beschreibung geht auf eine Seite und ist ISO-Latin-1!)
2. KISS bei der Implementierung (Code-Groesse <= 80KB)
3. Wir implementieren nur das, was wir _WIRKLICH_ brauchen.
4. Sugar ist wie Unix: Wenige Konzepte existieren und
werden konsequent durchgezogen
5. Sugar hat *keine* GUI, sondern ist ein Filter!
Beispielaufruf:
$ cat test.txt | sugar --html -otest.html
6. Sugar ist stand-alone (bis auf Postscript),
man braucht also nicht 1001 Tools bei der Installation
7. Release early, release often (Eric S. Raymond)
8. Jedes Markup kann immer eindeutig formuliert werden (=non-magic),
nur sieht es dann eventuell nicht so schoen aus.
Wenn man sich an bestimmte Regeln haelt, kann man
im Magic Mode ASCII-Aesthetik pur nutzen.
Non-Magic ist immer nutzbar und aktiviert, Magic-Mode per default an, aber
kann abgeschalten werden (per -xx und/oder inline tag) Idee: -xx im
Dokument direkt eingeben ala vi/less
Was Sugar nicht ist
-------------------
1. Sugar ist _keine_ Textverarbeitung oder ein DTP-Tool
2. Sugar ist keine Markup-Sprache (der Text ist bereits das Endprodukt)
3. Sugars Brother is more/less and not nroff (i.e. Sugar is fast!)
Anwendungsfeld
--------------
1. Technische Dokumentation fuer mehrere Darstellungsplatformen:
Plain ASCII (= Sugar Quelle), roff/-man (Unix), HTML (= Online), PS (= Print)
2. Brain Dump!
Sprach-Konzepte
---------------
1. Escape-Konzept
- per character
- (per block)
2. Simples Markup-Konzept
- Headers
- Stufe 1-3
- optional automatische Nummerierung
- Lists
- Ordered
- Unordered
- Description
- Tabellen
- Inline Markup
- Underline
- Bold
- Italics
- Code
- (Boxed)
3. Block-Konzept
- (per paragraph)
- per line
- per word ???
- per character
4. Verweis-Konzept
- internal (reference)
- external (hyperlink)
5. Native-Output-Markup (if-html)
Optionale Zusatzfeatures
------------------------
- ToC
- Index
1. Escape-Konzept
- per character Idee: \
- (per block) Idee: \\ (einsetzbar wie normales Blockkonzept)
2. Simples Markup-Konzept
- Headers
- Stufe 1 (Part)
Foo Bar Foo Bar Foo Bar Foo Bar
===============================
xxxxx
- Stufe 2 (Chapter)
Foo Bar Foo Bar Foo Bar Foo Bar
-------------------------------
- Stufe 3 (Section)
Foo Bar Foo Bar Foo Bar Foo Bar
- - - - - - - - - - - - - - - -
- Stufe 4 (Paragraph)
Foo Bar Foo Bar Foo Bar Foo Bar
Foo Bar Foo Bar Foo Bar Foo Bar
Foo Bar Foo Bar Foo Bar Foo Bar
Foo Bar Foo Bar Foo Bar Foo Bar
Foo Bar Foo Bar Foo Bar Foo Bar --
dsh hdsjhfdhjf klfhd jkash flhaflhaslfhlfjdha
dsh hdsjhfdhjf klfhd jkash flhaflhaslfhlfjdha
dsh hdsjhfdhjf klfhd jkash flhaflhaslfhlfjdha
dsh hdsjhfdhjf klfhd jkash flhaflhaslfhlfjdha
- optional automatische Nummerierung
- Lists
- Ordered
Idee: Wir erlauben [o-*+.] _UND_ <num>. und durch <num>. wird
die defaultmaessige Zaehlung forciert auf <num>
1. erster
o xxxx
o xxxx
1. xxxx
- xxxx
- xxxx
1. xxxx
. xxxx
o xxxx
- Unordered
(alle drei sind auf allen akzeptiert: o-*)
o xxxx
o xxxx
- xxxx
- xxxx
- xxxx
- xxxx
- Description
(sowohl newline als auch leading blank sind optional)
das word::
xxxxx
xxxxx
das zweite
word::
xxxxx
- Code (ala TeX-Idee intern)
|| $ sjsjfkdjfd
$ kfjd kfjdkjf
$ xxx
- Einrueckung
>> ...
- Tabellen
XXX XXX XXXX
foo bar quux
foo baz quux
bar
bazfoo bar
chrei:
rse:
++ | | |
| foo | !!bar | quux
| foo | baz
bar | quux
| bazfoo
fjfjkwq
rwrqwd sddksjk
| dsdjks
| foo
| dsdsds
o Tabellen sind Bloecke und werden mit ++ eingeleitet wie
andere Bloecke auch, d.h. Ende ist bei Ausrueckung oder
selber Level.
o Jede Tabellenzeile faengt mit einem | an und immer in der selben Spalte.
o Die |'s der ersten Zeile geben die Gesamtanzahl und die Normposition
der Spalten an.
o Besteht die erste Zeile nur aus |'s (und keinem Inhalt), dann
ist sie eine _reine_ Normungszeile und erzeugt auch keine Leerzeile.
Ansonsten (Zeile 2, ...) kann man so selbstverstanelich eine
Leerreihe erzeigen.
o Spaltentrennungs-| koennen an belieber Stelle stehen, wenn
genuegend da sind.
o Folgespalten sind dadurch gekennzeichnet, dasz ihr | eingerueckt
erscheint.
o Multicolums liegen vor, wenn weniger |'s auftreten, als die
Normungszeile vorgibt. Die Erkennung der Span's erfolgt dabei ueber die
Position der |'s, d.h. sie muessen die |'s der Normunszeile matchen.
Zusaetzlich kann die Normungszeile beliebig oft wiederhlt werden.
Aber dabei darf sich nur die Position der |'s aendern, aber
nicht die Anzahl (klar!).
o Leerzeilen bestehen aus nur einem |' am Anfang und sonst nichts.
o Normungszielen haben mind.(!) 2 |'s.
o Leerzeilen erzeugen im Output soviele |'s wie die Normungszeile
vorgibt. Fuer andere Layouting-Dinge muss man z.B. ``| \_'' schreiben.
o In einer Tabelle koennen alle Zeichenformatierungen genutzt werden,
ausser || (Vertatim).
o In der Normungszeile kann mit den Zeichenformatierung-Tags
die Formatierung der Tabellenspalten angegeben werden!
- Inline Markup
- Header (Paragraph):
chrei: --xx xxx xxx-- rse: -- xxx xxx xxx
- Underline:
chrei: __xxx__ rse: _xxx_ (= underline)
- (Boxed):
chrei: --- rse: [_xxx_]
- Bold:
chrei: **xxx** rse: *xxx* (Asterisk is fat)
- Italics:
chrei: //xxx// rse: /xxx/ (/ von Italic Direction)
- Code:
chrei: ""xxx"" rse: |xxx| (courier/teletype ist gerade schrift)
- Paragraph:
chrei/rse: Leerzeile!!
- Hartes Newline
rse: ~~
3. Block-Konzept
Es gibt zwei Blockkonzepte:
- character block (eindimensional) und
- line block (zweidimensional).
Der //character block// wird durch das Tag eingeleitet und wieder beendet. Das
Paragraph Ende beendet in jedem Fall den character block.
Der //line block// beginnt mit dem Tag __ausgerückt__, wobei davor keine
Leerzeile stehen muß (ein \n und ggf. \s davor reicht). Er enthält ganze
Zeilen und zwar solange, wie Text in der Zeile mindestens zwei Leerzeichen
weiter rechts beginnt als das einleitende Tag. Achtung: Tags stellen selbst
__nicht__ den Zeilenanfang dar! Damit kann ich also line blocks schachteln.
(Anders gesagt: Es geht nicht um den linkenRand der Textdatein, sondern um
den linken Rand des übergeordneten Line Blocks.)
Automatischer reflow durch den Editor ist bei character blocks **kein**
Problem, da das Tag keine positionsabhängige Bedeutung hat (daher wurde
auch verworfen, daß ein Tag am Zeilenanfang, aber nicht ausgerückt, am
Zeilenende beendet wird). Das Start-Tag beim line block wird vom Editor
nicht versetzt (wenn er was taugt).
Möglicherweise kann für bestimmte Tags das Ende des char blocks auch das
Zeilenende (nicht das Para. Ende) sein. Gedacht ist an Kommandos:
Gehen sich nach http://laber.lall
Das ist ## eine blöde Zeile und ich will daß ##das## unterstrichen ist
''##das ist ungut##
##das ist intuitiver, bedeutet aber Kommandoende=Zeilenende
Das wäre dann eine Eigenschaft des Tags, d.h. es verhält sich dann
//immer// so (und nicht mal so und mal anders).
Beispiele:
1. ''Dies ist ein Beispiel für einen Text, __in dem der zweite
Halbsatz unterstrichen wird__, obwohl er sich über eine
Zeilengrenze erstreckt.
o. ''__In diesem Fall wird der line block unterstrichen. Das
geht solange, bis der Text wieder ausgerückt wird.
Auch Leerzeilen stellen da kein Hindernis dar.
Diese Zeile beendet den Line Block.
o. ''Ein Sonderfall: __Dieser Text hat kein Ende-Tag.
Er wird dann durch das Paragraph-Ende beendet.
Ab hier also keine Unterstreichung mehr.
4. Verweis-Konzept(+)
- internal (reference)
anchor: foo (+Verweis-Konzept+) bar
reference: foo ->Verweis-Konzept bar
- external (hyperlink)
reference: foo ->http://wwww bar
o Native-Output-Stuff
xxxx
``jdjlasdjajlad``
skd asdk s
dsö ksaölkdaös##
dfkdjsdal
html
xxxx
##endif
xxxx
o Comments
##//
##/*
##*/
5. Inline-Images
- Source ist immer Bitmap-Grafik im GIF Format!
(Fuer ASCII: gifscii, Fuer HTML: Direkt, Fuer PS: gif2ps)
##img xx.gif size=jsjs s=xx
- UNBEDINGT Unicode und UTF-8 unterstutezen von anfang an!