DocBook

Auf das Thema “DocBook” kam ich, als ich das Sourceforge-Projekt DocBookWiki gestossen bin.
Zum Experimentieren habe ich zunächst folgendes installiert:

Installation docbook-xsl

• Definitive Software Library ID: docbook-xsl
• Name: DocBook XSL Stylesheets 2.65.1
• Hersteller/Bezugsquelle: Sourceforge
• I man so in voller Breite mit DocBook arbeiten wollte, muss man einen dafür spezialisierten Editor/IDE/Autorensystem haben.

Das mindeste ist ein “richtiger” XML-Editor. Folgende Produkte sind im Gespräch:

• jEdit von Sourceforge / jedit.org mit XML-Plugin (Java-basierter sehr guter File-Editor als OpenSourceSoftware, aber sehr schlichte XML-Funktionalität)
• Eclipse mit XML-Plugin z.B. XMLBuddy (recht odentlich, habe ich für eine erste Testphase für mich ausgewählt)
• Xopus (kommerziell, kann Tabellen)
• Abortext Epic (kommerziell, kann Tabellen)
• epcEdit (kommerziell, kann Tabellen, Screenshots sehen sehr schlicht aus)
• XMLmind (kommerziell, eine sog. “Standard Edition” ist kostenlos) http://www.xmlmind.com/xmleditor (Java-basiert, der beste kostenlose!!!!)
• OxygenXMLEditor (sehr schön, aber: kommerziell)
• XML Spy (kommerziell, ein alter Bekannter,….)

Ein XSLT-Prozessor

Die DocBook-Gemeinde ist ja sehr auf Unix/Linux fixiert und präferriert xsltproc, das man unter Cygwin als Paket libxslt installieren kann.

Ich verwende zunächst meinen Java-basierten Xalan-XSLT-Prozessor, den ich wie folgt aufrufe:

%JAVA_HOME%\bin\java org.apache.xalan.xslt.Process -IN simple.xml -XSL "docbook-xsl-1.65.1/htmlhelp/htmlhelp.xsl" -OUT hugo.htm

Since JDK 1.5 the xerces and xalan packages are part of JAXP which is a standard package shipped along with jdk1.5. Consequently, the package names have changed and the xalan transformation process can be invoked using the command line

%java com.sun.org.apache.xalan.internal.xslt.Process -IN a.xml -XSL a.xsl -OUT a.htm

Der Aufruf des XSLT-Prozessors kann auch innerhalb von Eclipse erfolgen, wenn man ein entsprechendes Eclipse-Plugin installiert (z.B. Improve XSLT oder Transclipse).

Eine dritte Möglichkeit ist, einen komfortablen XMLEditing mit integrierter XSLT-Funktionalität z.B. XMLMind einzusetzen.

DocBook Output generieren

Der generierte Output wird durch die Angabe eines bestimmten Stylesheets und die Angabe von Stylesheet-Parametern bestimmt. Einige der üblichen Stylesheets sind z.B.:

1. -XSL /html/docbook.xsl (das “normale” HTML-DocBook)
2. -XSL /html/chunk.xsl (ein modulares HTML-DocBook d.h. “zerstückelt”)
3. -XSL /fo/docbook.xsl (habe ich noch nicht probiert, soll PDF oder sonstwas rauskommem….)
4. -XSL /htmlhelp/htmlhelp.xsl (ein “help” DocBook)

Stylesheet-Parameter (in der Xalan-Systax) sehen etwa wie folgt aus:

• -param shade.verbatim 1
• -param navig.graphics 1

Erzeugen von: Slideshow und Einbindung von SVG-Verktorgrafik ist (im Prinzip) möglich. Und auch beides in Kombination: http://www.zveno.com/open_source/svgslides.html

DocBook Beispiel gmo_chronik.xml

Meine Beispiele befinden sich im Ordner E:\var\www\htdocs\docbook.

Der Aufruf des XSLT-Prozessors mit den diversen Parametern erfolgt über das Kommando-Script (BAT-File) xslt_chunk.bat:

rem Aufruf Java XSLT-Prozessor Xalan
rem $Date: 2007/06/02 07:54:32 $
echo  html/chunk.xsl	in %1.xml out %1.htm
pause
%JAVA_HOME%\bin\java org.apache.xalan.xslt.Process -IN %1.xml 
		  -XSL "docbook-xsl-1.65.1/html/chunk.xsl" 
		  -OUT %1.htm 
		  -param generate.meta.abstract 1 
		  -param html.stylesheet "chronik.css" 
		  -param html.stylesheet.type "text/css" 
		  -param navig.graphics 1 
		  -param navig.graphics.extension ".gif"
		  -param chunk.section.depth 2 
		  -param chunk.first.sections 1
