uwe_lueck > texmap > dantev45-768-exact-show – neu laden –

[ START <<< zuerst klicken, dann auf Bildunterrand klicken bzw. knapp unter Text (MSIE) und rechts unten für „Rückkehr“
  – more about the present file on: CTAN
 teil-0 | titelerlaeut1 | titelerlaeut2 | titelerlaeut3 | interessant | motive-t | motive-p | status | inhalt
 teil-1 | txt2tex | txt2tex-trad
 teil-2 | typoz-latex | minimal-mehr | typoz-bewert | typoz-auto | typoz-ctan
 teil-3 | wiki-markup | wiki-listen
 teil-4 | implement | implement-ms | implement-ms2 | implement-ma | implement-ma+ | implement-mas
 teil-5 | nicetext | wiki
 teil-6 | niceverb | syntax | vert | niceverb-noch | niceverb-sim
 teil-7 | kommentar | kommentarzw | kommentarzwa
 teil-8 | kommentar-ignor | kommentar-ignor-mehr | docstrip | kommentarzch | ohne-docstrip
 teil-9 | doku-vor | doku-doc | docinput | docinput2 | docinput-min | makedoc-input | makedoc-lauf | erfolg | catcodes
 teil-10 | html-alt | html-statt-pdf | html-und-pdf | blog-probleme | schluss ]

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

Uwe Lück
Überarbeitete Fassung des auf der
DANTE-Herbsttagung 2011
gehaltenen Vortrags
2011-10-25

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):

„Webseitenpflege“
– „hochtrabend“, zunächst bloß: HTML-Erzeugung –
  • Internetauftritt (? CMS? – ja …)
  • bequeme Textformat-Alternative zu PDF …
    (Notizen zu Links, Beamer-Präsentation …)

Vortragstitel bedeutet (III):

… was haben Paketdokumentation und HTML-Erzeugung miteinander zu tun??

(– Zu HTML-Paketdokumentationen
habe ich es noch nicht gebracht …)

Vortrag interessant …

  1. wenn man als Makroprogrammierer doc.sty und docstrip.tex („.dtx …“) zu aufwändig findet …
  2. wenn man HTML schätzt und PDF vermeiden möchte …
  3. wenn man Makro-Denksport mag

Inhaltliche Motive

  1. „minimales Markup“, „syntaktischer Zucker“ (LaTeX-Qualität möglichst ohne LaTeX-Befehle)
  2. „Missbrauch“ von TeX als „Skriptsprache“
    („mit TeX muss und will ich keine andere Sprache lernen“; statt PDF-Schriftsatz – wie docstrip)
  3. kleine(?), einfache(?), experimentelle(!), („schrullige“,) gerade eigenen (U. L.) Bedürfnissen entsprechende Alternativen zu existierenden „professionelleren“ Paketen (Erfolge – Scheitern …)

Persönliche Motive

(bemerkenswerte Mischung aus:)
  1. gespannt auf Kommentare
    zu meinen Paketen,
  2. Vortrag soll aber auch über „Konkurrenzprodukte“ informieren
  3. Irrtümer? Hinweise? – Terminologie erst in letzten zwei Wochen „erarbeitet“
  4. Vorstellung von blogdot.sty (morehype-Bündel)
(und wohl auch ein wenig der beklagenswerten Eitelkeit …)

Status

nicht richtig fertig, zu umfangreich, hasten, überspringen
kein Experte in Typografie, HTML, CSS

Vortragsteile

  1. „Markup“? – Terminologie
  2. „typografische Zeichen“ mit TeX/LaTeX
  3. „Formatierung“
  4. Implementierung „minimalen Markups“ „mit TeX allein“
  5. Paketdokumentation
  6. niceverb.sty
  7. „Kommentar“
  8. Kommentar ausblenden
  9. „Darstellung“ des Kommentars
  10. HTML erzeugen

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

Von .txt zu .tex

Um reinen Text in LaTeX-Input (für LaTeX-Qualität) umzuwandeln, muss man normalerweise Folgendes ergänzen/ändern:
  1. „typografische Zeichen“ – „typografische“ Varianten von Auslassungspunkten, Anführungszeichen, Leerzeichen, und Strichen.
  2. „Formatierung“ – Umschalten zwischen Zeichensätzen, Einrücken, Listen, Verweise, …
– Unterscheidung nur HTML-Terminologie?
HTML verwendet für ersten Fall spezielle Zeichen wie &nbsp; (anders als \dots),
für zweiten Einrahmung mit „Tags“ wie <i>...</i> (ähnlich LaTeX …); oder …
[dachte zunächst, Wortschöpfung sei meine eigene]

