Source Code Dokumentation mit DocBook
Hallo! Ich soll den Quellcode für meine Diplomarbeit ausführlich dokumentieren und frage mich ob es sich auszahlt das mit DocBook zu erledigen. Es handelt sich dabei zur Zeit um ca. 22000 Zeilen in 37 Dateien (könnte noch auf max. 35000 Zeilen wachsen). Mir wäre eine einfache Konvertierung nach PDF und HTML wichtig. Vom Inhalt her nichts besonderes, ein paar Tabellen, Code-Beispiele und Grafiken, der Großteil einfacher Text. Kennt jemand gute Anleitungen und einfache Tools bzw. Stylesheets zum Validieren und Konvertieren von DocBook nach PDF/HTML? Danke im Voraus, Stefan Lang
* Stefan Lang
Ich soll den Quellcode für meine Diplomarbeit ausführlich dokumentieren und frage mich ob es sich auszahlt das mit DocBook zu erledigen. Es handelt sich dabei zur Zeit um ca. 22000 Zeilen in 37 Dateien (könnte noch auf max. 35000 Zeilen wachsen).
Das Problem bei Quellcodedokumentation mit DocBook ist, dass Quellcode und Dokumentation getrennt ist. Erstens muss man die Struktur des Codes in der Dokumentation duplizieren, zweitens vergisst man bei Änderungen im Quellcode gerne, die Dokumentation zu ändern. Ich empfehle daher Doxygen, wo man die Dokumentation in den Quellcode (z. B. Headerdateien) integrieren kann. Beispiel: /** * Computes the maximum of the two given numbers. * * @param a the first number * @param b the second number * @return the maximum of the two numbers */ int max(int a, int b); Das ganze funktioniert praktisch genauso wie bei JavaDoc. Als Ausgabe erhält man HTML, RTF und LaTeX. Aus dem LaTeX-Dokument kann man dann problemlos PDF generieren. Das ganze funktioniert mit C/C++ und auch weiteren Sprachen. Bei Java nimmt man ohnehin JavaDoc. Gruß, Bernhard -- * Linux Viruscan..... Windows 95 found. Remove it? (y/n)
Am Sonntag, 24. Oktober 2004 11:15 schrieb Bernhard Walle:
* Stefan Lang
[2004-10-24 10:36]: Ich soll den Quellcode für meine Diplomarbeit ausführlich dokumentieren und frage mich ob es sich auszahlt das mit DocBook zu erledigen. Es handelt sich dabei zur Zeit um ca. 22000 Zeilen in 37 Dateien (könnte noch auf max. 35000 Zeilen wachsen).
Das Problem bei Quellcodedokumentation mit DocBook ist, dass Quellcode und Dokumentation getrennt ist. Erstens muss man die Struktur des Codes in der Dokumentation duplizieren, zweitens vergisst man bei Änderungen im Quellcode gerne, die Dokumentation zu ändern.
Ich empfehle daher Doxygen, wo man die Dokumentation in den Quellcode (z. B. Headerdateien) integrieren kann. ...
Danke für den Hinweis. Ich glaube ich habe mich falsch ausgedrückt. Im Quellcode selbst befinden sich schon Kommentare so ähnlich wie für Doxygen. Das was dabei herauskommt ist praktisch eine Dokumentation des API. Meinen Lehrern ist das leider nicht ausreichend. Was noch fehlt wäre eine Gesamtübersicht, Klassenhierarchie und allgemeine Beschreibungen, wie ein bestimmtes Problem gelöst wurde und warum. Außerdem Beispiele an welchen Stellen man die Quellen verändern muss um das Programm um bestimmte Funktionalitäten zu erweitern usw. Trotzdem vielen Dank, Stefan
* Stefan Lang
Meinen Lehrern ist das leider nicht ausreichend. Was noch fehlt wäre eine Gesamtübersicht, Klassenhierarchie und allgemeine Beschreibungen, wie ein bestimmtes Problem gelöst wurde und warum. Außerdem Beispiele an welchen Stellen man die Quellen verändern muss um das Programm um bestimmte Funktionalitäten zu erweitern usw.
Achso. Kann man schon auch mit Doxygen machen. Beispielsweise wurde die Doku http://www.nongnu.org/avr-libc/user-manual/index.html komplett mit Doxygen realisiert. Mit Docbook geht's auch, ich würde wahrscheinlich direkt LaTeX nehmen, mit listings.sty für Quellcodebeispiele. Aber das ist alles eine Frage des persönlichen Geschmacks. Gruß, Bernhard -- Wenn Du ein Schiff bauen willst, so trommle nicht Männer zusammen, um Holz zu beschaffen, Werkzeuge vorzubereiten, Aufgaben zu vergeben, und die Arbeit einzuteilen, sondern lehre die Männer die Sehnsucht nach dem weiten endlosen Meer. -- Antoine de Saint-Exupery
Am Sonntag, 24. Oktober 2004 14:05 schrieb Bernhard Walle:
* Stefan Lang
[2004-10-24 12:06]: Meinen Lehrern ist das leider nicht ausreichend. Was noch fehlt wäre eine Gesamtübersicht, Klassenhierarchie und allgemeine Beschreibungen, wie ein bestimmtes Problem gelöst wurde und warum. Außerdem Beispiele an welchen Stellen man die Quellen verändern muss um das Programm um bestimmte Funktionalitäten zu erweitern usw.
Achso. Kann man schon auch mit Doxygen machen. Beispielsweise wurde die Doku http://www.nongnu.org/avr-libc/user-manual/index.html komplett mit Doxygen realisiert.
Mit Docbook geht's auch, ich würde wahrscheinlich direkt LaTeX nehmen, mit listings.sty für Quellcodebeispiele. Aber das ist alles eine Frage des persönlichen Geschmacks.
Habe ein Buch über DocBook auftreiben können und damit begonnen. Das konvertieren nach HTML funktioniert einwandfrei, nur mit fop nach PDF mit den Stylesheets von Norman Walsh, die bei SUSE dabei sind, gibt fop zuerst einige Fehlermeldungen aus und wird dann mit einer java.lang.NullPointerException beendet. Mfg, Stefan
* Stefan Lang
Am Sonntag, 24. Oktober 2004 14:05 schrieb Bernhard Walle:
* Stefan Lang
[2004-10-24 12:06]: Meinen Lehrern ist das leider nicht ausreichend. Was noch fehlt wäre eine Gesamtübersicht, Klassenhierarchie und allgemeine Beschreibungen, wie ein bestimmtes Problem gelöst wurde und warum. Außerdem Beispiele an welchen Stellen man die Quellen verändern muss um das Programm um bestimmte Funktionalitäten zu erweitern usw.
Achso. Kann man schon auch mit Doxygen machen. Beispielsweise wurde die Doku http://www.nongnu.org/avr-libc/user-manual/index.html komplett mit Doxygen realisiert.
Mit Docbook geht's auch, ich würde wahrscheinlich direkt LaTeX nehmen, mit listings.sty für Quellcodebeispiele. Aber das ist alles eine Frage des persönlichen Geschmacks.
Habe ein Buch über DocBook auftreiben können und damit begonnen. Das konvertieren nach HTML funktioniert einwandfrei, nur mit fop nach PDF mit den Stylesheets von Norman Walsh, die bei SUSE dabei sind, gibt fop zuerst einige Fehlermeldungen aus und wird dann mit einer java.lang.NullPointerException beendet.
Ich persönlich verwende db2pdf. Gruß, Bernhard -- "Unix is the most user friendly system I know, the point is the it is really selective about who is indeed its friend." -- Luigi Genoni
participants (2)
-
Bernhard Walle
-
Stefan Lang