Thread Dokumentation mit DocBook und/oder .odt (OpenOffice) oder ...? (2 answers)
Opened by payx at 2011-10-17 11:17

payx
 2015-05-07 18:58
#180962 #180962
User since
2006-05-04
564 articles
BenutzerIn

user image
Hallo,

hier kommt die ultimative Lösung von diesem Problem (ohne Perl, oder vielleicht auch mit Perl, s.u.):

    1. Text mit beliebigem Editor als Wikipedia:Markdown erfassen.
    2. Mit pandoc daraus pdf erzeugen.

Fertig!

Anders als bei einem Textverarbeitungssystem bietet diese Vorgehensweise kein WYSIWYG (what you see is what you get). Diese Einschränkung ist aber zugleich die Stärke dieser Arbeitsweise, denn beim Arbeiten in der Layoutansicht wird man erfahrungsgemäß ständig vom Erscheinungsbild des Ergebnisses abgelenkt und beeinflusst.

Tatsächlich ist es besser, wenn man während der Bearbeitung des Textes eben nicht sieht, was man am Schluss erhält, sondern sich einfach darauf verlassen kann, dass es schon gut aussehen wird. Stattdessen kann man sich voll auf Inhalt und Struktur seines Textes konzentrieren.

Also statt WYSIWYG: WYSIWYM (what you see is what you mean)!

Weitere Vorteile:

  • pandoc erzeugt die pdf-Dateien über LaTeX (das installiert sein muss), was hochwertigen, professionellen Satz garantiert. Layoutfehler und satztechnische Inkonsistenzen, wie sie bei einem Textverarbeitungssystem leicht entstehen können, werden hier durch eine sehr reife, speziell für diesen Zweck geschaffene Software vermieden.
  • Trotzdem entfällt die aufwendige Einarbeitung in LaTeX und die Bearbeitung der mit Markup übersähten LaTeX-Quellen. Markdown ist ja das Gegenteil von Markup: Der Text wird mit einem Minimum an zusätzlichen Zeichen strukturiert.
  • Die Quelldateien können versioniert werden (z.B. SVN).


Man baut sich einmal ein LaTeX-Template, das dynamische Elemente enthalten kann, die entweder durch Header-Einträge in der Markdown-Quelldatei oder durch Parameter beim Aufruf beeinflusst werden können. Wir haben z.B. auf diese Weise einstellbar gemacht, ob das pdf-Dokument für den einseitigen oder doppelseitigen Druck erzeugt werden soll. Die Erzeugung des LaTeX-Templates erfordert natürlich doch ein bisschen Beschäftigung mit LaTeX, aber eben nur einmal. Mit pandoc werden Beispiel-Templates ausgeliefert, an denen man sich orientieren kann.

Das pandoc-Markdown geht in einigen Punkten ein wenig über den Markdown-Standard hinaus. Die Dokumentation ist gut.

Wenn die Möglichkeiten von pandoc für die Gestaltungsanforderungen nicht ausreichen, können einfach LaTeX-Konstrukte ins Markdown eingefügt werden, die dann von pandoc an LaTeX weitergereicht werden. Wir haben auf diese Weise beispielsweise Querverweise realisiert, die im pdf sowohl in der Bildschirmanzeige klickbar als auch im Ausdruck durch Blättern nachverfolgbar sein sollen: \label{sec:labelname} ist ein Label namens labelname. \ref{sec:labelname} erzeugt einen klickbaren Querverweis auf die Nummer des Kapitels, in dem dieses Label steht. Außerdem haben wir ein paar eigene kleine LaTeX-Makros, mit denen wir z.B. Grafiken an den Seitenrand setzen, im Einsatz.

Wenn man außer LaTeX auch andere Ausgabeformate erzeugen will, dürfen natürlich keine LaTeX-Konstrukte im Markdown stehen. In diesem Fall wird man der Verarbeitung durch pandoc ein Preprocessing vorschalten müssen, z.B. mit Perl, bzw. siehe hierzu:



Wir arbeiten jetzt seit ein paar Monaten auf diese Weise (ohne Preprocessing, nur pdf-Erzeugung) und haben außerordentlich positive Erfahrungen gemacht. Insbesondere die saubere Versionierbarkeit der Handbücher ist ein wahrer Quantensprung.

Ein möglicher nächster Schritt könnte sein, dass man sich ein Redaktionssystem mit pandoc und LaTeX auf einem Server baut, der auf Knopfdruck die aktuelle Markdown-Datei aus dem SVN (oder was auch immer) holt und das dementsprechend aktuelle pdf ausliefert usw.

Fazit: Wer vor der im Titel dieses Threads gestellten Frage steht, sollte sich pandoc unbedingt ansehen. Die Einarbeitung in Markdown geht wirklich sehr schnell – in die Erstellung und Bearbeitung der LaTeX-Templates kann man hingegen praktisch unbegrenzt viel Zeit stecken.

An weiterführendem Meinungsautausch über dieses Thema bin ich interessiert.

Viele Grüße
payx

PS: Dank an Daniel Bruder, der mich auf diese Vorgehensweise gebracht hat.

View full thread Dokumentation mit DocBook und/oder .odt (OpenOffice) oder ...?