Code dokumentieren? Welches System?

sebbo

sebbo

aka noganex
Hi!

Ich werde demnaechst ein kleines "Buechlein" (~ 50 Seiten) erstellen muessen und ich weiss einfach nicht mit welchem System ich arbeiten soll.
Warum ich diesen Thread hier im Prorgammiererforum erstellt habe: In dem Buechlein wird sehr viel Quelltext stehen (Perl/Konfigurationsdateien/etc...) und ich hab einfach keine Lust mich mit so Sachen wie Quellcode escapen zu beschaeftigen. Ausserdem sollten Tabulatoren in dem Quelltext, den ich in das Buechlein paste, auch so eingerueckt sein, wie ich ihn gepastet habe. ;)
Im Quellcode sollte jede Zeile automatisch nummeriert werden, so dass man jede Zeile bequem dokumentieren kann.

Das Buechlein wollte ich in mehrere Dateien (pro Kapitel) aufteilen, so dass ich bequem per subversion arbeiten kann und am Ende soll trotzdem ein ganzes Dokument und nicht zehn Einzelne rauskommen.
Hin und wieder werden auch mal Bilder auftauchen. Auch hier will ich das Bild nicht erst 20x umwandeln muessen, damit es im Dokument auftaucht.

Und der wichtigste Punkt:
Das Dokument sollte problemlos in valides XHTML, PDF, Postscript... exportiert werden koennen.

LaTeX "kann" ich zwar, aber ich weiss definitiv, dass ich es hier nicht verwenden will.
Docbook - sieht ziemlich cool aus. Scheint auch alles zu haben, was ich will, aber ich weiss nicht ob ich da meinen Code so einfach pasten kann und ob dann die Einrueckungen noch stimmen. Wie sieht es da mit der Zeilennummerierung des Codes an? Gibt es fuer dieses System eine freundliche Einfuehrung? :)

Bevor ich mit dem Buch anfange, wollte ich mich erstmal von euch hoeren, was ihr von Docbook haltet oder ob es noch besser geeignete Systeme gibt.
Habt ihr sowas schonmal gemacht und habt ihr vielleicht ein paar Hinweise fuer mich?

mfg
Sebastian
 
oehm...
was spricht gegen latex?

code:
Code: 
\begin{verbatim}
bla
fasel
troet
\end{verbatim}
(gut, nummerieren musst du den so von hand... es sei denn, du baust dir eine eigene code-umgebung...)

mehrere dateien:
Code: 
laber
\input{file1.tex}
piiiiep
\input{file2.tex}
suelz

bilder einbinden:
Code: 
\includegraphics{sebbo_nackt_am_strand.eps}
?

http://www.dettus.net/math/latex_fuer_bloede.pdf
 
Zuletzt bearbeitet:
Docbook ist das, was Du suchst. Es ist ideal fuer diesen Zweck, da exakt darauf ausgelegt. Diverse XSLT Skripte erlauben die automatische Erstellung verschiedener technischer Dokumentationen und der umfangreiche Satz an XML Tags erlaubt eine saubere und ordentliche Darstellung inklusive aller noetigen Eventualtitaeten.
Desweiteren gibt es diverse Parser und Konverter, so dass auch PDF, HTML, PS, etc. schnell und einfach erstellt werden koennen.

Die <programlisting> Tags geben Dir die Moeglichkeit, Quelltext entweder intern exakt einzubinden oder per externer Referenz in das Dokument zu laden.

Siehe dazu auch
http://docbook.sourceforge.net/
http://docbook.org/

gruss

Edit:
Die <programlisting> Tags haben die Moeglichkeit per XML Attribut Zeilen zu nummerieren.
 
DocBook-XML ist Dein Freund

Ich habe es bisher für diesen Zweck zwar noch nicht eingesetzt, aber DocBook unterstützt definitiv soetwas. Das geht dann so:

Code: 
<programlisting linenumbering="numbered">
#!/usr/bin/python
import sys
...
</programlisting>

Ich arbeite gerne mit DocBook. Als Tranformationstools solltest Du am besten GNU libxml installiert haben. Da kannst Du dann auch XIncludes nutzen. Evtl. mußt Du einige xsl-Dateien editieren/erweitern, wenn Du optisch was anderes als Deinen Text/Code auf weißem Hintergrund haben willst.

Gute Literatur zum Thema:

DocBook-XML, m. CD-ROM von Thomas Schraitle

DocBook-XML, m. CD-ROM von Lars Trieloff

Lars Trieloff hat auch einen "Schnellstarter" ins Netz gestellt "Dokumentationen mit DocBook-XML" oder so (Link habe ich gerad nicht). Er ist in Deutschland wohl einer der bekanntesten DocBook-Experten und -Verfechter.
 
Danke fuer die Antworten! :) Docbook scheint also doch das Richtige fuer mich zu sein.

