uwe_lueck > texmap > dantev45-992-exact-frame – 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)!