Paketdokumentation
und Webseitenpflege mit
(niceverb.sty und)
fifinddo.sty

Teil 0: Über den Vortrag

Vortragstitel bedeutet (I):

„Paketdokumentation“

– Beschreibung von LaTeX-Makro-Paketen, d. h.

1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter Paketcode wechselt mit in LaTeX-Qualität gesetztem Kommentar ab („zeilenweise“)
2. der Kommentartext enthält „verbatim“ gesetzten TeX-Code („inline“) zur Bezugnahme – insbesondere:
3. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer:
   „Tippt man

   \foo∗[⟨opt-arg⟩]{⟨mand-arg⟩},

   so erhält man …“

Vortragstitel bedeutet (II):

Vortragstitel bedeutet (III):

Vortrag interessant …

Inhaltliche Motive

Persönliche Motive

Status

Vortragsteile

Teil 1: „Markup“ oder so (Begriffsklärung – oder so)

Von .txt zu .tex

1. „typografische Zeichen“ – „typografische“ Varianten von Auslassungspunkten, Anführungszeichen, Leerzeichen, und Strichen.
2. „Formatierung“ – Umschalten zwischen Zeichensätzen, Einrücken, Listen, Verweise, …

„Auszeichnung“

Teil 2: Typografische Zeichen mit TeX/LaTeX

Typografische Zeichen mit TeX/LaTeX

[„Aktive Zeichen“ verhalten sich wie Makros, TeXbook S. 37 ]

Bewertung –
„minimales Markup“ genauer

Typografische Zeichen – Bewertung

Typografische Zeichen automatisch?

1. automatische Umwandlung „reiner“ Zeichen in „typografische“?
   