pause

So wird jetzt aus der Docbook-XML-Datei eine kleine Website, indem jede Section eine HTML-Seite wird:

e:
cd \var\www\htdocs\docbook
xslt_chunk gmo_chronik

Microsoft HTML Help Workshop

Wenn man seine schönen DocBooks unbedingt in Microsoft-Help-Files umsetzen will, benötigt man für den letzten Schritt den MicrosoftHTMLHelp-Workshop und dann ganz einfach:

hhc htmlhelp.hhp 

http://codeproject.com/winhelp/docbook_howto.asp

DocBook Beispiel

<?xml version="1.0" encoding="ISO-8859-1"?>
<DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
  <article>
  <title>Mein Lexikon</title>
  <section id="analogiemethode">
  <title>Analogiemethode</title>
  <para>Analogiemethode, gehört zu den Methoden der <link linkend="aufwandsschätzung">Aufwandsschätzung</link>. Es wird versucht, das zu schätzende Projekt mit ähnlichen, abgeschlossenen Projekten zu vergleichen. Eine Abweichungsanalyse stellt Gemeinsamkeiten und Unterschiede zwischen den Projekten bezüglich der wichtigen Einflussfaktoren (Projektorganisation, Entwicklungsumgebung, Metriken usw.) fest und bewertet diese bezüglich Aufwand und Produktivität.</para>
  <para>Die Schätzgenauigkeit hängt davon ab, wie gut man das zu schätzende Projekt kennt (Pflichtenheft) und von der Erfahrung bei der richtigen Auswahl und Einschätzung der Einflussfaktoren in der Abweichungsanalyse. Umfangreiche Erfahrungen mit abgeschlossenen, ähnlichen Projekten sind die Basis der Analogiemethode. Projekte, die sich in wesentlichen Faktoren grundsätzlich von den bekannten Projekten unterscheiden, können so nicht geschätzt werden.</para>
  <indexterm>
  <seealso>Aufwandsschätzung</seealso>
  <seealso>Pflichtenheft</seealso>
  </indexterm>
  </section>
  <section id="aufwandsschätzung">
  <title>Aufwandsschätzung</title>
  <para>Aufwandsschätzung, für den Anwender gleichermaßen schwieriges Unterfangen wie für den Berater; für letzteren insbesondere vor dem Hintergrund eines Festpreisauftrags. Es geht um die Prognose des Perso­nal­kapa­zitätsbedarfs für ein Projekt. Die Güte der Aufwandsschätzung kann nur so gut sein wie die Qualität der zugrundeliegenden Unterlagen (Ausschreibungsunterlagen, Ist-Analyse, Pflichtenheft). Äusserst schwierig ist es, aus der Sicht der ersten Projektphasen bereits das gesamte Projekt zu schätzen. Eine verbindliche Genauigkeit kann für die jeweils nächste Phase meist erst bei Abschluss der vorange­gan­genen Phase erfolgen. Aufwandsschätzung beruht auf zwei Größen: <emphasis>Arbeitsmenge und Arbeitspro­duk­tivität.</emphasis>
  </para>
  <para>Wesentlich ist auch der Zeitpunkt der Aufwandsschätzung: Vor der Erstellung eines Fach­konzepts können nur grobe Erfahrungswerte und Analogieschlüsse zur Anwendung kommen. Auf der Basis eines Fach­konzepts können ausgefeilte Methoden wie z.B. Function Point angewendet werden. Interindividuelle Varianzen der Produktivität haben nach Capers Jones den größten Einfluss auf die Aufwandsschätzung.
  <simplelist type="vert">
  <member>Die wichtigsten Methoden sind:</member>
  <member>Analogiemethode</member>
  <member>Multiplikatormethode</member>
  <member>Prozentsatzmethode</member>
  <member>Function-Point-Methode</member>
  <member>COCOMO-Methode</member>
  <member>Pi-mal-Daumen-Methode</member>
  <member>Budget-Methode</member>
  </simplelist>
  </para>
  </section>
  </article>

Weblinks

• DocBook-Tutorial: http://www.sagehill.net/docbookxsl

— Main.DietrichKracht – 10 Jul 2004