Index: ossp-pkg/sugar/README RCS File: /v/ossp/cvs/ossp-pkg/sugar/README,v co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/sugar/README,v' | diff -u /dev/null - -L'ossp-pkg/sugar/README' 2>/dev/null --- ossp-pkg/sugar/README +++ - 2024-05-18 01:58:40.641195361 +0200 @@ -0,0 +1,11 @@ + ___ _ _ __ _ __ _ _ __ + / __| | | |/ _` |/ _` | '__| + \__ \ |_| | (_| | (_| | | + |___/\__,_|\__, |\__,_|_| + __________ |___/ ___________________________________________________ + + Sugar -- The Markup Language With Invisible Syntactic Sugar + + Copyright (c) 1999-2000 Ralf S. Engelschall + Copyright (c) 1999-2000 Christian Reiber + Index: ossp-pkg/sugar/sugar.txt RCS File: /v/ossp/cvs/ossp-pkg/sugar/Attic/sugar.txt,v co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/sugar/Attic/sugar.txt,v' | diff -u /dev/null - -L'ossp-pkg/sugar/sugar.txt' 2>/dev/null --- ossp-pkg/sugar/sugar.txt +++ - 2024-05-18 01:58:40.662261470 +0200 @@ -0,0 +1,446 @@ + + Sugar -- The Markup Language With Invisible Syntactic Sugar + =========================================================== + + Ralf S. Engelschall + Christian Reiber + + 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
) + \\ a backslash (there no block concept!) + \X escapes following character X + + o Commands (all charblock until EOL): + + ##! + ##include + ##// line comment + ##/* block comment anfang + ##*/ block comment ende + ##if + ##elsif + ##endif + ##img ... + ## [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 " x ..... y
" + um in "
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_ . und durch . wird + die defaultmaessige Zaehlung forciert auf + 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! +