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 > dantev45neu 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 + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 0: + + + +
+Über den Vortrag

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (I):

+
+
„Paketdokumentation“
+– Beschreibung von LaTeX-Makro-Paketen, d. h. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+ +

Vortragstitel bedeutet (III):

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortrag interessant …

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Inhaltliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Persönliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Status

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Auszeichnung“

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. SmileTeX Windows .exe? ++ Werkzeuge für Grafikeinbindung etc., +zuletzt 2004 +
+– für Paketdokumentation ist mir das zuviel … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 3: + + + +
+„Formatierung“ + + + +
+ (Auszeichnung, Wikipedia)

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Schriftauszeichnung

+– Anregungen wie für EasyLaTeX? +

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Listen und Zitate

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Wiki-wie LaTeX-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(\DocInput)

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. 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
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

makedocs \DocInput{⟨job⟩}

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

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 10: + + + +
+HTML erzeugen

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML-Erzeugung – Alternativen

+
    + +
  • HTML-Editoren, CMSe?; Formeln? keine Ahnung, egal +
  • +
  • TeX4th +(Eitan Gurari†; +Wikipedia sehr informativ) +– verarbeitet .dvi, kommt insofern (wohl) mit allen Paketen/Makros +zurecht, ohne sie einzeln zu behandeln +– damit Webseiten pflegen? +
  • +
  • diverse Syntax-Wandler wie +LaTeX2html (Perl), hevea.inria.fr, +TeX2page, + +TtH +(C; +Home: Formeln!); +vgl. tug.org/interest.html#web +
  • +
  • blog.sty +(morehype-Bündel) +– expandiert Makros zu HTML; +LaTeX-Makros umdefiniert, +neue Makros für bestimmte +HTML-Strukturen, z. B.lnavicol.sty +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML und PDF aus selber Quelle?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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). +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Was (zur Zeit) nicht geht

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dank

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+ + 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 > dantev45neu 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. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

Vortragstitel bedeutet (III):

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

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

Vortrag interessant …

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

Inhaltliche Motive

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

Persönliche Motive

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

Status

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

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

„Auszeichnung“

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

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. 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-Codewie 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-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

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

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

(\DocInput)

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. makedoc.sty (selbst) bietet statt awk + +eine Art TeX-basierte Skriptsprache und unterschiedliche +Zeilenparser,
    +um jeweils eine Dokumentationsdatei zu erzeugen. + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Interpretationen“ von Kommentarzeichen

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

makedocs \DocInput{⟨job⟩}

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

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

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

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

Teil 10: + + + +
+HTML erzeugen

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

+
+
    + +
  1. Internetauftritt/CMS +
  2. +
  3. „Elektronischer Zettelkasten“ +
      +
    1. Querverweise +
    2. +
    3. gegliederte/kommentierte Link-Sammlungen +
    4. +
    5. Hervorhebung von Stichwörtern +in Texten aus anderen Formaten + +(Xpad/Tomboy) + +
    +
  4. +
  5. besserer Lesefluss ohne Seitenumbrüche,
    +ohne problematische Zeilenumbrüche +
  6. +
  7. keine Arbeit mit Umbrüchen
    (außer gedankliche Gliederung) +
  8. +
  9. 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?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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 > dantev45neu 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 + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 0: + + + +
+Über den Vortrag

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (I):

+
+
„Paketdokumentation“
+– Beschreibung von LaTeX-Makro-Paketen, d. h. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+ +

Vortragstitel bedeutet (III):

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortrag interessant …

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Inhaltliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Persönliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Status

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Auszeichnung“

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. SmileTeX Windows .exe? ++ Werkzeuge für Grafikeinbindung etc., +zuletzt 2004 +
+– für Paketdokumentation ist mir das zuviel … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 3: + + + +
+„Formatierung“ + + + +
+ (Auszeichnung, Wikipedia)

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Schriftauszeichnung

+– Anregungen wie für EasyLaTeX? +

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Listen und Zitate

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Wiki-wie LaTeX-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(\DocInput)

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. 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
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

makedocs \DocInput{⟨job⟩}

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

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 10: + + + +
+HTML erzeugen

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML-Erzeugung – Alternativen

+
    + +
  • HTML-Editoren, CMSe?; Formeln? keine Ahnung, egal +
  • +
  • TeX4th +(Eitan Gurari†; +Wikipedia sehr informativ) +– verarbeitet .dvi, kommt insofern (wohl) mit allen Paketen/Makros +zurecht, ohne sie einzeln zu behandeln +– damit Webseiten pflegen? +
  • +
  • diverse Syntax-Wandler wie +LaTeX2html (Perl), hevea.inria.fr, +TeX2page, + +TtH +(C; +Home: Formeln!); +vgl. tug.org/interest.html#web +
  • +
  • blog.sty +(morehype-Bündel) +– expandiert Makros zu HTML; +LaTeX-Makros umdefiniert, +neue Makros für bestimmte +HTML-Strukturen, z. B.lnavicol.sty +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML und PDF aus selber Quelle?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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). +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Was (zur Zeit) nicht geht

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dank

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+ + 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 > dantev45neu 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 + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 0: + + + +
+Über den Vortrag

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (I):