2. \sfcode`A=999 schon in diese Richtung (TeXbook S. 76)
3. so ja optional Anführungszeichen in Word
4. … und hier – simpel, solange nicht german/babel …:
   "..." expandiert zu \glqq...\grqq oder so
5. eigentlich nur dies (automatisches Einfügen typografischer Zeichen) „.txt→.tex“ in nicetext-Beschreibung (Schwäche der Terminologie)
6. WARNUNG! fehlerhafte Automatisierung typografischer Anführungszeichen kann zum Verlust des Doktortitels und politischer Ämter führen! (gutten.sty) [ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ]

.txt→.tex vor nicetext

1. txt2latex kleines Perl-Skript, wandelt gerade TeXs spezielle Zeichen („&“ etc.), „...“ und doppelte/einzelne Anführungszeichen um (s. Datei txt2latex)
2. txt2tex – Perl, erzeugt tatsächlich LaTeX-Formatierung (Paketnamen „verkehrt“!)
3. EasyLaTeX ähnlich oder mehr, GUI(?), Ideen aus Wiki…-Markup; zuletzt 2004 (README 2009 eher CTAN-Hand)
4. SmileTeX Windows .exe? + Werkzeuge für Grafikeinbindung etc., zuletzt 2004

Teil 3: „Formatierung“ (Auszeichnung, Wikipedia)

Wikipedia: Schriftauszeichnung

– Intuition dahinter vielleicht: Bedeutungen von kursiv und
doppelten Anführungszeichen verwandt, z. B. Buchtitel

Wikipedia: Listen und Zitate

Teil 4: Implementierung
„minimalen Markups“
„mit TeX allein“

Implementierungsmethoden für
„minimales Markup“ mit TeX

Methode (MS) – Anmerkungen I

1. Vor- und Nachteile entstehen daraus, dass ein „String“ aus „reinem Text“ von TeX intern durch unterschiedliche „Token-Ketten“ „dargestellt“ werden kann. Auch von Groß-/Kleinschreibung abzusehen ist nicht ganz einfach.
2. Diese Methode wurde seit längerem von LaTeX’s internem \@in-Makro [hauptsächlich zur Erkennung von Paket-Optionen] und vom Paket substr (Harald Harders bzw. Heiko Oberdiek) angewandt.
3. Gegenwärtig fußen auch fifinddo.sty und makedoc.sty (nicetext) auf dieser Methode – genügte bisher praktisch.

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

1. Die Pakete stringstrings (Steven Segletes), xstring (Christian Tellechea, e-TeX) und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen „auf höchstem Niveau“.
2. String-Funktionen finden sich auch in datatool (Nicola Talbot), coolstr (Nick Setzer) und texapi (Paul Isambert).
3. Eine „ernsthafte Skriptsprache“ bietet neben Zeichenersetzung allgemeiner „Sortierung“ und „Filter“. Beispielsweise bietet docstrip eine TeX-basierte Skriptsprache, die aus einer .dtx-Quelldatei die „Kommentare“ entfernt und den Rest in verschiedene „kompakte“ TeX-Eingabedateien „sortiert“.

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

1. statt \...section{...} einrahmende Gleichheitszeichen-Folgen verwenden,
2. Kursiv- und Fettschrift mit Folgen von „Apostroph-Ersatzzeichen“ (ASCII-Code 39) ein- und abschalten,
3. Listen und Blockzitate aus Menschen- oder Programmiersprache durch spezielle Zeilenanfänge anzeigen.

wiki.stys „forschende“ Zeichen

1. Gleichheitszeichen werden aktive Zeichen, die feststellen, wieviele Gleichheitszeichen unmittelbar aufeinander folgen.
2. Ebenso funktionieren die Apostroph-Ersatzzeichen. Dabei werden \textit und \textbf nicht direkt verwendet, das Umschalten und die Kursivkorrektur finden ohne „Gruppenbildung“ statt.
3. Um Listen und Zitate am Zeilenanfang zu erkennen, wird das Zeilenende-Zeichen (^^M) aktiv und ändert auch für kurze Zeit die Kategorie des Leerzeichens. So analysiert ^^M den Anfang der nächsten Zeile und kann feststellen, ob eine Liste bzw. ein Blockzitat beginnt, fortgesetzt wird, oder endet, oder ob der Liste ein weiterer Punkt (\item) hinzugefügt wird. Entsprechend wird automatisch eine \begin{...}- bzw. \end{...}-Zeile oder das Makro \item eingefügt

(MA) vs. (MS)

Teil 5: Dokumentation von LaTeX-Paketen (mit nicetext)

Die Pakete des nicetext-Bündels

wiki.sty

1. Schriftkodierung durch Folgen von Apostrophen finde ich nicht intuitiv genug, um andere Paketbearbeiter damit konfrontieren zu wollen, [Publikum (U. Z.): Markdown!]
2. … sie ist gegenwärtig auch inkompatibel mit der Verwendung „aktiver Apostrophe“ in niceverb.sty.
3. Überschriftenkodierung durch Gleichheitszeichen verwende ich bisher in der (MA)-Implementierung von makedoc.sty.
4. Dass Einrücken eine verbatim-Umgebung auslöst, finde ich unpraktisch.
5. Im Quelltext sehe ich lieber „1.“, „2.“, …als „#“.
   [Publikum: Markdown!]
6. Unnummerierte Listen mit * sind OK, habe ich mal für „Fremddokumentation“ eingesetzt.

Teil 6: niceverb.sty

niceverb.sty – „Schriftauszeichnung“

1. Umrahmung mit einfachen Apostroph-Ersatzzeichen (’nicetext’) wirkt wie \textsf – für Paketnamen.
2. einfache Anführungszeichen wirken wie \texttt – für Code – tatsächlich wirkt ‘\foo’ (solange nicht in Makro-Argument) wie \verb+\foo+ (Inline-verbatim).

Beschreibung von LaTeX-Makros

 
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩} 

 
‘\foo∗[<opt-arg>]{<mand-arg>}’ 

 
|\foo∗[|\meta{opt-arg}|]{|\meta{mand-arg}|}| 

Hervorhebung von Makrobeschreibungen

• schalten im vorigen Beispiel (doc.sty) – wie es sehr üblich ist – verbatim-Modus an/aus, d. h. |\foo| kürzt \verb|\foo| ab –
• sollen mit niceverb.sty Code hervorheben und beim Überfliegen der Dokumentation herausstechen lassen („hier Erläuterung von \foo!“)

 
|\foo∗[<opt-arg>]{<mand-arg>}| 

\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}

niceverb.sty noch:

1. „<meta>“ erzeugt „⟨meta⟩“ sowohl innerhalb als auch außerhalb von einfachen Anführungszeichen.
2. Im „Auto-Modus“ werden LaTeX-Befehle nicht ausgeführt, sondern als verbatim-Text interpretiert, etwa folgende Sterne und Klammern als Syntaxbeschreibung dazu.
3. – dient besonders der „Fremddokumentation“ (vorhandene ASCII-Paketdokumentation anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
4. „&“ ist aktives Zeichen, welches in Makroargumenten Befehlen und Syntaxbeschreibungen vorangestellt werden kann, um „nachzuhelfen“:

    
   \footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
   

5. aktive Zeichen → Probleme … Auswege …

Ähnliche Pakete anderer Autoren

1. niceverb.sty ist wesentlich inspiriert durch die Dokumentationsmethode Stephan Böttchers in lineno.sty.
2. Ähnliche Funktionalität liefert auch ltxguide.cls für die „LaTeX-Guides“.
3. Die bequeme Syntaxbeschreibung gibt es („mittlerweile“) auch in Martin Scharrers ydoc.
4. niceverb.sty ist ebenso wie ydoc als Alternative zu doc.sty konzipiert. ydoc liefert dabei einen ähnlichen Funktionsumfang wie doc.sty, während ich (für meine Zwecke) einen solchen Funktionsumfang überhaupt nicht haben will. – Allerdings habe ich einzelne doc.sty-Funktionen in makedoc.sty und in readprov.sty (fileinfo-Bündel).

Teil 7: „Kommentar“

Code und „Kommentar“

TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, in Quelldateien Text einzufügen, der nicht vom Compiler bzw. Interpreter (als Befehle/Daten) verarbeitet werden soll, sondern an (menschliche) Leser gerichtet ist – hier „Kommentar“.
Einzelne Zwecke (der Wikipedia-Artikel weiß noch mehr …):

Zwecke des Kommentars

Zwecke des „Auskommentierens“

1. als eine Art „Versionskontrolle“: man behält sich vor, den Code später wieder „an den Compiler/Interpreter zu richten“ (durch einfache Entfernung der Kommentarzeichen bzw. „Kommentarbegrenzern“), z. B. zum „Debugging“ oder für bestimmte Adressaten –
2. als „Erinnerung“ and frühere „Fehlversuche“, die auf frühere „Überlegungen“ hinweist und so wieder der Wartung durch den Programmierer/Autor dient.

Teil 8: Methoden Kommentar „auszublenden“

Feinheiten des „Ausblendens“
von Kommentar

1. Enthält eine TeX/LaTeX-Paketdatei die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, so umfasst sie typischerweise wesentlich mehr Kommentarzeilen als Anweisungszeilen.
2. Auch „Programmierertext“, der die Implementierung sorgfältig diskutiert, kann im Verhältnis zum Code sehr umfangreich sein (z. B. lineno.sty).
3. „Vor langer Zeit“ forderte das Einlesen von TeX-Makrodateien aufgrund der „Hardware-Umstände“ bereits so viel Zeit, dass es sinnvoll war, das Einlesen von Kommentarzeilen völlig zu vermeiden …

„Ausblenden“ von Kommentar – Forts. …

1. Ein „primitiver“ Ansatz dazu war, die „Gebrauchsanleitung“
   „am Ende der Datei“ nach dem \endinput-Befehl der Datei anzubringen. Die Datei enthielt dann gerne am Anfang den Hinweis auf die Gebrauchsanleitung der Datei an ihrem Ende.
   Der \endinput-Befehl bricht die Verarbeitung der Datei ab, so dass die Zeilen darunter tatsächlich keine Verarbeitungszeit mehr beanspruchen.
2. Andererseits sollte für die Wartung der Kommentar eben doch in der Nähe der betreffenden Code-Zeilen angebracht werden …

docstrip blendet noch effizienter aus:

1. Mit LaTeX2 hatten Paket-Dateien die Endung „.sty“.
   Sie enthielten noch „Kommentar“ wie oben.
2. Mit LaTeX2e wurden doc.sty und docstrip.tex eingeführt. Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung „.doc“ oder „.dtx“. docstrip wandelt solche Dateien in Dateien mit Endungen hauptsächlich wie „.sty“ oder „.cls“ um; diese sollen keinen Kommentar mehr enthalten (bis auf Lizenz-Hinweise) und sind diejenigen, die im TeX-Lauf tatsächlich eingelesen werden, außer …

Kommentarzeichen

1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich durch das Kommentarzeichen („%“) am Anfang gekennzeichnet.
2. (Nach \endinput wird Code auch ohne Kommentarzeichen ignoriert; ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit „\iffalse⟨kommentar⟩\fi“ einrahmen.)
3. Diese (ganz oben) Zeilen mit Kommentarzeichen werden dann von docstrip entfernt … d. h., diese Kommentarzeichen dienen gar nicht mehr dem Zweck, die Zeilen beim Einlesen der Paketdatei als „zu ignorieren“ zu kennzeichnen, vielmehr sind sie gar nicht mehr da. Wieso dann noch Kommentarzeichen?
4. … tatsächlich: Mit Paul Isamberts CodeDoc ist der „Kommentar“ normaler, von Listing-Umgebungen unterbrochener Text (ohne „%“ links). Letztere schreiben den Code in die kompakte Paketdatei.

Ohne docstrip heute

• verschiedene in TDS-ltxmisc/, darunter einige geniale, für manche unverzichtbare Pakete von Donald Arseneau (ich sehe gerade framed …)
• Stephan Böttchers lineno.sty (Zeilennummerierung besonders für kritische Editionen und Einreichungen) enthält gewaltig viel Kommentar – von mir übernommen, nie gehört, dass das Laden zu lange dauere …
• alle (? \endinput) meine eigenen Pakete (was natürlich einfach eine Frechheit sein kann …)

Teil 9: „Darstellung“ des Kommentars

„Darstellung“ des Kommentars – „Vorzeit“

1. Vor doc.sty war der Kommentar in Paketdateien dazu da, mit einem Texteditor gelesen oder im „Text“-Modus (als „Listing“, im Gegensatz zum für TeX erforderlichen „Grafik“-Modus) ausgedruckt zu werden.
2. Kommentar entsprechend „reiner ASCII-Text“, weder „typografische Zeichen“ noch Auszeichnung.

Darstellung des Kommentars mit doc.sty

1. Erst mit doc.sty wurde die heute von LaTeX-Paketen auf dem CTAN gewohnte LaTeX-Druckqualität des Kommentars möglich, wobei man den Code als Imitation der Texteditor- und Listing-Druckqualität auszeichnet. Entscheidend ist dabei der „Don’t repeat yourself“-Grundsatz – die Code und Kommentar mischende Quelldatei wird für den Qualitätsausdruck nicht von Hand überarbeitet, sondern „automatisch“ mit dem \DocInput-Befehl verarbeitet.
2. (Wie war das eigentlich mit WEB?)
3. Dazu kann man allerdings (oder konnte bisher) nicht (den früheren) „ASCII“-Kommentar verwenden, der Kommentar muss vielmehr als „LaTeX-Input“ mit typografischen Zeichen und LaTeX-Markup in der Code+Kommentar-Quelldatei stehen (vgl. ltxdoc-Dokumentation zu {oldcomments}).

\DocInput{⟨c+k⟩}

 
% \textit{dolce far niente:} 
%    \begin{macrocode} 
  \relax 
%    \end{macrocode} 
% -- genug, 

 
 \textit{dolce far niente:} 
    \begin{macrocode} 
  \relax 
    \end{macrocode} 
 -- genug, 

(\DocInput)

 
 \textit{dolce far niente:} 
    \begin{macrocode} 
  \relax 
    \end{macrocode} 
 -- genug, 

„Minimales Markup“ würde bedeuten, dass man dasselbe Ergebnis …

„Minimale“ Kennzeichnung des Codes

 
% \textit{dolce far niente:} 
%    \begin{macrocode} 
  \relax 
%    \end{macrocode} 
% -- genug, 

 
% \textit{dolce far niente:} 
  \relax 
% -- genug, 

„smartes“ \DocInput

1. gmdoc (Grzegorz Murzynowski; ich meine mich zu erinnern:
   wie bei wiki.sty sind die Zeilenendzeichen aktiv
   und schauen sich den nächsten Zeilenanfang an)
2. lineno (Stephan Böttcher) – eine UNIX-Shell wendet ein in der Datei lineno.sty enthaltenes awk-Skript auf lineno.sty an, erzeugt Dokumentationsdatei lineno.tex …
3. makedoc.sty (selbst) bietet statt awk eine Art TeX-basierte Skriptsprache und unterschiedliche Zeilenparser,
   um jeweils eine Dokumentationsdatei zu erzeugen.

„Interpretationen“ von Kommentarzeichen

 
\typeout{ok} %% Code 
% \typeout{ko} %% auskommentierter Code 
%% <- falls ko %% Kommentar 
%% % <- falls KO %% auskommentierter Kommentar 
%% %% <- 2011/10/01 %% Kommentar zum Kommentar 

makedocs \DocInput{⟨job⟩}

Dokumentationslauf

1. ⟨job⟩.pdf von ⟨job⟩.sty aus ⟨job⟩.tex.
2. ⟨job⟩.tex enthält makedoc-Befehle zur Erzeugung von ⟨job⟩.doc aus ⟨job⟩.sty und zum Einlesen von ⟨job⟩.doc,
3. kann noch Dokumentation von Ergänzungspaketen ⟨add⟩ via ⟨add⟩.doc einbinden.
4. ⟨job⟩.doc/⟨add⟩.doc können
   (nach \RequirePackage{makedoc})
   ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt und dann in der {document}-Umgebung mit \input eingelesen werden.

Erfolge/Scheitern

1. Ich kann damit flott Pakete schreiben/dokumentieren
   (auch mit Dokumentation als „Roadmap“ beginnen).
   Nach Einrichten des Dokumentations-Workflows
   läuft mittlerweile meist alles „wie am Schnürchen“.
2. Einrichten eines solchen Workflows war aufwändig,
   dafür jetzt Vorlagen sowie Bash- und fifinddo-Skripts.
3. Fehler wegen Umwegs über erzeugte Dateien
   (mehr Zeilen als in Quelldatei) manchmal schwer verständlich …
4. In der Praxis kann ich (derzeit) doch LaTeX-Befehle
   (Backslashs, …, vgl. Vorgabe) nicht ganz vermeiden,
   wohl vor allem bei Verweisen …
5. Dennoch gelungene „Fremddokumentationen“:
   arseneau.pdf, substr.pdf.

Vorteile und Problematik der Zeichenkategorien (\catcode...)

Teil 10: HTML erzeugen

Nutzen von HTML (vs. PDF)

HTML-Erzeugung – Alternativen

• HTML-Editoren, CMSe?; Formeln? keine Ahnung, egal
• TeX4th (Eitan Gurari†; Wikipedia sehr informativ) – verarbeitet .dvi, kommt insofern (wohl) mit allen Paketen/Makros zurecht, ohne sie einzeln zu behandeln – damit Webseiten pflegen?
• diverse Syntax-Wandler wie LaTeX2html (Perl), hevea.inria.fr, TeX2page, TtH (C; Home: Formeln!); vgl. tug.org/interest.html#web
• blog.sty (morehype-Bündel) – expandiert Makros zu HTML; LaTeX-Makros umdefiniert, neue Makros für bestimmte HTML-Strukturen, z. B.lnavicol.sty

HTML und PDF aus selber Quelle?

Was (zur Zeit) nicht geht

Dank