*** /dev/null Fri May 3 15:11:00 2024
--- - Fri May 3 15:11:48 2024
***************
*** 0 ****
--- 1,446 ----
+
+ 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!
+
|
