From fede1540ce6f021bff42a29058b2a86f9f5af5e5 Mon Sep 17 00:00:00 2001
From: Karl Berry
Date: Tue, 18 Oct 2011 22:31:48 +0000
Subject: new doc package fifinddo-info (18oct11)
git-svn-id: svn://tug.org/texlive/trunk@24319 c570f23f-e606-0410-a88d-b1316a301751
---
.../doc/latex/fifinddo-info/LIESMICH.txt | 48 +
Master/texmf-dist/doc/latex/fifinddo-info/README | 51 +
.../doc/latex/fifinddo-info/dante-mv45-lueck.pdf | Bin 0 -> 152801 bytes
.../doc/latex/fifinddo-info/dantev45.htm | 3283 ++++++++++++++++++++
.../doc/latex/fifinddo-info/mdoccorr.pdf | Bin 0 -> 94625 bytes
.../variants/dantev45-1180-clean.html | 3283 ++++++++++++++++++++
.../fifinddo-info/variants/dantev45-1180-com.html | 3283 ++++++++++++++++++++
.../fifinddo-info/variants/dantev45-768-com.html | 3283 ++++++++++++++++++++
.../variants/dantev45-768-exact-frame.html | 3283 ++++++++++++++++++++
.../variants/dantev45-768-exact-show.html | 3283 ++++++++++++++++++++
.../variants/dantev45-768-filltype-show.html | 3283 ++++++++++++++++++++
.../fifinddo-info/variants/dantev45-992-com.html | 3283 ++++++++++++++++++++
.../variants/dantev45-992-exact-frame.html | 3283 ++++++++++++++++++++
.../fifinddo-info/variants/dantev45-992-exact.html | 3283 ++++++++++++++++++++
14 files changed, 32929 insertions(+)
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/LIESMICH.txt
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/README
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/dante-mv45-lueck.pdf
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/dantev45.htm
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/mdoccorr.pdf
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-clean.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-com.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-com.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-frame.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-show.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-filltype-show.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-com.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact-frame.html
create mode 100644 Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact.html
(limited to 'Master/texmf-dist/doc')
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/LIESMICH.txt b/Master/texmf-dist/doc/latex/fifinddo-info/LIESMICH.txt
new file mode 100644
index 00000000000..e1553e28166
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/LIESMICH.txt
@@ -0,0 +1,48 @@
+
+ LIESMICH.txt fuer `fifinddo-info'
+ (C) Uwe Lueck 2011/10/16
+
+
+Die Datei `dantev45.htm' ist eine "HTML-Beamer-Praesentation" ueber
+
+ "Paketdokumentation und Webseitenpflege (HTML-Erzeugung)
+ mit (`niceverb.sty' und) `fifinddo.sty'"
+
+- ueberarbeitete Fassung meines Vortrags auf der
+DANTE-Herbsttagung 2011, zu oeffnen mit einem Webbrowser.
+In der zweiten Zeile mit "START" sollte die Gebrauchsanleitung
+zu finden sein.
+
+`dante-mv45-lueck.pdf' ist ausserdem eine Zusammenfassung.
+
+`dantev45.htm' und die uebrigen Dateien dienen auch als Beispiel
+fuer das im `morehype'-Buendel (http://ctan.org/pkg/morehype)
+enthaltene und dort in `blog.pdf' beschriebene Paket `blogdot.sty'
+fuer "HTML-Beamer-Praesentationen".
+
+Im Verzeichnis `variants' finden sich Versionen der Datei fuer
+unterschiedliche Bildschirme und Browser. Die Zahl im Dateinamen
+ist die Breite der "Folien" in Pixeln ("geraten" fuer
+Bildschirmbreiten 800 und ca. 1200). "exact" bedeutet genaue
+Abstimmung fuer die angegebene Breite und einen Schirm der Hoehe
+600 fuer die Browser Firefox, Google Chrome und Opera. "com"
+sollte auch mit Internet Explorer und breiteren Schirmen gut
+aussehen und (halbwegs) funktionieren. "frame" sollte auf einem
+groesseren Schirm die Abmessungen fuer einen kleineren durch einen
+Rahmen sichtbar machen. "show" zeigt die Randgrenzen und (evtl.)
+den sonst unsichtbaren Fuelltext (fuer "filltype" und "com",
+siehe `\FillBlogDotTypeArea' in der Dokumentation von `blogdot').
+"clean" bedeutet, dass kein Fuelltext verwendet wird.
+
+Die Dateien unterliegen der LaTeX Project Public License ab v1.3c:
+
+ http://www.latex-project.org/lppl.txt
+
+Eine TDS-Version ist
+
+ http://mirror.ctan.org/install/info/fifinddo.tds.zip
+
+Bemerkungen erbitte ich unter
+
+ http://www.contact-ednotes.sty.de.vu
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/README b/Master/texmf-dist/doc/latex/fifinddo-info/README
new file mode 100644
index 00000000000..732a80890c4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/README
@@ -0,0 +1,51 @@
+
+ README for `fifinddo-info'
+ (C) Uwe Lueck 2011/10/16
+
+Here you find (i) files (in `source/') that demonstrate making
+an "HTML beamer presentation" with `blogdot.sty' from the
+`morehype' bundle (described in `blog.pdf'), (ii) a German
+sketch of package documentation and HTML generation based on
+`fifinddo.sty' (`nicetext' bundle): `dantev45.htm'
+(cf. `LIESMICH.txt').
+
+TRYING the presentation: open `dantev45.htm' with a browser,
+click on "START", later click on screen bottom for next view
+or on lower right corner of screen for the overview. With MSIE
+however, this does not work, find something to click at right
+below the text.
+
+VARIANTS: dantev45.htm is a "compromise" version of the
+presentation. Directory `variants' contains versions for different
+screens and browsers, exemplifying "recompilation" according to
+the `blogdot' documentation.
+
+KEYWORDs: beamer presentations, literate macro programming, HTML;
+font selection, lists, punctuation, quotation, spacing,
+text decoration computer text/verbatim text, font selection,
+lists, punctuation, quotation, spacing, text decoration,
+verbatim text
+
+The files can be redistributed and/or modified under the terms
+of the LaTeX Project Public License; either version 1.3c of the
+License, or any later version, see
+
+ http://www.latex-project.org/lppl.txt
+
+We did our best to help you, but there is NO WARRANTY.
+
+The CTAN directory `/info/fifinddo/' is author-maintained in the
+sense of this license.
+
+The latest public version of the package is available at
+
+ http://mirror.ctan.org/info/fifinddo/
+
+A TDS version of the package is available as
+
+ http://mirror.ctan.org/install/info/fifinddo.tds.zip
+
+Please report bugs, problems, and suggestions via
+
+ http://www.contact-ednotes.sty.de.vu
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/dante-mv45-lueck.pdf b/Master/texmf-dist/doc/latex/fifinddo-info/dante-mv45-lueck.pdf
new file mode 100644
index 00000000000..7f4710a8a06
Binary files /dev/null and b/Master/texmf-dist/doc/latex/fifinddo-info/dante-mv45-lueck.pdf differ
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/dantev45.htm b/Master/texmf-dist/doc/latex/fifinddo-info/dantev45.htm
new file mode 100644
index 00000000000..e7a589dbbc5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/dantev45.htm
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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
]
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Von .txt zu .tex
+
+Um reinen Text in LaTeX-Input
+(für LaTeX-Qualität) umzuwandeln, muss man normalerweise
+Folgendes ergänzen/ändern:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Zwecke des Kommentars
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Feinheiten des „Ausblendens“ von Kommentar
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+„smartes“ \DocInput
+
+– Algorithmus klar:
+ – nach Zeile
+mit „% “ vor „ohne“
+„\begin{macrocode} “,
+ – im umgekehrten Fall „\end{macrocode} “
+einfügen –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/mdoccorr.pdf b/Master/texmf-dist/doc/latex/fifinddo-info/mdoccorr.pdf
new file mode 100644
index 00000000000..e6e2ac95828
Binary files /dev/null and b/Master/texmf-dist/doc/latex/fifinddo-info/mdoccorr.pdf differ
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-clean.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-clean.html
new file mode 100644
index 00000000000..e14faae57cf
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-clean.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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-15
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 0:
+
+Über den Vortrag
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - Gebrauchsanleitung/Syntaxbeschreibung für Nutzer:
+
„Tippt man
+
+\foo∗[〈opt-arg〉]{〈mand-arg〉} ,
+
+so erhält man …“
+
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+
+ - „Webseitenpflege“
-
+– „hochtrabend“, zunächst bloß: HTML-Erzeugung
+–
+
+
+ - Internetauftritt (?
+CMS?
+– ja …)
+
+ - bequeme Textformat-Alternative zu PDF …
+
+(Notizen zu Links,
+Beamer-Präsentation …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+… was haben Paketdokumentation und
+HTML-Erzeugung miteinander zu tun??
+
+(– Zu HTML-Paketdokumentationen
+ habe ich es noch nicht gebracht …)
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortrag interessant …
+
+
+
+ - wenn man als Makroprogrammierer
+
doc.sty und docstrip.tex
+(„.dtx …“)
+zu aufwändig findet …
+
+ - wenn man HTML schätzt und PDF
+vermeiden möchte …
+
+ - wenn man Makro-Denksport mag
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Inhaltliche Motive
+
+
+
+ - „minimales Markup“,
+„syntaktischer Zucker“
+(LaTeX-Qualität
+möglichst ohne LaTeX-Befehle)
+
+ - „Missbrauch“ von TeX
+als „Skriptsprache“
+
+(„mit TeX muss und will ich keine andere Sprache lernen“;
+statt PDF-Schriftsatz
+– wie docstrip )
+
+ - kleine(?), einfache(?), experimentelle(!),
+(„schrullige“,) gerade eigenen (U. L.) Bedürfnissen
+entsprechende Alternativen zu existierenden
+„professionelleren“ Paketen
+(Erfolge – Scheitern …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Persönliche Motive
+
+(bemerkenswerte Mischung aus:)
+
+
+ - gespannt auf Kommentare
zu meinen Paketen,
+
+ - Vortrag soll aber auch über „Konkurrenzprodukte“ informieren
+
+ - Irrtümer? Hinweise?
+– Terminologie erst in letzten zwei Wochen
+„erarbeitet“
+
+ - 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
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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ü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 ]
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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 –
+
+
+ - weg mit Backslashs,
+englischen Befehlen und
+geschwungenen Klammern!
+
+ - überhaupt möglichst wenig Code-Zeichen
+
+ - Zeichen möglichst intuitiv
+
+ - … am besten so aussehen wie Ergebnis
+
+ - – „ASCII-WYSIWYG“
+– vs.
unisugar mit Unicode …
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen – Bewertung
+
+– von TeX/LaTeX:
+
+
+ - TeX-Ligaturen schon ganz gut!
+
+ - aktive Zeichen … na ja …
+„
~ “ besser als „ “,
+aber …
+
+ \dots schon übel …
+(warum nicht Ligatur „... “?)
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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:
+
+
+ txt2latex kleines
+Perl-Skript,
+wandelt gerade TeXs spezielle Zeichen
+(„& “ etc.), „... “
+und doppelte/einzelne Anführungszeichen um
+(s. Datei
+txt2latex )
+
+ txt2tex – Perl, erzeugt tatsächlich
+LaTeX-Formatierung (Paketnamen „verkehrt“!)
+
+ EasyLaTeX ähnlich oder mehr,
+GUI(?), Ideen aus Wiki…-Markup;
+zuletzt 2004 (README 2009 eher CTAN-Hand)
+
+ 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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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)
+
+
+ - Die Pakete
stringstrings (Steven Segletes),
+xstring (Christian Tellechea, e-TeX )
+und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen
+„auf höchstem Niveau“.
+
+ - String-Funktionen finden sich auch in
+
datatool (Nicola Talbot),
+coolstr (Nick Setzer) und
+texapi (Paul Isambert).
+
+ - 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
+
+
+ - statt
\...section{...} einrahmende
+Gleichheitszeichen-Folgen verwenden,
+
+ - Kursiv- und Fettschrift
+mit Folgen von
+„Apostroph-Ersatzzeichen“
+(ASCII-Code 39) ein- und abschalten,
+
+ - Listen und Blockzitate
+aus Menschen- oder Programmiersprache durch
+spezielle Zeilenanfänge anzeigen.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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
+
+
+
+ - Schriftkodierung
+durch Folgen von Apostrophen finde ich
+nicht intuitiv genug,
+um andere Paketbearbeiter damit konfrontieren zu wollen,
+[Publikum (U. Z.): Markdown!]
+
+ - … sie ist gegenwärtig auch inkompatibel mit der
+Verwendung „aktiver Apostrophe“ in
+
niceverb.sty .
+
+ - Überschriftenkodierung durch
+Gleichheitszeichen verwende ich bisher in der
+(MA)-Implementierung von
makedoc.sty .
+
+ - Dass Einrücken eine
+verbatim-Umgebung auslöst, finde ich
+unpraktisch.
+
+ - Im Quelltext sehe ich lieber „1.“, „2.“,
+…als „
# “.
+
+[Publikum: Markdown!]
+
+ - Unnummerierte Listen mit
* sind
+OK,
+habe ich mal für „Fremddokumentation“ eingesetzt.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 6:
+
+niceverb.sty
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+niceverb.sty – „Schriftauszeichnung“
+„Fortsetzung“ der
+Wikipedia-Schriftauszeichnung:
+
+
+ - Umrahmung mit einfachen Apostroph-Ersatzzeichen
+(
’nicetext’ )
+wirkt wie \textsf
+– für Paketnamen.
+
+ - 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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+aktive Zeichen → Probleme …
+Auswege …
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Ähnliche Pakete anderer Autoren
+
+
+
+ niceverb.sty ist wesentlich inspiriert
+durch die Dokumentationsmethode Stephan Böttchers
+in lineno.sty .
+
+ - Ähnliche Funktionalität liefert auch
+
ltxguide.cls für die „LaTeX-Guides“.
+
+ - Die bequeme Syntaxbeschreibung
+gibt es
+(„mittlerweile“) auch in Martin Scharrers
+
ydoc .
+
+ 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
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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“
+
+
+ - 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.
+
+ - Kommentar entsprechend
+„reiner ASCII-Text“,
+weder „typografische Zeichen“ noch Auszeichnung.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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
+
+
+ - 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 /pdf ,
+
+ - liest und setzt die erzeugte Datei dann als
+
.tex .
+
+
+Genauer …
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - Dennoch gelungene „Fremddokumentationen“:
+arseneau.pdf ,
+substr.pdf .
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vorteile und Problematik der Zeichenkategorien (\catcode... )
+
+
+
+ - für Dokumentationsvorverarbeitung
+Einlesen als „reinen Text“
+(
\dospecials „other “)
+
+ \PatternCodes für Ersetzungsregeln
+anzupassen
+
+ 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)
+
+
+
+ - Internetauftritt/CMS
+
+ - „Elektronischer Zettelkasten“
+
+ - Querverweise
+
+ - gegliederte/kommentierte Link-Sammlungen
+
+ - Hervorhebung von Stichwörtern
+in Texten aus anderen Formaten
+
+(Xpad/Tomboy)
+
+
+
+ - besserer Lesefluss ohne Seitenumbrüche,
+ohne problematische Zeilenumbrüche
+
+ - keine Arbeit mit Umbrüchen
(außer gedankliche Gliederung)
+
+ - Bildschirmfläche voll nutzen
+
+ |
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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?
+
+
+
+
+ \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 .)
+
+
+ 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 )!
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-com.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-com.html
new file mode 100644
index 00000000000..2acb15f837e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-1180-com.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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
]
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Von .txt zu .tex
+
+Um reinen Text in LaTeX-Input
+(für LaTeX-Qualität) umzuwandeln, muss man normalerweise
+Folgendes ergänzen/ändern:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Zwecke des Kommentars
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Feinheiten des „Ausblendens“ von Kommentar
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+„smartes“ \DocInput
+
+– Algorithmus klar:
+ – nach Zeile
+mit „% “ vor „ohne“
+„\begin{macrocode} “,
+ – im umgekehrten Fall „\end{macrocode} “
+einfügen –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-com.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-com.html
new file mode 100644
index 00000000000..e7a589dbbc5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-com.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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
]
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Von .txt zu .tex
+
+Um reinen Text in LaTeX-Input
+(für LaTeX-Qualität) umzuwandeln, muss man normalerweise
+Folgendes ergänzen/ändern:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Zwecke des Kommentars
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Feinheiten des „Ausblendens“ von Kommentar
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+„smartes“ \DocInput
+
+– Algorithmus klar:
+ – nach Zeile
+mit „% “ vor „ohne“
+„\begin{macrocode} “,
+ – im umgekehrten Fall „\end{macrocode} “
+einfügen –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-frame.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-frame.html
new file mode 100644
index 00000000000..f5b3e2c0a77
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-frame.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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-15
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 0:
+
+Über den Vortrag
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - Gebrauchsanleitung/Syntaxbeschreibung für Nutzer:
+
„Tippt man
+
+\foo∗[〈opt-arg〉]{〈mand-arg〉} ,
+
+so erhält man …“
+
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+
+ - „Webseitenpflege“
-
+– „hochtrabend“, zunächst bloß: HTML-Erzeugung
+–
+
+
+ - Internetauftritt (?
+CMS?
+– ja …)
+
+ - bequeme Textformat-Alternative zu PDF …
+
+(Notizen zu Links,
+Beamer-Präsentation …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+… was haben Paketdokumentation und
+HTML-Erzeugung miteinander zu tun??
+
+(– Zu HTML-Paketdokumentationen
+ habe ich es noch nicht gebracht …)
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortrag interessant …
+
+
+
+ - wenn man als Makroprogrammierer
+
doc.sty und docstrip.tex
+(„.dtx …“)
+zu aufwändig findet …
+
+ - wenn man HTML schätzt und PDF
+vermeiden möchte …
+
+ - wenn man Makro-Denksport mag
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Inhaltliche Motive
+
+
+
+ - „minimales Markup“,
+„syntaktischer Zucker“
+(LaTeX-Qualität
+möglichst ohne LaTeX-Befehle)
+
+ - „Missbrauch“ von TeX
+als „Skriptsprache“
+
+(„mit TeX muss und will ich keine andere Sprache lernen“;
+statt PDF-Schriftsatz
+– wie docstrip )
+
+ - kleine(?), einfache(?), experimentelle(!),
+(„schrullige“,) gerade eigenen (U. L.) Bedürfnissen
+entsprechende Alternativen zu existierenden
+„professionelleren“ Paketen
+(Erfolge – Scheitern …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Persönliche Motive
+
+(bemerkenswerte Mischung aus:)
+
+
+ - gespannt auf Kommentare
zu meinen Paketen,
+
+ - Vortrag soll aber auch über „Konkurrenzprodukte“ informieren
+
+ - Irrtümer? Hinweise?
+– Terminologie erst in letzten zwei Wochen
+„erarbeitet“
+
+ - 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
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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ü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 ]
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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 –
+
+
+ - weg mit Backslashs,
+englischen Befehlen und
+geschwungenen Klammern!
+
+ - überhaupt möglichst wenig Code-Zeichen
+
+ - Zeichen möglichst intuitiv
+
+ - … am besten so aussehen wie Ergebnis
+
+ - – „ASCII-WYSIWYG“
+– vs.
unisugar mit Unicode …
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen – Bewertung
+
+– von TeX/LaTeX:
+
+
+ - TeX-Ligaturen schon ganz gut!
+
+ - aktive Zeichen … na ja …
+„
~ “ besser als „ “,
+aber …
+
+ \dots schon übel …
+(warum nicht Ligatur „... “?)
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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:
+
+
+ txt2latex kleines
+Perl-Skript,
+wandelt gerade TeXs spezielle Zeichen
+(„& “ etc.), „... “
+und doppelte/einzelne Anführungszeichen um
+(s. Datei
+txt2latex )
+
+ txt2tex – Perl, erzeugt tatsächlich
+LaTeX-Formatierung (Paketnamen „verkehrt“!)
+
+ EasyLaTeX ähnlich oder mehr,
+GUI(?), Ideen aus Wiki…-Markup;
+zuletzt 2004 (README 2009 eher CTAN-Hand)
+
+ 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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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)
+
+
+ - Die Pakete
stringstrings (Steven Segletes),
+xstring (Christian Tellechea, e-TeX )
+und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen
+„auf höchstem Niveau“.
+
+ - String-Funktionen finden sich auch in
+
datatool (Nicola Talbot),
+coolstr (Nick Setzer) und
+texapi (Paul Isambert).
+
+ - 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
+
+
+ - statt
\...section{...} einrahmende
+Gleichheitszeichen-Folgen verwenden,
+
+ - Kursiv- und Fettschrift
+mit Folgen von
+„Apostroph-Ersatzzeichen“
+(ASCII-Code 39) ein- und abschalten,
+
+ - Listen und Blockzitate
+aus Menschen- oder Programmiersprache durch
+spezielle Zeilenanfänge anzeigen.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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
+
+
+
+ - Schriftkodierung
+durch Folgen von Apostrophen finde ich
+nicht intuitiv genug,
+um andere Paketbearbeiter damit konfrontieren zu wollen,
+[Publikum (U. Z.): Markdown!]
+
+ - … sie ist gegenwärtig auch inkompatibel mit der
+Verwendung „aktiver Apostrophe“ in
+
niceverb.sty .
+
+ - Überschriftenkodierung durch
+Gleichheitszeichen verwende ich bisher in der
+(MA)-Implementierung von
makedoc.sty .
+
+ - Dass Einrücken eine
+verbatim-Umgebung auslöst, finde ich
+unpraktisch.
+
+ - Im Quelltext sehe ich lieber „1.“, „2.“,
+…als „
# “.
+
+[Publikum: Markdown!]
+
+ - Unnummerierte Listen mit
* sind
+OK,
+habe ich mal für „Fremddokumentation“ eingesetzt.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 6:
+
+niceverb.sty
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+niceverb.sty – „Schriftauszeichnung“
+„Fortsetzung“ der
+Wikipedia-Schriftauszeichnung:
+
+
+ - Umrahmung mit einfachen Apostroph-Ersatzzeichen
+(
’nicetext’ )
+wirkt wie \textsf
+– für Paketnamen.
+
+ - 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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+aktive Zeichen → Probleme …
+Auswege …
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Ähnliche Pakete anderer Autoren
+
+
+
+ niceverb.sty ist wesentlich inspiriert
+durch die Dokumentationsmethode Stephan Böttchers
+in lineno.sty .
+
+ - Ähnliche Funktionalität liefert auch
+
ltxguide.cls für die „LaTeX-Guides“.
+
+ - Die bequeme Syntaxbeschreibung
+gibt es
+(„mittlerweile“) auch in Martin Scharrers
+
ydoc .
+
+ 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
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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“
+
+
+ - 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.
+
+ - Kommentar entsprechend
+„reiner ASCII-Text“,
+weder „typografische Zeichen“ noch Auszeichnung.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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
+
+
+ - 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 /pdf ,
+
+ - liest und setzt die erzeugte Datei dann als
+
.tex .
+
+
+Genauer …
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - Dennoch gelungene „Fremddokumentationen“:
+arseneau.pdf ,
+substr.pdf .
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vorteile und Problematik der Zeichenkategorien (\catcode... )
+
+
+
+ - für Dokumentationsvorverarbeitung
+Einlesen als „reinen Text“
+(
\dospecials „other “)
+
+ \PatternCodes für Ersetzungsregeln
+anzupassen
+
+ 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)
+
+
+
+ - Internetauftritt/CMS
+
+ - „Elektronischer Zettelkasten“
+
+ - Querverweise
+
+ - gegliederte/kommentierte Link-Sammlungen
+
+ - Hervorhebung von Stichwörtern
+in Texten aus anderen Formaten
+
+(Xpad/Tomboy)
+
+
+
+ - besserer Lesefluss ohne Seitenumbrüche,
+ohne problematische Zeilenumbrüche
+
+ - keine Arbeit mit Umbrüchen
(außer gedankliche Gliederung)
+
+ - Bildschirmfläche voll nutzen
+
+ |
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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?
+
+
+
+
+ \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 .)
+
+
+ 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 )!
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-show.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-show.html
new file mode 100644
index 00000000000..7a2281e3806
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-exact-show.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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-15
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 0:
+
+Über den Vortrag
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - Gebrauchsanleitung/Syntaxbeschreibung für Nutzer:
+
„Tippt man
+
+\foo∗[〈opt-arg〉]{〈mand-arg〉} ,
+
+so erhält man …“
+
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+
+ - „Webseitenpflege“
-
+– „hochtrabend“, zunächst bloß: HTML-Erzeugung
+–
+
+
+ - Internetauftritt (?
+CMS?
+– ja …)
+
+ - bequeme Textformat-Alternative zu PDF …
+
+(Notizen zu Links,
+Beamer-Präsentation …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+… was haben Paketdokumentation und
+HTML-Erzeugung miteinander zu tun??
+
+(– Zu HTML-Paketdokumentationen
+ habe ich es noch nicht gebracht …)
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortrag interessant …
+
+
+
+ - wenn man als Makroprogrammierer
+
doc.sty und docstrip.tex
+(„.dtx …“)
+zu aufwändig findet …
+
+ - wenn man HTML schätzt und PDF
+vermeiden möchte …
+
+ - wenn man Makro-Denksport mag
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Inhaltliche Motive
+
+
+
+ - „minimales Markup“,
+„syntaktischer Zucker“
+(LaTeX-Qualität
+möglichst ohne LaTeX-Befehle)
+
+ - „Missbrauch“ von TeX
+als „Skriptsprache“
+
+(„mit TeX muss und will ich keine andere Sprache lernen“;
+statt PDF-Schriftsatz
+– wie docstrip )
+
+ - kleine(?), einfache(?), experimentelle(!),
+(„schrullige“,) gerade eigenen (U. L.) Bedürfnissen
+entsprechende Alternativen zu existierenden
+„professionelleren“ Paketen
+(Erfolge – Scheitern …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Persönliche Motive
+
+(bemerkenswerte Mischung aus:)
+
+
+ - gespannt auf Kommentare
zu meinen Paketen,
+
+ - Vortrag soll aber auch über „Konkurrenzprodukte“ informieren
+
+ - Irrtümer? Hinweise?
+– Terminologie erst in letzten zwei Wochen
+„erarbeitet“
+
+ - 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
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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ü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 ]
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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 –
+
+
+ - weg mit Backslashs,
+englischen Befehlen und
+geschwungenen Klammern!
+
+ - überhaupt möglichst wenig Code-Zeichen
+
+ - Zeichen möglichst intuitiv
+
+ - … am besten so aussehen wie Ergebnis
+
+ - – „ASCII-WYSIWYG“
+– vs.
unisugar mit Unicode …
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen – Bewertung
+
+– von TeX/LaTeX:
+
+
+ - TeX-Ligaturen schon ganz gut!
+
+ - aktive Zeichen … na ja …
+„
~ “ besser als „ “,
+aber …
+
+ \dots schon übel …
+(warum nicht Ligatur „... “?)
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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:
+
+
+ txt2latex kleines
+Perl-Skript,
+wandelt gerade TeXs spezielle Zeichen
+(„& “ etc.), „... “
+und doppelte/einzelne Anführungszeichen um
+(s. Datei
+txt2latex )
+
+ txt2tex – Perl, erzeugt tatsächlich
+LaTeX-Formatierung (Paketnamen „verkehrt“!)
+
+ EasyLaTeX ähnlich oder mehr,
+GUI(?), Ideen aus Wiki…-Markup;
+zuletzt 2004 (README 2009 eher CTAN-Hand)
+
+ 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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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)
+
+
+ - Die Pakete
stringstrings (Steven Segletes),
+xstring (Christian Tellechea, e-TeX )
+und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen
+„auf höchstem Niveau“.
+
+ - String-Funktionen finden sich auch in
+
datatool (Nicola Talbot),
+coolstr (Nick Setzer) und
+texapi (Paul Isambert).
+
+ - 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
+
+
+ - statt
\...section{...} einrahmende
+Gleichheitszeichen-Folgen verwenden,
+
+ - Kursiv- und Fettschrift
+mit Folgen von
+„Apostroph-Ersatzzeichen“
+(ASCII-Code 39) ein- und abschalten,
+
+ - Listen und Blockzitate
+aus Menschen- oder Programmiersprache durch
+spezielle Zeilenanfänge anzeigen.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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
+
+
+
+ - Schriftkodierung
+durch Folgen von Apostrophen finde ich
+nicht intuitiv genug,
+um andere Paketbearbeiter damit konfrontieren zu wollen,
+[Publikum (U. Z.): Markdown!]
+
+ - … sie ist gegenwärtig auch inkompatibel mit der
+Verwendung „aktiver Apostrophe“ in
+
niceverb.sty .
+
+ - Überschriftenkodierung durch
+Gleichheitszeichen verwende ich bisher in der
+(MA)-Implementierung von
makedoc.sty .
+
+ - Dass Einrücken eine
+verbatim-Umgebung auslöst, finde ich
+unpraktisch.
+
+ - Im Quelltext sehe ich lieber „1.“, „2.“,
+…als „
# “.
+
+[Publikum: Markdown!]
+
+ - Unnummerierte Listen mit
* sind
+OK,
+habe ich mal für „Fremddokumentation“ eingesetzt.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 6:
+
+niceverb.sty
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+niceverb.sty – „Schriftauszeichnung“
+„Fortsetzung“ der
+Wikipedia-Schriftauszeichnung:
+
+
+ - Umrahmung mit einfachen Apostroph-Ersatzzeichen
+(
’nicetext’ )
+wirkt wie \textsf
+– für Paketnamen.
+
+ - 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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+aktive Zeichen → Probleme …
+Auswege …
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Ähnliche Pakete anderer Autoren
+
+
+
+ niceverb.sty ist wesentlich inspiriert
+durch die Dokumentationsmethode Stephan Böttchers
+in lineno.sty .
+
+ - Ähnliche Funktionalität liefert auch
+
ltxguide.cls für die „LaTeX-Guides“.
+
+ - Die bequeme Syntaxbeschreibung
+gibt es
+(„mittlerweile“) auch in Martin Scharrers
+
ydoc .
+
+ 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
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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“
+
+
+ - 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.
+
+ - Kommentar entsprechend
+„reiner ASCII-Text“,
+weder „typografische Zeichen“ noch Auszeichnung.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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
+
+
+ - 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 /pdf ,
+
+ - liest und setzt die erzeugte Datei dann als
+
.tex .
+
+
+Genauer …
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - Dennoch gelungene „Fremddokumentationen“:
+arseneau.pdf ,
+substr.pdf .
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vorteile und Problematik der Zeichenkategorien (\catcode... )
+
+
+
+ - für Dokumentationsvorverarbeitung
+Einlesen als „reinen Text“
+(
\dospecials „other “)
+
+ \PatternCodes für Ersetzungsregeln
+anzupassen
+
+ 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)
+
+
+
+ - Internetauftritt/CMS
+
+ - „Elektronischer Zettelkasten“
+
+ - Querverweise
+
+ - gegliederte/kommentierte Link-Sammlungen
+
+ - Hervorhebung von Stichwörtern
+in Texten aus anderen Formaten
+
+(Xpad/Tomboy)
+
+
+
+ - besserer Lesefluss ohne Seitenumbrüche,
+ohne problematische Zeilenumbrüche
+
+ - keine Arbeit mit Umbrüchen
(außer gedankliche Gliederung)
+
+ - Bildschirmfläche voll nutzen
+
+ |
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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?
+
+
+
+
+ \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 .)
+
+
+ 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 )!
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-filltype-show.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-filltype-show.html
new file mode 100644
index 00000000000..0894946b75d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-768-filltype-show.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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
]
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Von .txt zu .tex
+
+Um reinen Text in LaTeX-Input
+(für LaTeX-Qualität) umzuwandeln, muss man normalerweise
+Folgendes ergänzen/ändern:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Zwecke des Kommentars
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Feinheiten des „Ausblendens“ von Kommentar
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+„smartes“ \DocInput
+
+– Algorithmus klar:
+ – nach Zeile
+mit „% “ vor „ohne“
+„\begin{macrocode} “,
+ – im umgekehrten Fall „\end{macrocode} “
+einfügen –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-com.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-com.html
new file mode 100644
index 00000000000..d021eeb03a3
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-com.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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
]
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Von .txt zu .tex
+
+Um reinen Text in LaTeX-Input
+(für LaTeX-Qualität) umzuwandeln, muss man normalerweise
+Folgendes ergänzen/ändern:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Zwecke des Kommentars
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Feinheiten des „Ausblendens“ von Kommentar
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+„smartes“ \DocInput
+
+– Algorithmus klar:
+ – nach Zeile
+mit „% “ vor „ohne“
+„\begin{macrocode} “,
+ – im umgekehrten Fall „\end{macrocode} “
+einfügen –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - 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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+ | |
|
+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 | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact-frame.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact-frame.html
new file mode 100644
index 00000000000..3628a857586
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact-frame.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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-15
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 0:
+
+Über den Vortrag
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - Gebrauchsanleitung/Syntaxbeschreibung für Nutzer:
+
„Tippt man
+
+\foo∗[〈opt-arg〉]{〈mand-arg〉} ,
+
+so erhält man …“
+
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+
+ - „Webseitenpflege“
-
+– „hochtrabend“, zunächst bloß: HTML-Erzeugung
+–
+
+
+ - Internetauftritt (?
+CMS?
+– ja …)
+
+ - bequeme Textformat-Alternative zu PDF …
+
+(Notizen zu Links,
+Beamer-Präsentation …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+… was haben Paketdokumentation und
+HTML-Erzeugung miteinander zu tun??
+
+(– Zu HTML-Paketdokumentationen
+ habe ich es noch nicht gebracht …)
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortrag interessant …
+
+
+
+ - wenn man als Makroprogrammierer
+
doc.sty und docstrip.tex
+(„.dtx …“)
+zu aufwändig findet …
+
+ - wenn man HTML schätzt und PDF
+vermeiden möchte …
+
+ - wenn man Makro-Denksport mag
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Inhaltliche Motive
+
+
+
+ - „minimales Markup“,
+„syntaktischer Zucker“
+(LaTeX-Qualität
+möglichst ohne LaTeX-Befehle)
+
+ - „Missbrauch“ von TeX
+als „Skriptsprache“
+
+(„mit TeX muss und will ich keine andere Sprache lernen“;
+statt PDF-Schriftsatz
+– wie docstrip )
+
+ - kleine(?), einfache(?), experimentelle(!),
+(„schrullige“,) gerade eigenen (U. L.) Bedürfnissen
+entsprechende Alternativen zu existierenden
+„professionelleren“ Paketen
+(Erfolge – Scheitern …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Persönliche Motive
+
+(bemerkenswerte Mischung aus:)
+
+
+ - gespannt auf Kommentare
zu meinen Paketen,
+
+ - Vortrag soll aber auch über „Konkurrenzprodukte“ informieren
+
+ - Irrtümer? Hinweise?
+– Terminologie erst in letzten zwei Wochen
+„erarbeitet“
+
+ - 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
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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ü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 ]
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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 –
+
+
+ - weg mit Backslashs,
+englischen Befehlen und
+geschwungenen Klammern!
+
+ - überhaupt möglichst wenig Code-Zeichen
+
+ - Zeichen möglichst intuitiv
+
+ - … am besten so aussehen wie Ergebnis
+
+ - – „ASCII-WYSIWYG“
+– vs.
unisugar mit Unicode …
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen – Bewertung
+
+– von TeX/LaTeX:
+
+
+ - TeX-Ligaturen schon ganz gut!
+
+ - aktive Zeichen … na ja …
+„
~ “ besser als „ “,
+aber …
+
+ \dots schon übel …
+(warum nicht Ligatur „... “?)
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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:
+
+
+ txt2latex kleines
+Perl-Skript,
+wandelt gerade TeXs spezielle Zeichen
+(„& “ etc.), „... “
+und doppelte/einzelne Anführungszeichen um
+(s. Datei
+txt2latex )
+
+ txt2tex – Perl, erzeugt tatsächlich
+LaTeX-Formatierung (Paketnamen „verkehrt“!)
+
+ EasyLaTeX ähnlich oder mehr,
+GUI(?), Ideen aus Wiki…-Markup;
+zuletzt 2004 (README 2009 eher CTAN-Hand)
+
+ 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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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)
+
+
+ - Die Pakete
stringstrings (Steven Segletes),
+xstring (Christian Tellechea, e-TeX )
+und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen
+„auf höchstem Niveau“.
+
+ - String-Funktionen finden sich auch in
+
datatool (Nicola Talbot),
+coolstr (Nick Setzer) und
+texapi (Paul Isambert).
+
+ - 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
+
+
+ - statt
\...section{...} einrahmende
+Gleichheitszeichen-Folgen verwenden,
+
+ - Kursiv- und Fettschrift
+mit Folgen von
+„Apostroph-Ersatzzeichen“
+(ASCII-Code 39) ein- und abschalten,
+
+ - Listen und Blockzitate
+aus Menschen- oder Programmiersprache durch
+spezielle Zeilenanfänge anzeigen.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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
+
+
+
+ - Schriftkodierung
+durch Folgen von Apostrophen finde ich
+nicht intuitiv genug,
+um andere Paketbearbeiter damit konfrontieren zu wollen,
+[Publikum (U. Z.): Markdown!]
+
+ - … sie ist gegenwärtig auch inkompatibel mit der
+Verwendung „aktiver Apostrophe“ in
+
niceverb.sty .
+
+ - Überschriftenkodierung durch
+Gleichheitszeichen verwende ich bisher in der
+(MA)-Implementierung von
makedoc.sty .
+
+ - Dass Einrücken eine
+verbatim-Umgebung auslöst, finde ich
+unpraktisch.
+
+ - Im Quelltext sehe ich lieber „1.“, „2.“,
+…als „
# “.
+
+[Publikum: Markdown!]
+
+ - Unnummerierte Listen mit
* sind
+OK,
+habe ich mal für „Fremddokumentation“ eingesetzt.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 6:
+
+niceverb.sty
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+niceverb.sty – „Schriftauszeichnung“
+„Fortsetzung“ der
+Wikipedia-Schriftauszeichnung:
+
+
+ - Umrahmung mit einfachen Apostroph-Ersatzzeichen
+(
’nicetext’ )
+wirkt wie \textsf
+– für Paketnamen.
+
+ - 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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+aktive Zeichen → Probleme …
+Auswege …
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Ähnliche Pakete anderer Autoren
+
+
+
+ niceverb.sty ist wesentlich inspiriert
+durch die Dokumentationsmethode Stephan Böttchers
+in lineno.sty .
+
+ - Ähnliche Funktionalität liefert auch
+
ltxguide.cls für die „LaTeX-Guides“.
+
+ - Die bequeme Syntaxbeschreibung
+gibt es
+(„mittlerweile“) auch in Martin Scharrers
+
ydoc .
+
+ 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
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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“
+
+
+ - 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.
+
+ - Kommentar entsprechend
+„reiner ASCII-Text“,
+weder „typografische Zeichen“ noch Auszeichnung.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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
+
+
+ - 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 /pdf ,
+
+ - liest und setzt die erzeugte Datei dann als
+
.tex .
+
+
+Genauer …
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - Dennoch gelungene „Fremddokumentationen“:
+arseneau.pdf ,
+substr.pdf .
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vorteile und Problematik der Zeichenkategorien (\catcode... )
+
+
+
+ - für Dokumentationsvorverarbeitung
+Einlesen als „reinen Text“
+(
\dospecials „other “)
+
+ \PatternCodes für Ersetzungsregeln
+anzupassen
+
+ 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)
+
+
+
+ - Internetauftritt/CMS
+
+ - „Elektronischer Zettelkasten“
+
+ - Querverweise
+
+ - gegliederte/kommentierte Link-Sammlungen
+
+ - Hervorhebung von Stichwörtern
+in Texten aus anderen Formaten
+
+(Xpad/Tomboy)
+
+
+
+ - besserer Lesefluss ohne Seitenumbrüche,
+ohne problematische Zeilenumbrüche
+
+ - keine Arbeit mit Umbrüchen
(außer gedankliche Gliederung)
+
+ - Bildschirmfläche voll nutzen
+
+ |
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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?
+
+
+
+
+ \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 .)
+
+
+ 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 )!
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
diff --git a/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact.html b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact.html
new file mode 100644
index 00000000000..bc22e8a2f5d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fifinddo-info/variants/dantev45-992-exact.html
@@ -0,0 +1,3283 @@
+
+
+
+
+
+
+
+ Dokumentation und HTML mit fifinddo
+
+
+
+ uwe_lueck
>
+ texmap
>
dantev45
– neu laden
+ –
+
+[ START
+<<< zuerst klicken,
+dann auf Bildunterrand klicken
+
+bzw. knapp unter Text
+(MSIE)
+
+und rechts unten für „Rückkehr“
+ 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-15
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 0:
+
+Über den Vortrag
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortragstitel bedeutet (I):
+
+ - „Paketdokumentation“
-
+– Beschreibung von LaTeX-Makro-Paketen, d. h.
+
+
+
+ - in „Schreibmaschinenschrift“ („verbatim“) gesetzter
+Paketcode wechselt mit in LaTeX-Qualität gesetztem
+Kommentar ab („zeilenweise“)
+
+ - der Kommentartext enthält
+„verbatim“ gesetzten TeX-Code („inline“)
+zur Bezugnahme – insbesondere:
+
+ - Gebrauchsanleitung/Syntaxbeschreibung für Nutzer:
+
„Tippt man
+
+\foo∗[〈opt-arg〉]{〈mand-arg〉} ,
+
+so erhält man …“
+
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+
+ - „Webseitenpflege“
-
+– „hochtrabend“, zunächst bloß: HTML-Erzeugung
+–
+
+
+ - Internetauftritt (?
+CMS?
+– ja …)
+
+ - bequeme Textformat-Alternative zu PDF …
+
+(Notizen zu Links,
+Beamer-Präsentation …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+
+
+… was haben Paketdokumentation und
+HTML-Erzeugung miteinander zu tun??
+
+(– Zu HTML-Paketdokumentationen
+ habe ich es noch nicht gebracht …)
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vortrag interessant …
+
+
+
+ - wenn man als Makroprogrammierer
+
doc.sty und docstrip.tex
+(„.dtx …“)
+zu aufwändig findet …
+
+ - wenn man HTML schätzt und PDF
+vermeiden möchte …
+
+ - wenn man Makro-Denksport mag
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Inhaltliche Motive
+
+
+
+ - „minimales Markup“,
+„syntaktischer Zucker“
+(LaTeX-Qualität
+möglichst ohne LaTeX-Befehle)
+
+ - „Missbrauch“ von TeX
+als „Skriptsprache“
+
+(„mit TeX muss und will ich keine andere Sprache lernen“;
+statt PDF-Schriftsatz
+– wie docstrip )
+
+ - kleine(?), einfache(?), experimentelle(!),
+(„schrullige“,) gerade eigenen (U. L.) Bedürfnissen
+entsprechende Alternativen zu existierenden
+„professionelleren“ Paketen
+(Erfolge – Scheitern …)
+
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Persönliche Motive
+
+(bemerkenswerte Mischung aus:)
+
+
+ - gespannt auf Kommentare
zu meinen Paketen,
+
+ - Vortrag soll aber auch über „Konkurrenzprodukte“ informieren
+
+ - Irrtümer? Hinweise?
+– Terminologie erst in letzten zwei Wochen
+„erarbeitet“
+
+ - 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
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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:
+
+
+
+ -
+
+„typografische Zeichen“
+– „typografische“ Varianten von
+Auslassungspunkten,
+Anführungszeichen,
+Leerzeichen,
+und Strichen.
+
+
+ - „Formatierung“ – Umschalten zwischen
+Zeichensätzen, Einrücken,
+Listen, Verweise, …
+
+
+
+– Unterscheidung nur HTML-Terminologie?
+
+HTML verwendet für ersten Fall
+spezielle Zeichen wie
+ (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ü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 ]
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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 –
+
+
+ - weg mit Backslashs,
+englischen Befehlen und
+geschwungenen Klammern!
+
+ - überhaupt möglichst wenig Code-Zeichen
+
+ - Zeichen möglichst intuitiv
+
+ - … am besten so aussehen wie Ergebnis
+
+ - – „ASCII-WYSIWYG“
+– vs.
unisugar mit Unicode …
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen – Bewertung
+
+– von TeX/LaTeX:
+
+
+ - TeX-Ligaturen schon ganz gut!
+
+ - aktive Zeichen … na ja …
+„
~ “ besser als „ “,
+aber …
+
+ \dots schon übel …
+(warum nicht Ligatur „... “?)
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Typografische Zeichen automatisch?
+
+
+ - automatische Umwandlung „reiner“ Zeichen
+in „typografische“?
+
+ \sfcode`A=999 schon in diese Richtung
+(TeXbook S. 76)
+
+ - so ja optional Anführungszeichen in
+Word
+
+ - … und hier
+– simpel, solange nicht
german /babel …:
+
" ..." expandiert zu
+\glqq... \grqq oder so
+
+ - eigentlich nur dies
+(automatisches Einfügen typografischer Zeichen)
+„
.txt→.tex “
+in nicetext -Beschreibung
+(Schwäche der Terminologie)
+
+ - 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:
+
+
+ txt2latex kleines
+Perl-Skript,
+wandelt gerade TeXs spezielle Zeichen
+(„& “ etc.), „... “
+und doppelte/einzelne Anführungszeichen um
+(s. Datei
+txt2latex )
+
+ txt2tex – Perl, erzeugt tatsächlich
+LaTeX-Formatierung (Paketnamen „verkehrt“!)
+
+ EasyLaTeX ähnlich oder mehr,
+GUI(?), Ideen aus Wiki…-Markup;
+zuletzt 2004 (README 2009 eher CTAN-Hand)
+
+ 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).
+
+
+ - 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.
+
+ - 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.
+
+ - 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)
+
+
+ - Die Pakete
stringstrings (Steven Segletes),
+xstring (Christian Tellechea, e-TeX )
+und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen
+„auf höchstem Niveau“.
+
+ - String-Funktionen finden sich auch in
+
datatool (Nicola Talbot),
+coolstr (Nick Setzer) und
+texapi (Paul Isambert).
+
+ - 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
+
+
+ - statt
\...section{...} einrahmende
+Gleichheitszeichen-Folgen verwenden,
+
+ - Kursiv- und Fettschrift
+mit Folgen von
+„Apostroph-Ersatzzeichen“
+(ASCII-Code 39) ein- und abschalten,
+
+ - Listen und Blockzitate
+aus Menschen- oder Programmiersprache durch
+spezielle Zeilenanfänge anzeigen.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+wiki.sty s „forschende“ Zeichen
+
+
+ - Gleichheitszeichen werden aktive Zeichen,
+die feststellen, wieviele Gleichheitszeichen unmittelbar
+aufeinander folgen.
+
+ - Ebenso funktionieren die Apostroph-Ersatzzeichen.
+Dabei werden
\textit und \textbf nicht direkt
+verwendet, das Umschalten und die
+Kursivkorrektur
+finden ohne „Gruppenbildung“ statt.
+
+ - 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
+
+
+
+ - Schriftkodierung
+durch Folgen von Apostrophen finde ich
+nicht intuitiv genug,
+um andere Paketbearbeiter damit konfrontieren zu wollen,
+[Publikum (U. Z.): Markdown!]
+
+ - … sie ist gegenwärtig auch inkompatibel mit der
+Verwendung „aktiver Apostrophe“ in
+
niceverb.sty .
+
+ - Überschriftenkodierung durch
+Gleichheitszeichen verwende ich bisher in der
+(MA)-Implementierung von
makedoc.sty .
+
+ - Dass Einrücken eine
+verbatim-Umgebung auslöst, finde ich
+unpraktisch.
+
+ - Im Quelltext sehe ich lieber „1.“, „2.“,
+…als „
# “.
+
+[Publikum: Markdown!]
+
+ - Unnummerierte Listen mit
* sind
+OK,
+habe ich mal für „Fremddokumentation“ eingesetzt.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Teil 6:
+
+niceverb.sty
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+niceverb.sty – „Schriftauszeichnung“
+„Fortsetzung“ der
+Wikipedia-Schriftauszeichnung:
+
+
+ - Umrahmung mit einfachen Apostroph-Ersatzzeichen
+(
’nicetext’ )
+wirkt wie \textsf
+– für Paketnamen.
+
+ - 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:
+
+
+ - „
<meta> “ erzeugt „〈meta〉“
+sowohl innerhalb als auch
+außerhalb von einfachen Anführungszeichen.
+
+ - Im „Auto-Modus“ werden LaTeX-Befehle nicht
+ausgeführt, sondern als verbatim-Text
+interpretiert, etwa folgende Sterne und Klammern
+als Syntaxbeschreibung dazu.
+
+ - – dient besonders
+der „Fremddokumentation“
+(vorhandene ASCII-Paketdokumentation
+anderer Autoren ohne Eingriff in LaTeX-Qualität setzen).
+
+ - „
& “
+ist aktives Zeichen, welches in
+Makroargumenten Befehlen und
+Syntaxbeschreibungen vorangestellt werden kann,
+um „nachzuhelfen“:
+
+\footnote{& \foo ∗[<opt-arg>]{<mand-arg>}}
+
+
+ -
+
+aktive Zeichen → Probleme …
+Auswege …
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Ähnliche Pakete anderer Autoren
+
+
+
+ niceverb.sty ist wesentlich inspiriert
+durch die Dokumentationsmethode Stephan Böttchers
+in lineno.sty .
+
+ - Ähnliche Funktionalität liefert auch
+
ltxguide.cls für die „LaTeX-Guides“.
+
+ - Die bequeme Syntaxbeschreibung
+gibt es
+(„mittlerweile“) auch in Martin Scharrers
+
ydoc .
+
+ 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
+
+
+
+ - Erläuterungen für Programmierer,
+um die Wartung des Codes zu erleichtern –
+
+ - gerade im Falle von TeX- und LaTeX-Paketen
+(alter Zeiten)
+an Nutzer gerichtete „Erläuterungen“
+im Sinne einer Gebrauchsanleitung
+(manchmal der einzig verfügbaren).
+
+ - 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“
+
+ - 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 –
+
+ - 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
+
+
+ - Enthält eine TeX/LaTeX-Paketdatei
+die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung,
+so umfasst sie typischerweise wesentlich mehr
+Kommentarzeilen als Anweisungszeilen.
+
+ - Auch „Programmierertext“, der die Implementierung
+sorgfältig diskutiert, kann im Verhältnis zum Code sehr
+umfangreich sein (z. B.
lineno .sty ).
+
+ - „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. …
+
+
+ - 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.
+
+ - 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:
+
+
+
+ - Mit LaTeX2 hatten Paket-Dateien
+die Endung „
.sty “.
+Sie enthielten noch „Kommentar“ wie oben.
+
+ - 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
+
+
+ - Kommentarzeilen sind mit TeX/LaTeX gewöhnlich
+durch das Kommentarzeichen („
% “)
+am Anfang gekennzeichnet.
+
+ - (Nach
\endinput wird Code auch
+ohne Kommentarzeichen ignoriert;
+ebenso kann man im Prinzip „Kommentar“ 〈kommentar〉 mit
+„\iffalse 〈kommentar〉\fi “
+einrahmen.)
+
+ - 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?
+
+ - … 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“
+
+
+ - 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.
+
+ - Kommentar entsprechend
+„reiner ASCII-Text“,
+weder „typografische Zeichen“ noch Auszeichnung.
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Darstellung des Kommentars mit doc.sty
+
+
+ - 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.
+
+ - (Wie war das eigentlich mit WEB?)
+
+ - 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 –
+
+
+ gmdoc (Grzegorz Murzinowski;
+ich meine mich zu erinnern:
+wie bei wiki.sty sind die
+Zeilenendzeichen aktiv
+und schauen sich den nächsten Zeilenanfang an)
+
+ 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 …
+
+ 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
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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
+
+
+ - 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 /pdf ,
+
+ - liest und setzt die erzeugte Datei dann als
+
.tex .
+
+
+Genauer …
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Dokumentationslauf
+[Genauer] … kompiliere
+ich typischerweise die Dokumentation
+
+
+ 〈job〉.pdf von
+〈job〉.sty aus
+〈job〉.tex .
+
+ 〈job〉.tex
+enthält makedoc -Befehle
+zur Erzeugung von
+〈job〉.doc aus
+〈job〉.sty und zum Einlesen von
+〈job〉.doc ,
+
+ - kann noch Dokumentation von
+Ergänzungspaketen
+〈add〉 via
+
〈add〉.doc einbinden.
+
+ 〈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
+
+
+
+ - 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“.
+
+ -
+Einrichten eines solchen Workflows
+war aufwändig,
dafür jetzt Vorlagen
+sowie Bash- und
+fifinddo -Skripts.
+
+ - Fehler wegen Umwegs über
+erzeugte Dateien
+(mehr Zeilen als in Quelldatei)
+manchmal schwer verständlich …
+
+ -
+In der Praxis kann ich (derzeit)
+doch LaTeX-Befehle
+(Backslashs, …, vgl. Vorgabe)
+nicht ganz vermeiden,
+wohl vor allem bei Verweisen …
+
+ - Dennoch gelungene „Fremddokumentationen“:
+arseneau.pdf ,
+substr.pdf .
+
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+Vorteile und Problematik der Zeichenkategorien (\catcode... )
+
+
+
+ - für Dokumentationsvorverarbeitung
+Einlesen als „reinen Text“
+(
\dospecials „other “)
+
+ \PatternCodes für Ersetzungsregeln
+anzupassen
+
+ 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)
+
+
+
+ - Internetauftritt/CMS
+
+ - „Elektronischer Zettelkasten“
+
+ - Querverweise
+
+ - gegliederte/kommentierte Link-Sammlungen
+
+ - Hervorhebung von Stichwörtern
+in Texten aus anderen Formaten
+
+(Xpad/Tomboy)
+
+
+
+ - besserer Lesefluss ohne Seitenumbrüche,
+ohne problematische Zeilenumbrüche
+
+ - keine Arbeit mit Umbrüchen
(außer gedankliche Gliederung)
+
+ - Bildschirmfläche voll nutzen
+
+ |
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+
+ | |
|
+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?
+
+
+
+
+ \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 .)
+
+
+ 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 )!
+
+ |
+
+ | |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
--
cgit v1.2.3