+
+
„Paketdokumentation“
+– Beschreibung von LaTeX-Makro-Paketen, d. h. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+ +

Vortragstitel bedeutet (III):

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortrag interessant …

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Inhaltliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Persönliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Status

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Auszeichnung“

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. SmileTeX Windows .exe? ++ Werkzeuge für Grafikeinbindung etc., +zuletzt 2004 +
+– für Paketdokumentation ist mir das zuviel … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 3: + + + +
+„Formatierung“ + + + +
+ (Auszeichnung, Wikipedia)

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Schriftauszeichnung

+– Anregungen wie für EasyLaTeX? +

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Listen und Zitate

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Wiki-wie LaTeX-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(\DocInput)

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. 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
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

makedocs \DocInput{⟨job⟩}

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

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 10: + + + +
+HTML erzeugen

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML-Erzeugung – Alternativen

+
    + +
  • HTML-Editoren, CMSe?; Formeln? keine Ahnung, egal +
  • +
  • TeX4th +(Eitan Gurari†; +Wikipedia sehr informativ) +– verarbeitet .dvi, kommt insofern (wohl) mit allen Paketen/Makros +zurecht, ohne sie einzeln zu behandeln +– damit Webseiten pflegen? +
  • +
  • diverse Syntax-Wandler wie +LaTeX2html (Perl), hevea.inria.fr, +TeX2page, + +TtH +(C; +Home: Formeln!); +vgl. tug.org/interest.html#web +
  • +
  • blog.sty +(morehype-Bündel) +– expandiert Makros zu HTML; +LaTeX-Makros umdefiniert, +neue Makros für bestimmte +HTML-Strukturen, z. B.lnavicol.sty +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML und PDF aus selber Quelle?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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). +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Was (zur Zeit) nicht geht

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dank

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+ + 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 > dantev45neu 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. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

Vortragstitel bedeutet (III):

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

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

Vortrag interessant …

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

Inhaltliche Motive

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

Persönliche Motive

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

Status

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

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

„Auszeichnung“

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

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. 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-Codewie 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-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

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

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

(\DocInput)

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. makedoc.sty (selbst) bietet statt awk + +eine Art TeX-basierte Skriptsprache und unterschiedliche +Zeilenparser,
    +um jeweils eine Dokumentationsdatei zu erzeugen. + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Interpretationen“ von Kommentarzeichen

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

makedocs \DocInput{⟨job⟩}

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

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

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

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

Teil 10: + + + +
+HTML erzeugen

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

+
+
    + +
  1. Internetauftritt/CMS +
  2. +
  3. „Elektronischer Zettelkasten“ +
      +
    1. Querverweise +
    2. +
    3. gegliederte/kommentierte Link-Sammlungen +
    4. +
    5. Hervorhebung von Stichwörtern +in Texten aus anderen Formaten + +(Xpad/Tomboy) + +
    +
  4. +
  5. besserer Lesefluss ohne Seitenumbrüche,
    +ohne problematische Zeilenumbrüche +
  6. +
  7. keine Arbeit mit Umbrüchen
    (außer gedankliche Gliederung) +
  8. +
  9. 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?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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 > dantev45neu 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. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

Vortragstitel bedeutet (III):

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

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

Vortrag interessant …

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

Inhaltliche Motive

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

Persönliche Motive

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

Status

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

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

„Auszeichnung“

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

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. 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-Codewie 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-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

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

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

(\DocInput)

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. makedoc.sty (selbst) bietet statt awk + +eine Art TeX-basierte Skriptsprache und unterschiedliche +Zeilenparser,
    +um jeweils eine Dokumentationsdatei zu erzeugen. + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Interpretationen“ von Kommentarzeichen

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

makedocs \DocInput{⟨job⟩}

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

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

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

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

Teil 10: + + + +
+HTML erzeugen

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

+
+
    + +
  1. Internetauftritt/CMS +
  2. +
  3. „Elektronischer Zettelkasten“ +
      +
    1. Querverweise +
    2. +
    3. gegliederte/kommentierte Link-Sammlungen +
    4. +
    5. Hervorhebung von Stichwörtern +in Texten aus anderen Formaten + +(Xpad/Tomboy) + +
    +
  4. +
  5. besserer Lesefluss ohne Seitenumbrüche,
    +ohne problematische Zeilenumbrüche +
  6. +
  7. keine Arbeit mit Umbrüchen
    (außer gedankliche Gliederung) +
  8. +
  9. 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?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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 > dantev45neu 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 + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 0: + + + +
