Dateiformat und Übersetzprogramm für Dokumentation und Sprache in Programmen oder Bibliotheken

Je exotischer, desto mehr Probleme später. Wichtig wäre, dass man Jahre später ohne spezielle Tools alles einfach lesen und durchsuchen kann.

Lu schrieb:

Wichtig wäre, dass man Jahre später ohne spezielle Tools alles einfach lesen und durchsuchen kann.

Ja, da stimme ich zu. Deshalb habe ich ja zumindest bei PDF Dokumentationen von einen Office Bearbeitungsprogramm (LibreOffice, MS Office, ...) auf LaTeX gewechselt. Da ist zumindest der Inhalt bis auf die "paar" Steuerbefehle und Formatierungsbefehle noch mit einen ganz normalen Texteditor lesbar. Aber da hilft auch Syntaxhighlighting um die Befehle zu erkennen. Zugegeben mit dem "normalen" Windows Texteditor würde ich mir ein LaTeX Dokument nur zur Not ansehen. Verstehe bis heute nicht warum der Standard-Texteditor von Windows kein Highlighting kann. Aber zumindest erkennt er seit einiger Zeit auch Unix Zeilenenden (LF). War soweit ich weiß zu Windows 95 Zeiten nicht der Fall.

Johannes schrieb:

Mich würde interessieren was Ihr für Dokumentation und Sprachausgabe für eure Programme verwendet. Also zum Beispiel bei CLI Programmen die Manpage und für die Bedienung passend in der jeweiligen Benutzersprache (Deutsch, Englisch, ...).

Heute? Markdown. Das ist ein einfaches Textformat, das sich einfach durchsuchen und mit pandoc [1] in quasi alles Mögliche umwandeln läßt. Zudem ist es erweiterbar, zum Beispiel können die Markdown-Dateien mit der Frontmatter-Erweiterung mit strukturierten YAML-Daten angereichert werden. Und der Clou: Markdown ist sehr leicht menschenlesbar, jedenfalls im Vergleich mit HTML, LaTeX, DocBook und Co.

[1] https://pandoc.org/

Ich habe mir ja für PDF Dokumentationen LaTeX angeeignet.

Das kann ich zwar auch, aber bei meinen Programmen ist mir wichtig, daß die Dokumentation für die Benutzer möglichst leicht zugänglich ist. Da hat Markdown den großen Vorteil, daß es weder eine GUI noch zusätzliche Software braucht, sondern einfach mit less(1), more(1) oder sogar cat(1) gelesen werden kann -- auch über langsame Netzwerke und auch von Laien, die dem Markdown-Format noch nie vorher begegnet sind. (Wobei solche Nutzer zumindest im technikorientierten Umfeld mittlerweile ziemlich selten geworden sind.)

Johannes schrieb:

Mich würde interessieren was Ihr für Dokumentation und Sprachausgabe für eure Programme verwendet. Also zum Beispiel bei CLI Programmen die Manpage und für die Bedienung passend in der jeweiligen Benutzersprache (Deutsch, Englisch, ...).

troff und dessen Derivate kann man auch heute noch dazu verwenden. Als Ausgabeformate stehen damit txt, ps, pdf oder html zur Verfügung. Für die unterschiedlichen Aufgaben gibt es passende Makros - man, ms, mom. Mit tbl und eqn gehen auch Tabellen und mathematische Formeln. Letzteres nicht so einfach und perfekt wie mit LaTeX, aber ausreichend gut.

https://www.gnu.org/software/groff/

https://www.schaffter.ca/mom/mom-01.html

https://www.troff.org/using-ms.pdf

https://www.troff.org/54.pdf

http://mam.sdf.org/pub/3rd-party-doc/troff-nroff/gpic.pdf

Pdf ist zwar ok, aber html ist da viel netter, einfacher und flexibler.

asciidoc gibts auch noch.

Doxygen?

https://doxygen.nl/

https://doxygen.nl/examples.html (Liste mit Projekten, die Doxygen verwenden)

Daraus kann man dann HTML generieren, oder PDF, oder man Pages, ... Bei der AVR-LibC sieht das dann so aus:

• HTML: https://avrdudes.github.io/avr-libc/avr-libc-user-manual/index.html Kann man auch so generieren, dass es ein Zoo von einzelnen HTML-Seiten wird anstatt die ganze Doku auf einer Seite.

• PDF: https://avrdudes.github.io/avr-libc/avr-libc-user-manual-2.3.0.pdf

Für Java-Projekte Javadoc: https://de.wikipedia.org/wiki/Javadoc

Dann gibe es noch Sphinx, hab ich aber keine Erfahrung mit.

Soweite Software, die die Doku in die Quellen einbettet bzw aus diesen extrahiert. Üblicherweise kann man auch zusätzliche Seiten einbinden die nicht in einer Quelldatei stehen, bei AVR-LibC zum Beispiel https://avrdudes.github.io/avr-libc/avr-libc-user-manual/inline_asm.html

Gute Erfahrung habe ich mit Makeinfo / Texinfo gemacht: https://www.gnu.org/software/texinfo/ Damit kann man auch unterschiedliche Ausgabeformate (HTML, PDF, ...) erzeugen.

Absolut grauslig für größere Projekte finde ich Asciidoc / Markdown. Gut für ein Readme, aber bei komplexeren Layout-Aufgaben einfach nur ätzend.

Vorschläge wie *roff sind wohl als Scherz gemeint. Als Ausgabeformat ja, aber in dem Format willst /nicht/ deine Projekte dokumentieren. Nimm halt was, was unterschiedlicheste Ausgaben wie auch *roff erzeugen kann, z.B. Doxygen oder Makeinfo.