Zwei Fragen haette ich jedoch noch.
Das mit der Numerierung klappt doch nicht so wie ich mir das vorstelle.. Laut Dokumentation muss ich doch "lediglich" use.extensions und linenumbering.extension aktivieren, oder?
/usr/bin/xsltproc -o perl.html --stringparam use.extensions 1 --stringparam linenumbering.extension 1 /usr/share/sgml/docbook/xsl-stylesheets-1.68.1/xhtml/docbook.xsl perl.xml
No numberLines function available.
Zum Vergrößern anklicken....
-> Der Code wird nicht angezeigt und ich kann mit der Fehlermeldung nichts anfangen. ;'(

2. Wie gehe ich in DocBook richtig mit Umlauten um? Irgendwie ist UTF-8 nicht ganz mein Fall und ich moechte gerne iso-8859-1 verwenden. Also schreibe ich meine Umlaute direkt ins XML File (laut den Spezifikationen ist das ja so Standard) und gebe folgendes an:
<?xml version='1.0' encoding='iso-8859-1'?>
Zum Vergrößern anklicken....
Der obige Aufruf von xsltproc wandelt mir das trotzdem irgendwie nach UTF-8 um und folglich sind alle Umlaute hinueber... Gibt's da eine saubere Loesung?

mfg
Sebastian
 
Das wusste ich nicht, aber so klappt es. Und der Sache mit der Zeilennummerierung bin ich auch auf die Spur gekommen. xsltproc unterstuetzt das nicht, nur saxon.

Danke fuer die Hilfe! :)
 
Quellcodezeilen numerieren und evtl. Syntaxhighlighting kann LaTeX mit dem listings-Paket (oder so aehnlich auch).

Docbook, LaTeX. Das gibt sich nicht viel, mir ist XML viel zu viel zum Tippen. Und mit LaTeX schaut das Druckerzeugniss einfach viel besser aus. YMMV.
 
MrFixit schrieb:
Quellcodezeilen numerieren und evtl. Syntaxhighlighting kann LaTeX mit dem listings-Paket (oder so aehnlich auch).

Docbook, LaTeX. Das gibt sich nicht viel, mir ist XML viel zu viel zum Tippen. Und mit LaTeX schaut das Druckerzeugniss einfach viel besser aus. YMMV.
Zum Vergrößern anklicken....
Kann ich so nur bestätigen. Ich habe in den letzten drei Jahren Studium so
fast alles ausprobiert, um endlich eine annehmbare Lösung für die Erstellung von
Dokumentationen zu finden. Durch eine Ausarbeitung habe ich mich auch mit
"docbook" gequält, aber das XML drumherum macht auf Dauer wirklich keinen Spaß.
Mittlerweile bin ich bei Lyx und KOMA-Script gelandet und relativ zufrieden.
Für die Einbindung von Source Code jeglich Art gibt es m.E. nichts komfortableres als
Code: 
\documentclass{article}
\usepackage{listings}
\renewcommand\lstlistingname{Beispiel}
\renewcommand\lstlistlistingname{Beispielverzeichnis}
\lstset{language=Perl, numbers=left, numberstyle=\tiny, numbersep=5pt, frame=tb}
\begin{document}
\begin{lstlisting}[caption={``hello world'' in Perl''}]
print "hello world";
\end{lstlisting}
\lstlistoflistings
\end{document}
siehe: http://www.ctan.org/tex-archive/macros/latex/contrib/listings/

mfg dagnu
 
Ist schon irgendwie blöd, dass viele sagen Latex würde besser aussehen. Das gleiche Ergebnis müsste sich doch prinzipiell auch mit Docbook hinbekommen lassen...

Ich persönlich finde die Latex Syntex leider so zum kotzen, dass ich damit nicht arbeiten kann...schade.
 
Verwendet DocBook nicht auch den Weg ueber Tex->PDF? Oder machen die das inzwischen direkt?

Na jedenfalls hat TeX halt so einiges an typographischen Kniffen zu bieten: Kerning, Ligaturen, optischer Randausgleich, etc.

Ein XML->TeX Converter ist ebenfalls trivial zu schreiben. XML kann ja schliesslich alles!!!111eins
 
MrFixit schrieb:
Verwendet DocBook nicht auch den Weg ueber Tex->PDF? Oder machen die das inzwischen direkt?

Na jedenfalls hat TeX halt so einiges an typographischen Kniffen zu bieten: Kerning, Ligaturen, optischer Randausgleich, etc.

Ein XML->TeX Converter ist ebenfalls trivial zu schreiben. XML kann ja schliesslich alles!!!111eins
Zum Vergrößern anklicken....

Normalerweise geht das über XSL-FO.
 
Du musst dich einloggen oder registrieren, um hier zu antworten.
Zurück
Oben