+Über den Vortrag

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (I):

+
+
„Paketdokumentation“
+– Beschreibung von LaTeX-Makro-Paketen, d. h. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+ +

Vortragstitel bedeutet (III):

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortrag interessant …

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Inhaltliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Persönliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Status

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Auszeichnung“

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. SmileTeX Windows .exe? ++ Werkzeuge für Grafikeinbindung etc., +zuletzt 2004 +
+– für Paketdokumentation ist mir das zuviel … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 3: + + + +
+„Formatierung“ + + + +
+ (Auszeichnung, Wikipedia)

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Schriftauszeichnung

+– Anregungen wie für EasyLaTeX? +

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Listen und Zitate

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Wiki-wie LaTeX-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(\DocInput)

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. 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
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

makedocs \DocInput{⟨job⟩}

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

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 10: + + + +
+HTML erzeugen

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML-Erzeugung – Alternativen

+
    + +
  • HTML-Editoren, CMSe?; Formeln? keine Ahnung, egal +
  • +
  • TeX4th +(Eitan Gurari†; +Wikipedia sehr informativ) +– verarbeitet .dvi, kommt insofern (wohl) mit allen Paketen/Makros +zurecht, ohne sie einzeln zu behandeln +– damit Webseiten pflegen? +
  • +
  • diverse Syntax-Wandler wie +LaTeX2html (Perl), hevea.inria.fr, +TeX2page, + +TtH +(C; +Home: Formeln!); +vgl. tug.org/interest.html#web +
  • +
  • blog.sty +(morehype-Bündel) +– expandiert Makros zu HTML; +LaTeX-Makros umdefiniert, +neue Makros für bestimmte +HTML-Strukturen, z. B.lnavicol.sty +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML und PDF aus selber Quelle?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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). +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Was (zur Zeit) nicht geht

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dank

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+ + 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 > dantev45neu 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 + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 0: + + + +
+Über den Vortrag

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (I):

+
+
„Paketdokumentation“
+– Beschreibung von LaTeX-Makro-Paketen, d. h. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+ +

Vortragstitel bedeutet (III):

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortrag interessant …

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Inhaltliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Persönliche Motive

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Status

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Auszeichnung“

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. SmileTeX Windows .exe? ++ Werkzeuge für Grafikeinbindung etc., +zuletzt 2004 +
+– für Paketdokumentation ist mir das zuviel … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 3: + + + +
+„Formatierung“ + + + +
+ (Auszeichnung, Wikipedia)

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Schriftauszeichnung

+– Anregungen wie für EasyLaTeX? +

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Wikipedia: Listen und Zitate

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Wiki-wie LaTeX-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(\DocInput)

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. 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
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

makedocs \DocInput{⟨job⟩}

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

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

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 10: + + + +
+HTML erzeugen

+

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML-Erzeugung – Alternativen

+
    + +
  • HTML-Editoren, CMSe?; Formeln? keine Ahnung, egal +
  • +
  • TeX4th +(Eitan Gurari†; +Wikipedia sehr informativ) +– verarbeitet .dvi, kommt insofern (wohl) mit allen Paketen/Makros +zurecht, ohne sie einzeln zu behandeln +– damit Webseiten pflegen? +
  • +
  • diverse Syntax-Wandler wie +LaTeX2html (Perl), hevea.inria.fr, +TeX2page, + +TtH +(C; +Home: Formeln!); +vgl. tug.org/interest.html#web +
  • +
  • blog.sty +(morehype-Bündel) +– expandiert Makros zu HTML; +LaTeX-Makros umdefiniert, +neue Makros für bestimmte +HTML-Strukturen, z. B.lnavicol.sty +
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

HTML und PDF aus selber Quelle?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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). +
+
+ +

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Was (zur Zeit) nicht geht

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Dank

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

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
+ + + + +
+
+ + + +
+
+ + 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 > dantev45neu 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. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

Vortragstitel bedeutet (III):

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

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

Vortrag interessant …

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

Inhaltliche Motive

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

Persönliche Motive

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

Status

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

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

„Auszeichnung“

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

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. 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-Codewie 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-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

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

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

(\DocInput)

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. makedoc.sty (selbst) bietet statt awk + +eine Art TeX-basierte Skriptsprache und unterschiedliche +Zeilenparser,
    +um jeweils eine Dokumentationsdatei zu erzeugen. + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Interpretationen“ von Kommentarzeichen

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

makedocs \DocInput{⟨job⟩}

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

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

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

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

Teil 10: + + + +
+HTML erzeugen

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

