`uwe_lueck` `>` `texmap` `>` `dantev45-992-com` – 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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 0:

Über den Vortrag

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 …“

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Vortragstitel bedeutet (II):

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Vortragstitel bedeutet (III):

… was haben Paketdokumentation und HTML-Erzeugung miteinander zu tun??
(– Zu HTML-Paketdokumentationen
habe ich es noch nicht gebracht …)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 …)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 …)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Status

nicht richtig fertig, zu umfangreich, hasten, überspringen

kein Experte in Typografie, HTML, CSS

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 1:

„Markup“ oder so

(Begriffsklärung – oder so)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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]

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## „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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 2:

Typografische Zeichen mit TeX/LaTeX

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Typografische Zeichen mit TeX/LaTeX

Zeichen | realisiert durch
Auslassungszeichen | `\dots`
Gedanken-/„bis“-Strich | „`---`“ (englisch), „`--`“ – Ligaturen
(Doppelte) Anführungszeichen | Englisch: 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 ]

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 „`...`“?)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 ]

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `.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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 3:

„Formatierung“

(Auszeichnung, Wikipedia)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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`)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 4:

Implementierung
„minimalen Markups“
„mit TeX allein“

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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“

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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“.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## „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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `wiki.sty`s „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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## (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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 5:

Dokumentation von LaTeX-Paketen

(mit `nicetext`)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 6:

`niceverb.sty`

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `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}`

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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}|}|

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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⟩}`

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Ä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).

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 7:

„Kommentar“

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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“ …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 8:

Methoden Kommentar „auszublenden“

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## „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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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 …)

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 9:

„Darstellung“ des Kommentars

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## „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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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}`).

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `\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,

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## (`\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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## „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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## „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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## „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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## `makedoc`s `\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 …

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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`.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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).

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## Teil 10:

HTML erzeugen

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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`

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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
3. für `hyperref`/PDF
4. 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).

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

## 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`)!

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X