View source for Kracht:Docbook

= DocBook =
Auf das Thema "DocBook" kam ich, als ich das Sourceforge-Projekt '''DocBookWiki''' gestossen bin.
<br />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: http://sourceforge.net/projects/docbook
* 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" [[XMLEditing|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|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|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|Cygwin]]  als Paket '''libxslt''' installieren kann.

Ich verwende zunächst meinen [[Java|Java]]-basierten Xalan-XSLT-Prozessor, den ich wie folgt aufrufe:<br />
<pre>
	%JAVA_HOME%\bin\java org.apache.xalan.xslt.Process -IN simple.xml -XSL "docbook-xsl-1.65.1/htmlhelp/htmlhelp.xsl" -OUT hugo.htm
</pre>

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<br />
<pre>
  %java com.sun.org.apache.xalan.internal.xslt.Process -IN a.xml -XSL a.xsl -OUT a.htm
</pre>

Der Aufruf des XSLT-Prozessors kann auch innerhalb von [[Eclipse|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|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.:
# -XSL /html/docbook.xsl	  (das "normale" HTML-DocBook)
# -XSL /html/chunk.xsl	 (ein modulares HTML-DocBook d.h. "zerstückelt")
# -XSL /fo/docbook.xsl	 (habe ich noch nicht probiert, soll PDF oder sonstwas rauskommem....)
# -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''':
<pre>
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
</pre> 
So wird jetzt aus der Docbook-XML-Datei  eine kleine Website, indem jede Section eine HTML-Seite wird:
<pre>
e:
cd \var\www\htdocs\docbook
xslt_chunk gmo_chronik
</pre>

== 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|MicrosoftHTMLHelp]]-Workshop und dann ganz einfach:
<nowiki>
hhc htmlhelp.hhp 
</nowiki>
[[http://codeproject.com/winhelp/docbook_howto.asp|http://codeproject.com/winhelp/docbook_howto.asp]]

== DocBook Beispiel ==
<nowiki>
<?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 Personalkapazitä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 vorangegangenen Phase erfolgen. Aufwandsschätzung beruht auf zwei Größen: <emphasis>Arbeitsmenge und Arbeitsproduktivität.</emphasis>
  </para>
  <para>Wesentlich ist auch der Zeitpunkt der Aufwandsschätzung: Vor der Erstellung eines Fachkonzepts können nur grobe Erfahrungswerte und Analogieschlüsse zur Anwendung kommen. Auf der Basis eines Fachkonzepts 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>
</nowiki>

== Weblinks ==
* DocBook-Tutorial: [[http://www.sagehill.net/docbookxsl|http://www.sagehill.net/docbookxsl]]

-- Main.DietrichKracht - 10 Jul 2004