+
+
    + +
  1. Internetauftritt/CMS +
  2. +
  3. „Elektronischer Zettelkasten“ +
      +
    1. Querverweise +
    2. +
    3. gegliederte/kommentierte Link-Sammlungen +
    4. +
    5. Hervorhebung von Stichwörtern +in Texten aus anderen Formaten + +(Xpad/Tomboy) + +
    +
  4. +
  5. besserer Lesefluss ohne Seitenumbrüche,
    +ohne problematische Zeilenumbrüche +
  6. +
  7. keine Arbeit mit Umbrüchen
    (außer gedankliche Gliederung) +
  8. +
  9. 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?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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 > dantev45neu 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. + +
    + +
  1. in „Schreibmaschinenschrift“ („verbatim“) gesetzter +Paketcode wechselt mit in LaTeX-Qualität gesetztem +Kommentar ab („zeilenweise“) +
  2. +
  3. der Kommentartext enthält +„verbatim“ gesetzten TeX-Code („inline“) +zur Bezugnahme – insbesondere: +
  4. +
  5. Gebrauchsanleitung/Syntaxbeschreibung für Nutzer: +
    „Tippt man +
    +\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}, +
    +so erhält man …“ +
  6. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vortragstitel bedeutet (II):

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

Vortragstitel bedeutet (III):

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

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

Vortrag interessant …

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

Inhaltliche Motive

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

Persönliche Motive

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

Status

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

Vortragsteile

+
+
    + +
  1. „Markup“? – Terminologie +
  2. +
  3. „typografische Zeichen“ +mit TeX/LaTeX +
  4. +
  5. „Formatierung“ +
  6. +
  7. Implementierung +„minimalen Markups“ „mit TeX allein“ +
  8. +
  9. Paketdokumentation +
  10. +
  11. niceverb.sty +
  12. +
  13. „Kommentar“ +
  14. +
  15. Kommentar ausblenden +
  16. +
  17. „Darstellung“ des Kommentars +
  18. +
  19. HTML erzeugen +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Von .txt zu .tex

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

„Auszeichnung“

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

Teil 2: + + + +
+Typografische Zeichen mit TeX/LaTeX

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen mit TeX/LaTeX

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Bewertung –
„minimales Markup“ genauer

+
+„LaTeX-Qualität möglichst ohne LaTeX-Befehle
+– README des nicetext-Bündels: + +
„möglichst keine Zeichen im Dokumentquellcode,
die nicht auch gedruckt werden!“

+– schließt „typografische Zeichen“ ein +– Schwäche meiner (damaligen) Terminologie – +
    + +
  1. weg mit Backslashs, +englischen Befehlen und +geschwungenen Klammern! +
  2. +
  3. überhaupt möglichst wenig Code-Zeichen +
  4. +
  5. Zeichen möglichst intuitiv +
  6. +
  7. … am besten so aussehen wie Ergebnis +
  8. +
  9. ASCII-WYSIWYG +– vs. unisugar mit Unicode … +
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Typografische Zeichen – Bewertung

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

Typografische Zeichen automatisch?

