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