„Auszeichnung“

„Traditionell“
  • bezieht sich „Auszeichnung“
    (im „Manuskript“/Typoskript, „Markup“, „Schriftauszeichnung“/Auszeichnungssprache)
    anscheinend nur auf „Formatieren“
    (vielleicht weil der Setzer das nicht „ahnen“ konnte),
  • während typografische Zeichenvarianten
    für den Setzer eher „selbstverständlich“ waren
    und im „Manuskript“ nicht besonders angezeigt wurden.

Teil 2:
Typografische Zeichen mit TeX/LaTeX

Typografische Zeichen mit TeX/LaTeX

Zeichen realisiert durch
Auslassungszeichen\dots
Gedanken-/„bis“-Strich„---“ (englisch), „--“ – Ligaturen
(Doppelte) AnführungszeichenEnglisch: Ligaturen ``...'';
Deutsch mit (n)german.sty oder babel.sty "`..."' – aktive Zeichen
Geschütztes Leerzeichen, Festabstand„~“ – aktives Zeichen, „\,“
Englisch: Leerraum nach Satzzeichen„\ “ („Steuerungsleerzeichen“), „\@“, \sfcode`...

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

Bewertung –
„minimales Markup“ genauer

„LaTeX-Qualität möglichst ohne LaTeX-Befehle“
– README des nicetext-Bündels:
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“
– schließt „typografische Zeichen“ ein – Schwäche meiner (damaligen) Terminologie –
  1. weg mit Backslashs, englischen Befehlen und geschwungenen Klammern!
  2. überhaupt möglichst wenig Code-Zeichen
  3. Zeichen möglichst intuitiv
  4. … am besten so aussehen wie Ergebnis
  5. – „ASCII-WYSIWYG“ – vs. unisugar mit Unicode …

Typografische Zeichen – Bewertung

– von TeX/LaTeX:
  1. TeX-Ligaturen schon ganz gut!
  2. aktive Zeichen … na ja … „~“ besser als „&nbsp;“, aber …
  3. \dots schon übel … (warum nicht Ligatur „...“?)

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

– auf CTAN:
  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
– für Paketdokumentation ist mir das zuviel …

Teil 3:
„Formatierung“
(Auszeichnung, Wikipedia)

Wikipedia: Schriftauszeichnung

– Anregungen wie für EasyLaTeX?

Wiki-Code wie LaTeX-Code
== Über ==\section{Über}
=== Unter ===\subsection{Unter}
'''fett'''\textbf{fett}
''kursiv''\textit{kursiv}
'''''Fett-'''Kur''\textit{\textbf{Fett-}Kur}

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

Wikipedia: Listen und Zitate

Wiki- wie LaTeX-Code Wiki- wie LaTeX-Code
∗ Eins
∗ Zwei		 \begin{itemize}
\item Eins
\item Zwei
\end{itemize}		 Er nur:
:Ja, …		 Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei		 \begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}		 Code:
 \relax		 Code:
\begin{verbatim}
\relax
\end{verbatim}

– immerhin recht „minimal“, auch halbwegs intuitiv.
(vgl. wikicheat.pdf)

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

Implementierungsmethoden für
„minimales Markup“ mit TeX

(ML)Ligaturen – …
(nicht mein Ding, Zukunft ohne METAFONT?)
(MS)„Substitution“ bzw. „Skript“, genauer: Vorverarbeitung der .tex-Datei, Zeichenkettenersetzung (und mehr) per Skript wie mit Perl / awk / etc. bzw. mit den beschriebenen Paketen
(MA)(„forschende“) aktive Zeichen – im „Schriftsatz-Modus“ (während TeX den Dokumentquelltext stückweise in Glyphen und Kästchen umwandelt) expandieren aktive Zeichen mehr oder weniger direkt zu „normalen“ LaTeX-Befehlen, „forschende“ aktive Zeichen „erkunden dabei ihre Umgebung“

Methode (MS) – Anmerkungen I

TeXs Mechanismus, sog. „begrenzte Parameter“ von Makros zu erkennen (TeXbook S. 203), bietet eine bequeme, aber auch „begrenzte“ Methode, „Zeichenketten“ („Strings“) zu erkennen
(und zu ersetzen).
  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)

wiki.sty aus dem nicetext-Bündel implementiert die zuvor beschriebene Wikipedia-Syntax für TeX, d. h. mit wiki.sty kann man in der {document}-Umgebung von LaTeX
  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)

Die Methoden (MA) (aktive Zeichen) und (MS)
(Substitution/Skript) schließen sich nicht gegenseitig aus.
Welche Methode man anwendet, ist vielleicht „Geschmackssache“. Die Wikipedia-Abschnittsüberschrift (Gleichheitszeichen) wird in wiki.sty nach Methode (MA),
in makedoc.sty nach Methode (MS) implementiert.

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

Die Pakete des nicetext-Bündels

wiki.sty
Wikipedia-Markup gemäß (MA) (s. o.)
niceverb.sty
„minimales Markup“(?) speziell für Beschreibung
von LaTeX-Makros und LaTeX-Paketen (MA)
makedoc.sty
Vorverarbeitung von Code+Kommentar-Dateien (MS)
mdoccorr.cfg
Regeln zum Einfügen typografischer Zeichen (MS)
fifinddo.sty
makedoc.sty zugrundeliegende Skriptsprache

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“

„Fortsetzung“ der Wikipedia-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).

Code mit niceverb.sty wie Code sonst
’nicetext’\textsf{nicetext}
‘\foo’\verb+\foo+
‘README.txt’\texttt{README.txt}

Beschreibung von LaTeX-Makros

„Tippt man 
 
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
so erhält man …“ – so soll die Beschreibung der Syntax von \foo im .pdf aussehen. – Code dafür mit niceverb.sty: 
 
‘\foo∗[<opt-arg>]{<mand-arg>}’
– „ASCII-WYSIWYG“
– \langle „typografisches“ „<“,
– \rangle „typografisches“ „>“.
– Code dafür mit doc.sty (aus der LaTeX-„base“-Distribution): 
 
|\foo∗[|\meta{opt-arg}|]{|\meta{mand-arg}|}|

Hervorhebung von Makrobeschreibungen

Vertikalstriche (|\foo|)
  • 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!“)
– Farbhinterlegung? derzeit „Kästen“ wie mit \fbox, intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros in einem Absatz ermöglichen. Beispiel Code/Ergebnis: 
 
|\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“

[vgl. Schuld und Sühne, Pride and Prejudice, Gesetzeskommentar zum Code civil]

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

  1. Erläuterungen für Programmierer, um die Wartung des Codes zu erleichtern –
  2. gerade im Falle von TeX- und LaTeX-Paketen (alter Zeiten) an Nutzer gerichtete „Erläuterungen“ im Sinne einer Gebrauchsanleitung
    (manchmal der einzig verfügbaren).
  3. In etwa gleichrangig Bedeutung des „Auskommentierens“ von Code, d. h. „Kommentar“ enthält eigentlich Befehle/Daten für Compiler/Interpreter, die der Programmierer (oder auch Dokumentautor) „aufbewahren“ möchte statt völlig zu löschen

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.
Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX das „Auskommentieren“ die hauptsächliche Funktion des „Kommentars“ …

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

(docstrip fortsetzend:) … aber es gibt die .sty-Pakete, die mit Kommentarzeilen (ohne docstrip einzuschalten) eingelesen werden, noch 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⟩}

… (doc, gmdoc, …) verarbeitet die Code/Kommentar mischende Datei ⟨c+k⟩ so – sie enthalte als Beispiel 
 
% \textit{dolce far niente:} 
%    \begin{macrocode} 
  \relax 
%    \end{macrocode} 
% -- genug,
\DocInput{⟨c+k⟩} führt \MakePercentIgnore vor \input{⟨c+k⟩} aus, Effekt wie 
 
 \textit{dolce far niente:} 
    \begin{macrocode} 
  \relax 
    \end{macrocode} 
 -- genug,

(\DocInput)

(Übertrag:) 
 
 \textit{dolce far niente:} 
    \begin{macrocode} 
  \relax 
    \end{macrocode} 
 -- genug,
… so kommt der Code in eine Listing-Umgebung, der Rest wird „normal“ in LaTeX-Qualität gesetzt.

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

„Minimale“ Kennzeichnung des Codes

… statt mit 
 
% \textit{dolce far niente:} 
%    \begin{macrocode} 
  \relax 
%    \end{macrocode} 
% -- genug,
schon mit 
 
% \textit{dolce far niente:} 
  \relax 
% -- genug,
erhält. Dies erreichen …

„smartes“ \DocInput

– Algorithmus klar:
 – nach Zeile mit „%“ vor „ohne“ „\begin{macrocode}“,
 – im umgekehrten Fall „\end{macrocode}“ einfügen –
  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

echter Kommentar vs. „Auskommentieren“, ich: 
 
\typeout{ok} %% Code 
% \typeout{ko} %% auskommentierter Code 
%% <- falls ko %% Kommentar 
%% % <- falls KO %% auskommentierter Kommentar 
%% %% <- 2011/10/01 %% Kommentar zum Kommentar
ergibt mit makedoc und von mir bevorzugten Einstellungen:
\typeout{ok} %% Code
% \typeout{ko} %% auskommentierter Code
←falls ko
– Parsermakros für verschiedene „Stile“, etwa Pakete anderer Autoren, die keine „%%“ verwenden

makedocs \DocInput{⟨job⟩}

Genaue Entsprechung zu \DocInput fehlt derzeit.
„⟨job⟩“ ergibt sich von selbst, oder …
Verschiedene Skriptbefehle unterstützen unterschiedliche Dokumentationsstile (Übersicht: mdoccheat.pdf).

c+k-Dateien werden mit makedoc nicht direkt eingelesen.
Die Hauptdatei

  1. erzeugt aus (je)der c+k-Datei eine Dokumentationsversion („.txt→.tex“, Einfügen von „Listing-Wrappern“, Zeichenkettenersetzungen für Gliederung und typografische Zeichen, dazu Datei mdoccorr.cfg/mdoccorr.pdf,
  2. liest und setzt die erzeugte Datei dann als .tex.
Genauer …

Dokumentationslauf

[Genauer] … kompiliere ich typischerweise die Dokumentation
  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...)

  1. für Dokumentationsvorverarbeitung Einlesen als „reinen Text“ (\dospecials „other“)
  2. \PatternCodes für Ersetzungsregeln anzupassen
  3. blog.sty (morehype-Bündel) nutzt dagegen „minimale“ TeX-Syntax, expandiert Makros zu HTML-Code (Hauptdatei „makehtml.tex“ o. ä. wandelt ⟨job⟩.tex zeilenweise in ⟨job⟩.html um).

Teil 10:
HTML erzeugen

Nutzen von HTML (vs. PDF)

  1. Internetauftritt/CMS
  2. „Elektronischer Zettelkasten“
    1. Querverweise
    2. gegliederte/kommentierte Link-Sammlungen
    3. Hervorhebung von Stichwörtern in Texten aus anderen Formaten (Xpad/Tomboy)
  3. besserer Lesefluss ohne Seitenumbrüche,
    ohne problematische Zeilenumbrüche
  4. keine Arbeit mit Umbrüchen
    (außer gedankliche Gliederung)
  5. Bildschirmfläche voll nutzen

HTML-Erzeugung – Alternativen

HTML und PDF aus selber Quelle?

  1. \labelsection etc. – „htmlTeX“
    (HTML regt zu Makros an, die auch für PDF-Erzeugung interessant wären,
    angefangen mit logischer Auszeichnung wie <code>/\code, <strong>/\strong.)
  2. texlinks.sty (morehype-Bündel)
    bietet Beispiele für Makros, die gleichermaßen
    • für hyperref/PDF
    • wie für HTML-Erzeugung mit blog.sty
    geeignet sind (fußen auf wenigen „Pivot/Angelpunkt“-Makros wie etwa \href,
    nur ein solches für hyperref vs. blog unterschiedlich zu definieren).

Was (zur Zeit) nicht geht

(weil Makros nur expandiert werden, vgl. Funktionale Programmierung): Zähler, optionale Argumente, ∗-Varianten, \unskip, \verb; \begin öffnet keine Gruppe für lokale Einstellungen, solche können ohnehin nicht vorgenommen werden. („Was man an TeX hat.“) – Mathe: Brüche/Wurzeln? vgl. dazu TtH.
Ausweg irgendwann: besondere Behandlung von Zeilen, die bestimmte einzelne Makros enthalten, wie etwa \EXECUTE{⟨einstellungen⟩}, \begin, \end.
Wandlung zeilenweise erschwert auch Verteilen von Makroargumenten über mehrere Zeilen („Klammer rechtzeitig öffnen“). Künftige Alternativen wären catchfile oder „bis zur nächsten leeren Zeile am Stück“ einlesen.

Dank

  • blog.sty wurde (2010) mittelbar/teilweise durch die DFG unterstützt
  • den Einstieg in HTML verdanke ich in erster Linie meinem Bruder, Rainer Lück (www.webdesign-bu.de)
  • fürs Zuhören [Zuschauen]
und nachträglich:
  • an Uwe Ziegenhagen (u. a.) für Hinweis auf
    Markdown und pandoc,
  • an Bernd Raichle für Hinweis auf Kees van der Laans (NTG) Arbeiten über „minimales Markup“,
  • „technischen Helfern“ (Kabel/xrandr)!

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.