+
    + +
  1. automatische Umwandlung „reiner“ Zeichen +in „typografische“?
    +
  2. +
  3. \sfcode`A=999 schon in diese Richtung +(TeXbook S. 76) +
  4. +
  5. so ja optional Anführungszeichen in +Word +
  6. +
  7. und hier +– simpel, solange nicht german/babel …: +
    "..." expandiert zu +\glqq...\grqq oder so +
  8. +
  9. eigentlich nur dies +(automatisches Einfügen typografischer Zeichen) +.txt→.tex +in nicetext-Beschreibung +(Schwäche der Terminologie) +
  10. +
  11. WARNUNG! fehlerhafte Automatisierung +typografischer Anführungszeichen kann zum Verlust +des Doktortitels +und politischer Ämter führen! +(gutten.sty) + + + + +
    + + +[ z. B. german.sty nicht geladen, \glqq, \grqq nicht definiert, Fehlermeldungen ignoriert ] + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

.txt.tex vor nicetext

+– auf CTAN: +
    + +
  1. txt2latex kleines +Perl-Skript, +wandelt gerade TeXs spezielle Zeichen +(„&“ etc.), ... +und doppelte/einzelne Anführungszeichen um +(s. Datei +txt2latex) +
  2. +
  3. txt2tex – Perl, erzeugt tatsächlich +LaTeX-Formatierung (Paketnamen „verkehrt“!) +
  4. +
  5. EasyLaTeX ähnlich oder mehr, +GUI(?), Ideen aus Wiki…-Markup; +zuletzt 2004 (README 2009 eher CTAN-Hand) +
  6. +
  7. 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-Codewie 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-CodeWiki-wie LaTeX-Code
∗ Eins
∗ Zwei
\begin{itemize}
\item Eins
\item Zwei
\end{itemize}
Er nur:
:Ja, …
Er nur:
\begin{quote}
Ja, \dots
\end{quote}
# Eins
# Zwei
\begin{enumerate}
\item Eins
\item Zwei
\end{enumerate}
Code:
\relax
Code:
\begin{verbatim}
\relax
\end{verbatim}
+
+– immerhin recht „minimal“, +auch halbwegs intuitiv. + + + + +
+ +(vgl. wikicheat.pdf) + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

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

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Implementierungsmethoden für
„minimales Markup“ mit TeX

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

Methode (MS) – Anmerkungen I

+TeXs +Mechanismus, sog. „begrenzte Parameter“ +von Makros zu erkennen +(TeXbook S. 203), +bietet eine bequeme, aber auch „begrenzte“ Methode, +„Zeichenketten“ („Strings“) +zu erkennen
(und zu ersetzen). +
    + +
  1. Vor- und Nachteile entstehen daraus, dass +ein „String“ aus „reinem Text“ von TeX intern +durch unterschiedliche „Token-Ketten“ „dargestellt“ +werden kann. Auch von Groß-/Kleinschreibung abzusehen +ist nicht ganz einfach. +
  2. +
  3. 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. +
  4. +
  5. Gegenwärtig fußen auch fifinddo.sty und +makedoc.sty (nicetext) +auf dieser Methode – genügte bisher praktisch. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Anmerkungen zu (MS) II
(Strings und Scripting mit TeX)

+
    + +
  1. Die Pakete stringstrings (Steven Segletes), +xstring (Christian Tellechea, e-TeX) +und ted (Manuel Pégourié-Gonnard) liefern String-Funktionen +„auf höchstem Niveau“. +
  2. +
  3. String-Funktionen finden sich auch in +datatool (Nicola Talbot), +coolstr (Nick Setzer) und +texapi (Paul Isambert). +
  4. +
  5. Eine „ernsthafte Skriptsprache“ +bietet neben Zeichenersetzung +allgemeiner „Sortierung“ und „Filter“. +Beispielsweise bietet docstrip +eine TeX-basierte Skriptsprache, +die aus einer .dtx-Quelldatei +die „Kommentare“ entfernt +und den Rest in verschiedene +„kompakte“ TeX-Eingabedateien „sortiert“. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimales Markup“
mit „forschenden“ aktiven Zeichen (MA)

+wiki.sty aus dem nicetext-Bündel +implementiert die zuvor beschriebene +Wikipedia-Syntax für TeX, d. h. mit wiki.sty +kann man in der {document}-Umgebung von LaTeX +
    + +
  1. statt \...section{...} einrahmende +Gleichheitszeichen-Folgen verwenden, +
  2. +
  3. Kursiv- und Fettschrift +mit Folgen von +Apostroph-Ersatzzeichen“ +(ASCII-Code 39) ein- und abschalten, +
  4. +
  5. Listen und Blockzitate +aus Menschen- oder Programmiersprache durch +spezielle Zeilenanfänge anzeigen. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

wiki.stys „forschende“ Zeichen

+
    + +
  1. Gleichheitszeichen werden aktive Zeichen, +die feststellen, wieviele Gleichheitszeichen unmittelbar +aufeinander folgen. +
  2. +
  3. Ebenso funktionieren die Apostroph-Ersatzzeichen. +Dabei werden \textit und \textbf nicht direkt +verwendet, das Umschalten und die +Kursivkorrektur +finden ohne „Gruppenbildung“ statt. +
  4. +
  5. Um Listen und Zitate am Zeilenanfang +zu erkennen, wird das Zeilenende-Zeichen +(^^M) aktiv und ändert auch für kurze Zeit +die Kategorie des Leerzeichens. +So analysiert ^^M den Anfang der nächsten Zeile +und kann feststellen, ob eine Liste bzw. ein Blockzitat +beginnt, fortgesetzt wird, oder +endet, oder ob der Liste ein +weiterer Punkt (\item) hinzugefügt wird. +Entsprechend wird automatisch eine +\begin{...}- bzw. \end{...}-Zeile oder das Makro +\item eingefügt +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

(MA) vs. (MS)

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

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

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Die Pakete des nicetext-Bündels

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

wiki.sty

+ +
    + +
  1. Schriftkodierung +durch Folgen von Apostrophen finde ich +nicht intuitiv genug, +um andere Paketbearbeiter damit konfrontieren zu wollen, +[Publikum (U. Z.): Markdown!] +
  2. +
  3. … sie ist gegenwärtig auch inkompatibel mit der +Verwendung „aktiver Apostrophe“ in +niceverb.sty. +
  4. +
  5. Überschriftenkodierung durch +Gleichheitszeichen verwende ich bisher in der +(MA)-Implementierung von makedoc.sty. +
  6. +
  7. Dass Einrücken eine +verbatim-Umgebung auslöst, finde ich +unpraktisch. +
  8. +
  9. Im Quelltext sehe ich lieber „1.“, „2.“, +…als „#“. +
    +[Publikum: Markdown!] +
  10. +
  11. Unnummerierte Listen mit * sind +OK, +habe ich mal für „Fremddokumentation“ eingesetzt. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 6: + + + +
+niceverb.sty

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty – „Schriftauszeichnung

+„Fortsetzung“ der +Wikipedia-Schriftauszeichnung: +
    + +
  1. Umrahmung mit einfachen Apostroph-Ersatzzeichen +(’nicetext’) +wirkt wie \textsf +– für Paketnamen. +
  2. +
  3. 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.stywie Code sonst
’nicetext’\textsf{nicetext}
\foo\verb+\foo+
‘README.txt’\texttt{README.txt}
+

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Beschreibung von LaTeX-Makros

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

Hervorhebung von Makrobeschreibungen

+ +Vertikalstriche (|\foo|) +
    + +
  • schalten im vorigen Beispiel (doc.sty) +– wie es sehr üblich ist – +verbatim-Modus an/aus, +d. h. |\foo| kürzt +\verb|\foo| ab – +
  • +
  • sollen mit niceverb.sty +Code hervorheben und +beim Überfliegen der +Dokumentation herausstechen lassen +(„hier Erläuterung von \foo!“) +
+– Farbhinterlegung? derzeit +„Kästen“ wie mit \fbox, + +intern soll \InlineCmdBox zusammenfassende Aufzählungen von Makros +in einem Absatz ermöglichen. Beispiel Code/Ergebnis: +
 
+|\foo∗[<opt-arg>]{<mand-arg>}| 
+
+
+ + + + +
\foo∗[⟨opt-arg⟩]{⟨mand-arg⟩}
+
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

niceverb.sty noch:

+
    + +
  1. <meta> erzeugt „⟨meta⟩“ +sowohl innerhalb als auch +außerhalb von einfachen Anführungszeichen. +
  2. +
  3. Im „Auto-Modus“ werden LaTeX-Befehle nicht +ausgeführt, sondern als verbatim-Text +interpretiert, etwa folgende Sterne und Klammern +als Syntaxbeschreibung dazu. +
  4. +
  5. – dient besonders +der „Fremddokumentation“ +(vorhandene ASCII-Paketdokumentation +anderer Autoren ohne Eingriff in LaTeX-Qualität setzen). +
  6. +
  7. &“ +ist aktives Zeichen, welches in +Makroargumenten Befehlen und +Syntaxbeschreibungen vorangestellt werden kann, +um „nachzuhelfen“: +
     
    +\footnote{&\foo∗[<opt-arg>]{<mand-arg>}} 
    +
    +
  8. +
  9. + +aktive Zeichen → Probleme … +Auswege … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ähnliche Pakete anderer Autoren

+ +
    + +
  1. niceverb.sty ist wesentlich inspiriert +durch die Dokumentationsmethode Stephan Böttchers +in lineno.sty. +
  2. +
  3. Ähnliche Funktionalität liefert auch +ltxguide.cls für die „LaTeX-Guides“. +
  4. +
  5. Die bequeme Syntaxbeschreibung +gibt es +(„mittlerweile“) auch in Martin Scharrers +ydoc. +
  6. +
  7. niceverb.sty ist ebenso wie +ydoc als Alternative +zu doc.sty konzipiert. +ydoc liefert dabei einen ähnlichen +Funktionsumfang wie doc.sty, +während ich (für meine Zwecke) +einen solchen Funktionsumfang überhaupt +nicht haben will. +– Allerdings habe ich einzelne +doc.sty-Funktionen in +makedoc.sty und in +readprov.sty +(fileinfo-Bündel). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 7: + + + +
+„Kommentar“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Code und „Kommentar“

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

+TeX bietet wie alle „normalen“ Programmiersprachen die Möglichkeit, +in Quelldateien Text einzufügen, der nicht +vom Compiler bzw. Interpreter (als Befehle/Daten) +verarbeitet werden soll, sondern an (menschliche) Leser +gerichtet ist – hier „Kommentar“. +
+Einzelne Zwecke +(der Wikipedia-Artikel +weiß noch mehr …): + +

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Zwecke des Kommentars

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

Zwecke des „Auskommentierens“

+
    +
  1. als eine Art „Versionskontrolle“: +man behält sich vor, den Code später wieder +„an den Compiler/Interpreter zu richten“ +(durch einfache Entfernung der +Kommentarzeichen bzw. +„Kommentarbegrenzern“), +z. B. zum „Debugging“ +oder für bestimmte Adressaten – +
  2. +
  3. als „Erinnerung“ and frühere „Fehlversuche“, +die auf frühere „Überlegungen“ hinweist und so wieder +der Wartung durch den Programmierer/Autor dient. +
+Ich nehme an, bei vielen ist in der täglichen Praxis mit TeX/LaTeX +das „Auskommentieren“ die hauptsächliche Funktion des +„Kommentars“ … + +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 8: + + + +
+Methoden Kommentar „auszublenden“

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Feinheiten des „Ausblendens“
von Kommentar

+
    + +
  1. Enthält eine TeX/LaTeX-Paketdatei +die TeX-Anweisungen und gleichzeitig die Gebrauchsanweisung, +so umfasst sie typischerweise wesentlich mehr +Kommentarzeilen als Anweisungszeilen. +
  2. +
  3. Auch „Programmierertext“, der die Implementierung +sorgfältig diskutiert, kann im Verhältnis zum Code sehr +umfangreich sein (z. B. lineno.sty). +
  4. +
  5. „Vor langer Zeit“ forderte das Einlesen +von TeX-Makrodateien aufgrund der „Hardware-Umstände“ +bereits so viel Zeit, dass es sinnvoll war, +das Einlesen von Kommentarzeilen völlig zu vermeiden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Ausblenden“ von Kommentar – Forts. …

+
    + +
  1. Ein „primitiver“ Ansatz dazu war, +die „Gebrauchsanleitung“
    +„am Ende der Datei“ nach dem +\endinput-Befehl der Datei +anzubringen. Die Datei enthielt dann gerne am +Anfang den Hinweis auf die Gebrauchsanleitung +der Datei an ihrem Ende.
    +Der \endinput-Befehl bricht die Verarbeitung der Datei ab, +so dass die Zeilen darunter tatsächlich +keine Verarbeitungszeit mehr beanspruchen. +
  2. +
  3. Andererseits sollte für die Wartung +der Kommentar eben doch in der Nähe der +betreffenden Code-Zeilen angebracht werden … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

docstrip blendet noch effizienter aus:

+ +
    + +
  1. Mit LaTeX2 hatten Paket-Dateien +die Endung .sty“.
    +Sie enthielten noch „Kommentar“ wie oben. +
  2. +
  3. Mit LaTeX2e wurden doc.sty und +docstrip.tex eingeführt. +Dateien, die Code und Kommentar „gemischt“ enthielten, bekamen nun die Endung +.doc oder .dtx“. +docstrip wandelt solche Dateien in Dateien mit Endungen +hauptsächlich wie .sty oder +.cls um; +diese sollen keinen Kommentar mehr enthalten +(bis auf Lizenz-Hinweise) und sind diejenigen, +die im TeX-Lauf tatsächlich eingelesen werden, +außer … +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Kommentarzeichen

+
    + +
  1. Kommentarzeilen sind mit TeX/LaTeX gewöhnlich +durch das Kommentarzeichen („%“) +am Anfang gekennzeichnet. +
  2. +
  3. (Nach \endinput wird Code auch +ohne Kommentarzeichen ignoriert; +ebenso kann man im Prinzip „Kommentar“ ⟨kommentar⟩ mit +\iffalsekommentar\fi +einrahmen.) +
  4. +
  5. 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? +
  6. +
  7. … tatsächlich: Mit Paul Isamberts +CodeDoc ist der „Kommentar“ +normaler, von Listing-Umgebungen +unterbrochener Text (ohne „%“ links). +Letztere schreiben den Code in die kompakte Paketdatei. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Ohne docstrip heute

+(docstrip fortsetzend:) … +aber +es gibt die .sty-Pakete, +die mit Kommentarzeilen +(ohne docstrip einzuschalten) eingelesen werden, noch heute! +
    + +
  • verschiedene in TDS-ltxmisc/, darunter +einige geniale, für manche unverzichtbare Pakete von +Donald Arseneau (ich sehe gerade framed …) +
  • +
  • Stephan Böttchers lineno.sty +(Zeilennummerierung besonders für +kritische Editionen und Einreichungen) +enthält gewaltig viel Kommentar – von mir übernommen, +nie gehört, dass das Laden zu lange dauere … +
  • +
  • alle (? \endinput) meine +eigenen +Pakete (was natürlich einfach eine Frechheit sein kann …) +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Teil 9: + + + +
+„Darstellung“ des Kommentars

+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Darstellung“ des Kommentars – „Vorzeit“

+
    + +
  1. Vor doc.sty +war der Kommentar in Paketdateien +dazu da, mit einem Texteditor gelesen oder +im „Text“-Modus +(als „Listing“, im Gegensatz zum für TeX +erforderlichen „Grafik“-Modus) +ausgedruckt zu werden. +
  2. +
  3. Kommentar entsprechend +„reiner ASCII-Text“, +weder „typografische Zeichen“ noch Auszeichnung. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Darstellung des Kommentars mit doc.sty

+
    + +
  1. Erst mit doc.sty wurde +die heute von LaTeX-Paketen auf dem +CTAN gewohnte LaTeX-Druckqualität +des Kommentars möglich, +wobei man den Code als Imitation +der Texteditor- und Listing-Druckqualität auszeichnet. +Entscheidend ist dabei der +Don’t repeat yourself-Grundsatz +– die Code und +Kommentar mischende Quelldatei wird für +den Qualitätsausdruck nicht von Hand überarbeitet, +sondern „automatisch“ mit dem \DocInput-Befehl +verarbeitet. +
  2. +
  3. (Wie war das eigentlich mit WEB?) +
  4. +
  5. Dazu kann man allerdings (oder konnte bisher) +nicht (den früheren) +ASCII“-Kommentar verwenden, +der Kommentar muss vielmehr als „LaTeX-Input“ +mit typografischen Zeichen und +LaTeX-Markup +in der Code+Kommentar-Quelldatei stehen +(vgl. ltxdoc-Dokumentation zu {oldcomments}). +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

\DocInput{⟨c+k⟩}

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

(\DocInput)

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

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

+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Minimale“ Kennzeichnung des Codes

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

„smartes“ \DocInput

+ +– Algorithmus klar:
+ – nach Zeile +mit%“ vor „ohne“ +„\begin{macrocode}“,
+ – im umgekehrten Fall „\end{macrocode}“ +einfügen – +
    + +
  1. gmdoc (Grzegorz Murzinowski; +ich meine mich zu erinnern:
    +wie bei wiki.sty sind die +Zeilenendzeichen aktiv
    +und schauen sich den nächsten Zeilenanfang an) +
  2. +
  3. 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 … +
  4. +
  5. makedoc.sty (selbst) bietet statt awk + +eine Art TeX-basierte Skriptsprache und unterschiedliche +Zeilenparser,
    +um jeweils eine Dokumentationsdatei zu erzeugen. + +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

„Interpretationen“ von Kommentarzeichen

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

makedocs \DocInput{⟨job⟩}

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

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

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

Dokumentationslauf

+[Genauer] … kompiliere +ich typischerweise die Dokumentation +
    + +
  1. job⟩.pdf von +job⟩.sty aus +job⟩.tex. +
  2. +
  3. job⟩.tex +enthält makedoc-Befehle +zur Erzeugung von +job⟩.doc aus +job⟩.sty und zum Einlesen von +job⟩.doc, +
  4. +
  5. kann noch Dokumentation von +Ergänzungspaketen +⟨add⟩ via +add⟩.doc einbinden. +
  6. +
  7. job.doc/add.doc +können
    (nach \RequirePackage{makedoc})
    +ganz zu Anfang des TeX-Laufs innerhalb einer Gruppe erzeugt +und dann in der {document}-Umgebung mit +\input eingelesen werden. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Erfolge/Scheitern

+ +
    + +
  1. Ich kann damit flott +Pakete schreiben/dokumentieren
    +(auch mit Dokumentation als +Roadmap beginnen). +
    +Nach Einrichten des +Dokumentations-Workflows
    +läuft mittlerweile meist alles „wie am Schnürchen“. +
  2. +
  3. +Einrichten eines solchen Workflows +war aufwändig,
    dafür jetzt Vorlagen +sowie Bash- und +fifinddo-Skripts. +
  4. +
  5. Fehler wegen Umwegs über +erzeugte Dateien
    +(mehr Zeilen als in Quelldatei) +manchmal schwer verständlich … +
  6. +
  7. +In der Praxis kann ich (derzeit) +doch LaTeX-Befehle
    +(Backslashs, …, vgl. Vorgabe) +nicht ganz vermeiden,
    +wohl vor allem bei Verweisen … +
  8. +
  9. Dennoch gelungene „Fremddokumentationen“:
    +arseneau.pdf, +substr.pdf. +
+ +
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Vorteile und Problematik der Zeichenkategorien (\catcode...)

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

Teil 10: + + + +
+HTML erzeugen

+
+ + + + +
+
+ + + +
+
+
+ + + + + +
+ + + + +
+
+
+

Nutzen von HTML (vs. PDF)

+
+
    + +
  1. Internetauftritt/CMS +
  2. +
  3. „Elektronischer Zettelkasten“ +
      +
    1. Querverweise +
    2. +
    3. gegliederte/kommentierte Link-Sammlungen +
    4. +
    5. Hervorhebung von Stichwörtern +in Texten aus anderen Formaten + +(Xpad/Tomboy) + +
    +
  4. +
  5. besserer Lesefluss ohne Seitenumbrüche,
    +ohne problematische Zeilenumbrüche +
  6. +
  7. keine Arbeit mit Umbrüchen
    (außer gedankliche Gliederung) +
  8. +
  9. 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?

+ +
+
    + +
  1. \labelsection etc. – htmlTeX
    +(HTML regt zu Makros an, die auch für +PDF-Erzeugung interessant wären,
    +angefangen mit logischer Auszeichnung wie +<code>/\code, +<strong>/\strong.) + +
  2. +
  3. 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