onsite
Project AXitd

AXitd DU1 DocBook Umgebung V2.0

Installation, Bedienung und Anpassung

Copyright AXitd.

Software und Dokumentation werden unter der GNU GENERAL PUBLIC LICENSE publiziert, eine Kopie der Lizenz befindet sich im root-Ordner. (Copying.txt)

Die vorliegende SW ist nach dem Open Source Prinzip frei erweiterbar und übertragbar. AXitd haftet nicht für Schäden, die durch Installation oder Betrieb dieser SW entstehen.

Versionsgeschichte
Version 012004-11-07

Starting Version

Version 022004-12-31

DU1.1

Added Chapter 9- Profiling, new publishing batches, imagelist feature, new FAQs, general revision, Appendix Reference

Version 032005-03-01

DU1.2

help systems and context sensitive help, translation management, Appendix DocBook with XXE

Version 032005-12-01

DU2

Modular Docbook files using XInclude and olinks, mindmap conversion


Inhaltsverzeichnis

1. Was ist neu in DU1 2.0 ?
2. Zweck
3. Quickstart
4. Installation
Entpacken /Struktur
Systemumgebung einrichten
5. Dokumente erstellen
Eine neues DocBook Dokument beginnen.
Das Dokument zum Publizieren vorbereiten
6. Publikation
Publikation mit GUI Oberfläche
Publikation in HTML (eine komplette HTML-Seite)
Publikation in HTML (Chunks, Einzelseiten)
Publikation in PDF
Titelseiten
Inhaltsseiten
PDF Datei erzeugen
Anpassung der PDF-Ausgabe
Publikation in Windows Help (chm-Format)
Kontextsensitive HTML-Hilfen mit <?dbhh?>
Publikation in JavaHelp
Java Help Umgebung installieren
Help Dateien generieren
Indexfile aufbereiten
Datenbank für Volltextsuche generieren
JavaHelp im helpset Viewer testen
Dateien zur Publikation packen
Publikation in RTF o. WML
Konfiguration
RTF bearbeiten
Customization Layer (driver_xsl)
driver_html.xsl
driver_html_chunks.xsl
driver_htmlhelp.xsl
driver_htmlhelp_projectfiles.xsl
driver_javahelp.xsl
Konfigurationsdateien
make_pdf.bat
make_pdf_module.bat
Titelseiten_template_erzeugen.bat
make_html_chunk.bat
make_html.bat
make_html_module.bat
make_htmlhelp.bat
make_javahelp.bat
make_javahelp_profile.bat
make_htmlhelp_config.bat
resolve_modules.bat
make_datafile_html.bat
make_datafile_pdf.bat
make_freemind.bat
make_imagelist.bat
7. Modulare Dokumente
Übersicht
Konzept von XInclude
Dokumentation planen und beginnen
Masterdokument anlegen
Module anlegen
Module erstellen
Grafiken und Pfadangaben
Verlinkung von Modulen
Erfassen von Dokumenten in XXE
Masterdokument öffnen
Referenziertes Dokument öffnen und bearbeiten
Publikation Gesamtdokumentation
XIncludes auflösen
Gesamtdatei nach HTML publizieren
Gesamtdatei nach PDF publizieren
Publikation andere Formate
Publikation Profiling
Verwendung sitemap Element
8. Übersetzungsmanagement
Erstübersetzung
Vorbereitung TM System
Übersetzungspaket vorbereiten
Übersetzung von DocBook XML-Dateien
Publikation der Übersetzung
Übersetzung Update
Identifikation Änderungen
Übersetzung der Änderungen
Publikation von Updates
9. Bedingter Text (Profiling)
Einzelne Textpassagen mit bedingtem Text
Mehrere Profiling Bedingungen
Profiling Prozess
Einstufiges Profiling in DU1
Zweistufiges Profiling in DU1
Standardproduktionen mit Profiling
10. Tools
Mindmap: freemind export
Übersicht über verwendete Grafiken
Remap Tool
DOCBook XSL Configurator
Zweck
XSL Configurator starten
Mit dem XSL Configurator arbeiten
11. FAQs
FAQs
A. Referenz Befehle in DU1
B. DocBook mit XXE
Allgemein
Arbeitsbereiche
Navigation
Elemente einfügen
Validieren der Dokumente
Text und Inline Elemente
Absätze
Inline Formatierungen
Verweise (Links)
Grafiken
mediaobject
figure
inlinemediaobject
Tabellen
table (mit Titel)
informaltable (ohne Titel)
Tabellen anpassen
Listen
itemizedlist
orderedlist
variablelist
simplelist
Hervorgehobene Absätze
warning, note, caution, important, tip
Example
programlisting
C. DocBook XML
Ein neues DocBook beginnen
set, book oder article?
Stichwortverzeichnis

Tabellenverzeichnis

A.1. Kommandos
B.1. Arbeitsbereiche XXE
B.2. table (Kopf_Zeile)
B.3. table

Beispiele

6.1. Kommentierte Beispiele zur HTML Anpassung
6.2. Kommentierte Beispiele zur HTML-Chunk Anpassung
6.3. Beispiel zur Anpassung der HTML Help Ausgabe
6.4. Beispiel zur Anpassung der JavaHelp Ausgabe
7.1. Beispiel: target database für Output einer (non chunked) HTML Datei
B.1. Beispiel 1

Kapitel 1. Was ist neu in DU1 2.0 ?

  • tool: xmllint for resolving XIncludes

  • Creating and processing modular DocBook Files

  • Description: modulare DocBooks with XXE

  • New DocBook Stylesheets 1.69.1

  • New DocBook DTD 4.4

  • Copying image subfolders in output for modular use

  • tool: xsltproc to resolve XIncludes an creating data file for modular processing

  • Stylesheet make_freemind.bat to create freemind mindmaps from your DocBook Document

Details siehe: whats_new_inDU2.txt im root-Verzeichnis

Kapitel 2. Zweck

Die vorliegende Dokumentation ist eine Arbeitsprotokollierung, die ich bei der Entwicklung anfertige, es ist keine vollständige und überarbeitete Benutzerdokumentation. Sie soll Anleitung zur Installation und Einrichtung zur Bedienung der AXitd DocBook Umgebung. Die aktuellste Version können Sie im Downloadbereich auf der AXitd Homepage erhalten. Die Dokumentation wird weiterentwickelt und erhebt keinen Anspruch auf Vollständigkeit. Sie beschreibt nicht die Elemente oder detaillierte Erfassung von DocBook Dokumentationen. Informationen dazu finden sie über die DocBook Wiki page.

Die AXitd DocBook Umgebung enthält alle für die beschriebenen Publikation notwendigen Komponenten.

[Tipp]Tipp

In der vorliegenden Version der AXitd DocBook Umgebung ist die vorliegende Dokumentation als Beispieldatei enthalten ..du1/ Projects/du1/du2_0.xml . Alle Publikationsskripts sind auf diese Datei voreingestellt

Spielen Sie die verschiedenen Publikationen einmal mit dieser Datei durch, bevor Sie mit Ihrer eigenen Dokumentation beginnen.

Fertigen Sie eine Sicherheitskopie des Publishing Ordners ../publish/ bevor Sie die Dateien modifizieren

Kapitel 3. Quickstart

AXitd DU1 ist eine kommandobasierte Umgebung um XML-Dokumente, die auf der DocBook-DTD basieren, zu erstellen und zu publizieren.

Installieren Sie die setup.exe in das vorgegebene Verzeichnis c:\du1\ und wechseln Sie ins Verzeichnis: c:\du1\publish

Um eine Befehlsübersicht über die DU1 Befehle zu bekommen starten Sie die Datei start_du1.bat mit Doppelklick oder durch Aufruf aus einer DOS Konsole.

Im Verzeichnis DU1\publish finden Sie für Testzwecke Batch-Dateien mit der Bezeichnung test_html.bat und test_pdf.bat, die Sie mit Doppelklick oder über die DOS-Eingabebox von Windows starten können. Wenn Sie die Publikationen ins output-Verzeichnis publizieren können, können Sie sicher sein, dass alle notwendigen Komponenten funktionieren und Sie mit Ihrer Dokumentation beginnen können.

Starten Sie die Datei test_html.bat, es wird eine HTML-Version der vorliegenden Dokumentation erstellt.

Das Ergebnis sehen Sie dann im Ordner: /DU1/output/output.htm

Wiederholen Sie den Vorgang mit der test_pdf.bat für die PDF- Ausgabe. Das Ergebnis finden Sie unter /DU1/output/ausgabe.pdf

Wozu dienen die batch-Dateien? Wenn Sie die *.bat Dateien mit dem Texteditor öffnen, werden Sie sehen, dass diese immer nach dem gleichen Prinzip vorgehen: Es wird eine XML Datei (Ihre DocBook Dokumentation) mit bestimmten Stylesheets in ein Zielformat umgewandelt. In diesem Fall ist dies die vorliegende Dokumentation, die sich im Ordner DU1/Projekte/project1/ docbook_env_doc.xml befindet.

Kapitel 4. Installation

Vor dem ersten produktiven Einsatz sind einmalig einige Einstellungen notwendig, die die Komponenten auf Ihre Umgebung abstimmen.

Vorher können Sie aber alle Komponenten auf die Funktionsfähigkeit in Ihrer Umgebung testen, indem Sie ohne Veränderungen nacheinander die Batchdateien test_html.bat und test_pdf.bat aus dem Ordner ../publish starten und die Ergebnisse im Ordner ../output kontrollieren. siehe: Kapitel 3, Quickstart

Die Komponenten FOP und Saxon benötigen das SUN Java Runtime Environment. ™Wenn Sie dieses noch nicht auf Ihrem Rechner installiert haben, installieren Sie die neueste Version von der SUNhomepage

Für die Erstellung einer HTML-Hilfe benötigen Sie zusätzlich den Microsoft HTML Workshop™, den Sie sich in der neuesten Version kostenlos von der Microsoft Homepage herunterladen können.

Entpacken /Struktur

  1. Installieren Sie die setup.exe vorzugsweise in das vorgegebene Verzeichnis c:\DU1

[Anmerkung]Anmerkung

DU1 enthält alle notwendigen Systemprogramme, wie Saxon, FOP etc. die für die Ausführung der Stylesheets notwendig sind inklusive der Stylesheets selbst.

Wechseln Sie in den Ordner: c:\DU1

Nach dem Entpacken existiert folgende Verzeichnisstruktur, die hier kurz beschrieben ist:

c:\Du1\

OrdnerBeschreibung
documentationDie vorliegende Dokumentation
fontsHier können Sie Schriften für FOP anlegen
FOPApache Formatting Object Prozessor zur PDF Erzeugung
ProjectsIhre Dokumentationsprojekte. Angelegt sind 3 Beispielordner mit den Beispieldokumenten, einer davon für modulare Dokumentationen. Sie können hier beliebig viele Dokumentationsprojekte mit beliebigem Namen anlegen
outputOutput Directory für alle Ausgabeformate
xslaktuelle DocBook Stylesheets
publishStartdateien für alle Ausgabeformate und Programme zum Erzeugen derselben. Im Unterordner driver liegen die Customization Layer für die verschiedenen Ausgabeformate
saxonSystemdateien für den XSL-Parser Saxon
xmllint2libxml2 tool xmllint das die XIncludes von modularen Dokumenten auflöst, sowie xsltproc als alternativen XSL Prozessor
strukturaktuelle DocBook DTD

Systemumgebung einrichten

Um die Publikationsskripts aus jeder beliebigen Verzeichnisebene starten zu können, müssen Sie DU1 einmalig Ihrer Systemumgebung bekannt machen.

Öffnen Sie zuerst die Datei setPfad.bat aus dem Verzeichnis DU1\publish mit einem Texteditor. Kontrollieren Sie, ob die markierte Umgebungseinstellung mit Ihrem Installationsverzeichnis übereinstimmt. Ändern Sie den Eintrag gegebenenfalls:

Starten Sie danach die Windows Systemsteuerung: Start => Einstellungen => Systemsteuerung => System => Reiter "Erweitert" => Schalter: Umgebungsvariablen

Wählen Sie Pfad unter Benutzervariablen aus, klicken Sie auf Bearbeiten und erweitern Sie die Variable um den Pfad c:\DU1\publish; hinter dem letzten Eintrag.

Sie können nun die DU1 Kommandos aus jeder beliebigen Verzeichnisebene aus einer DOS-Box aufrufen.

[Anmerkung]Anmerkung

Kontrollieren Sie die Pfadumgebung, indem Sie in einer DOS Konsole den Befehl SET eingeben. Sie sollten dann die DU1 Umgebung wiederfinden.

Starten Sie dazu die Kommandozeile z.B. über Start -> Ausführen->cmd

Geben Sie Ihre AXitd Du1 Kommandos ein:

Für die PDF-Ausgabe müssen Sie schließlich noch das Verzeichnis der vorhandenen Schriftarten angeben, das sogenannte fontBaseDir. Wenn Sie DU1 ins standardmäßig vorgegebene Verzeichnis c:\du1 installiert haben ist keine Anpassung notwendig. Wenn Sie in ein anderes Verzeichnis installiert haben müssen Sie die Datei ~\du1\FOP\userconfig.xml entsprechend anpassen. Öffnen Sie dazu die Datei userconfig.xml mit einem Texteditor. Ändern Sie den Parameter fontBaseDir indem Sie ihn an Ihr Installationsverzeichnis anpassen.

Speichern Sie die Änderungen ab. Wenn Sie nun neue Schriftarten hinzufügen, müssen Sie diese dem angegebenen Verzeichnis hinzufügen.

Kapitel 5. Dokumente erstellen

Die folgenden Ausführungen beziehen sich auf das Erfassen der Dokumentation im XML Editor: XML Mind XML Editor Standard Edition™. Dieser Editor ist in der Standardversion kostenlos erhältlich und eignet sich besonders für das Erfassen von DocBook Dokumenten.

Nachteil: Editieren der XML Sourcedatei, wie in einigen Fällen notwendig (z.B zum Einfügen von Seitenumbrüchen) ist nicht vorgesehen. Dazu muss auf einen Texteditor ausgewichen werden. Weitere Informationen hierzu auf der XML Mind Website. Generell ist das Erfassen von DocBook Dokumenten in jedem beliebigen XML-Editor möglich, allerdings ist zu bedenken, dass durch die DocBook Unterstützung einiger XML Editoren einiges an Arbeit abgenommen werden kann.

Als Beispieldatei ist die vorliegende Dokumentation im Ordner DU1\Projects\DU1\du2_0.xml enthalten. Öffnen Sie diese Datei um mit der Publikation vertraut zu werden oder ändern Sie diese und benennen sie um.

Eine neues DocBook Dokument beginnen.

Sie können ein neues Projekt starten, indem Sie ein bestehendes Dokument in einen neuen Projektordner kopieren oder ein neues Projekt mit dem Befehl: make_new starten. Starten Sie dazu den DU1 Standardaufruf: make_new [Projekt] [Name der XML Datei]

make_new Project3 neue_datei

Es wird ein neuer Ordner Project3 in der Verzeichnisebene DU1\Projects\ erzeugt. Es wird ein image Verzeichnis mit eineigen Grunddaten in diesen Ordner angelegt. Es wird eine Dummydatei neue_datei.xml mit vorgegebenen Einstellungen und grundlegenden Einträgen erzeugt.

Wenn Sie ein bestehendes Projekt als Grundlage kopieren wollen:

Öffnen Sie dazu ein Beispieldokument aus dem Verzeichnis DU1\Projects\Project1\

[Anmerkung]Anmerkung

Für die spätere Verarbeitung ist es unbedingt notwendig, dass Sie die Datei in der unter der Verzeichnisebene Projects anlegen. Platzieren Sie Ihre Grafiken im Unterverzeichnis ./images

Erfassen Sie ihr Dokument nach den DocBook Vorlagenregeln. Validieren Sie Ihr Dokument nach der DocBook DTD, die sich im Verzeichnis ../resources befindet

Eine Einführung über das Arbeiten mit DocBook in XXE (XMLMind XML Editor) ist hier beschrieben: Anhang B, DocBook mit XXE

Weiterführende Informationen zum Erstellen von DocBook Dokumenten erhalten Sie auf der DocBook Wiki Seite.

Das Dokument zum Publizieren vorbereiten

Speichern Sie das erfasste Dokument und vergewissern Sie sich, dass Sie Ihre Konfigurations-Files für die Publikation entsprechend Ihren Vorstellungen angepasst haben oder verwenden Sie die AXitd Standardvorlagen.

Kapitel 6. Publikation

Wenn Sie nur eine Testpublikation zur Voransicht Ihres Dokumentes machen wollen, verwenden sie die standardisierte Ausgabe Ihres XML-Editors. Im XML Mind XML Editor gibt es z.B. eine standardisierte Konvertierungsumgebung, die speziell auf DocBook Ausgabe angepasst ist (Unter Docbook->Dokument konvertieren->HTML Ausgabe)

Für eine Ihren Corporate Identity angepasste Ausgabe sollten Sie die Ausgabe über die AXitd Umgebung anpassen oder diese verwenden.

Starten Sie für die folgenden Schritte eine DOS Kommandozeilenbox, indem Sie z.B. über Start -> Ausführen -> cmd die DOS-BOX öffnen

[Anmerkung]Anmerkung

Um die DU1 Kommandos aus jeder beliebigen Verzeichnisebene ausführen zu können müssen Sie zuerst Ihre Pfadvariable angepasst haben: siehe „Systemumgebung einrichten“

Publikation mit GUI Oberfläche

Wird in V3 beschrieben. Welche GUI Sie verwenden können, wie diese konfiguriert werden etc.

Publikation in HTML (eine komplette HTML-Seite)

Starten Sie zur Publikation eine DOS Eingabebox.

  1. Starten Sie die HTML-Publikation durch den Standardaufruf: make_html [Projektordner] [XML-Datei ohne Dateiendung]

    make_html du1 du2_0 
  2. Überprüfen Sie die Ausgabe im Verzeichnis DU1\output\output.htm, indem Sie diese öffnen. Entspricht die Ausgabe nicht Ihren Wünschen, passen Sie die Datei DU1\publish\driver\driver_html.xsl entsprechend an und wiederholen die Publikation. Verwenden Sie zur Anpassung die HTML-Parameter von DocBook.

    Eine Übersicht aller DocBook-Parameter für die HTML-Ausgabe finden Sie im Ordner: DU1\xsl\doc\html\index.html

    siehe: „driver_html.xsl“

Publikation in HTML (Chunks, Einzelseiten)

Öffnen Sie eine DOS Konsole:

  1. Starten Sie die HTMLchunk-Publikation durch den Standardaufruf: make_html_chunk [Projektordner] [XML-Datei ohne Dateiendung]

    Ihre Grafiken werden automatisch ins Verzeichnis DU1\output\images verschoben

    make_html_chunk du1 du2_0 
  2. Überprüfen Sie die Ausgabe im Verzeichnis DU1\output\index.html . Entspricht die Ausgabe nicht Ihren Wünschen, passen Sie die Datei DU1\publish\driver\driver_html_chunks.xsl entsprechend an und wiederholen die Publikation. Verwenden Sie zur Anpassung die HTML-Parameter von DocBook.

    [Anmerkung]Anmerkung

    Das Ausgabeverzeichnis für die generierten HTML-Seiten wird als Parameter beim Aufruf übergeben. Standardmäßig wird ins Verzeichnis output publiziert.

    Speichern Sie die Änderungen ab.

Publikation in PDF

Die Publikation in PDF muss in zwei Schritten vorgenommen werden:

  1. Definition der Titelseiten

    Lesen Sie für die ausführliche Beschreibung zur Gestaltung der Titelseiten DocBook von Bob Stayton oder verwenden Sie die vorkonfigurierte AXitd Variante und passen diese an Ihre Bedürfnisse an.

  2. Gestaltung der fortlaufenden Seiten

Titelseiten

Mit der Datei DU1\publish\make_titelseiten.bat können Sie ein Stylesheet (notwendige XSL-Datei) für Ihre persönliche Titelseite erzeugen. Eine Anpassung dieser Datei ist nicht notwendig.

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar  
com.icl.saxon.StyleSheet 
-o %home%xsl\fo\mytitlepage.xsl 
%home%xsl\fo\mytitlepage.spec.xml 
%home%xsl\template\titlepage.xsl

Was passiert beim Aufruf?

  • XSL Prozessor Saxon generiert mittels des Stylesheets:titlepage.xsl eine Datei mytitlepage.xsl, die im Stylesheet Verzeichnis von Docbook (DU1\xsl\fo\) abgelegt wird. Diese Datei wird bei der späteren Umwandlung zu XSL:FO angezogen um Ihre persönliche Titelseite zu generieren.

  • Die Angaben für die Datei mytitlepage.xsl werden der Datei: mytitlepage.spec.xml entnommen, in der Sie die Gestaltung Ihrer Titelseite festlegen müssen. Hier werden allerdings nur das Layout und nicht die Parameter (wie z.B. Titel, Titelbild) festgelegt. Die Datei befindet sich in DU1\xsl\fo\mytitlepage.spec.xml

Um eine persönliche Titelseite zu entwerfen öffnen Sie die Datei DU1\xsl\fo\mytitlepage.spec.xml

<!--
        ********************************************************************
        $Id: titlepage.templates.xml,v 1.22 2003/09/16 16:29:34 bobstayton Exp
        $ ********************************************************************
        This file is part of the DocBook XSL Stylesheet distribution. See
        ../README or http://docbook.sf.net/ for copyright and other
        information.
        ********************************************************************
        --> <!--
        ====================================================================
        --> <t:titlepage font-family="{$title.fontset}"
        t:element="article" t:wrapper="fo:block">
        <t:titlepage-content t:side="recto"
        text-align="center"> <title
        font-size="24.8832pt" font-weight="bold"
        keep-with-next="always"
        param:node="ancestor-or-self::article[1]"
        t:named-template="component.title"></title>
        <subtitle></subtitle> <corpauthor
        font-size="14.4pt"
        space-before="0.5em"></corpauthor>
        <authorgroup font-size="14.4pt"
        space-before="0.5em"></authorgroup> <author
        font-size="20.736pt"
        space-before="0.5em"></author> <othercredit
        space-before="0.5em"></othercredit>
        <releaseinfo
        space-before="0.5em"></releaseinfo> <copyright
        space-before="0.5em"></copyright> <legalnotice
        font-family="{$body.fontset}" margin-left="0.5in" ....
        .....

Editieren Sie die betreffenden Bereiche oder fügen Sie neue Parameter hinzu. Anleitung welche Bereiche sich wie auswirken finden Sie in Bob Staytons Beschreibung bei SageHill

Speichern Sie Ihre Änderungen ab und führen Sie die Datei DU1\publish\make_titelseiten.bat aus.

[Anmerkung]Anmerkung

Standardmäßig wird in der AXitd DocBook Umgebung eine Titelseite mit Titelgrafik d.h eine vorbereitete mytitlepage.xsl bereitgestellt. Machen Sie sich eine Sicherungskopie bevor Sie diese modifizieren. Die Titelgrafik wird im Element <bookinfo> am Anfang Ihres Dokumentes festgelegt.

Um anspruchsvollere Titelseiten zu entwerfen sollten Sie in Ihrem Konfiguration-File (driver_fo.xsl) eine Tabelle mit den Elementen Ihrer Titelseite entwerfen, die das Positionieren der Elemente vereinfacht. Wenn das zu aufwendig ist (z.B. bei Einmalproduktion) empfehle ich die Titelseiten in einem DTP-Programm zu entwerfen und im PDF auszutauschen.

Inhaltsseiten

Aufbau und Parameter der fortlaufenden Seiten legen Sie in der Datei DU1\publish\driver\driver_fo.xsl fest. Definieren Sie hier:

  • Schriftgrößen

  • Schriftart

  • Fußzeilen, Kopfzeilen

  • Papierformat

  • Ausrichtung

etc.

<xsl:import
        href="..\..\xsl\fo\docbook.xsl"/> <xsl:include
        href="..\..\xsl\fo\mytitlepage.xsl"/>
        <!-- bookmarks --> <xsl:param
        name="fop.extensions"
        select="1"></xsl:param> <xsl:param
        name="paper.type"
        select="'A4'"></xsl:param> <xsl:param
        name="table.frame.border.color"
        select="'blue'"></xsl:param>
        <xsl:param name="table.cell.border.color"
        select="'blue'"></xsl:param>
        <xsl:param name="tablecolumns.extension"
        select="'1'"></xsl:param> <xsl:param
        name="alignment">left</xsl:param>
        <xsl:param name="section.autolabel"
        select="1"></xsl:param> <xsl:param
        name="section.label.includes.component.label"
        select="1"></xsl:param> <xsl:attribute-set
        name="section.title.level2.properties"> <xsl:attribute
        name="font-size"> <xsl:value-of
        select="$body.font.master * 1.228"></xsl:value-of>
        <xsl:text>pt</xsl:text> </xsl:attribute>
        </xsl:attribute-set> ..... .....

Anleitung welche Bereiche sich wie auswirken finden Sie in Bob Staytons Beschreibung Print Customizations bei Sagehill.

Bei der PDF- Ausgabe werden für Grafiken die Skalierungsattribute des imagedata Elementes herangezogen um die Grafiken auf der ausgegebenen Seiten entsprechend zu skalieren. Für Seitenbreite wurde eine Grafikbreite von 12cm verwendet, für halbe Seite sind 8cm voreingestellt.

Diese Grafikskalierung wurde bei der Ausgabe in HTML ausgeschaltet. Dort werden die Originalgrößen der Grafiken verwendet. (Attribut ignore.imagescaling in den html- Konfigurationsdateien)

[Tipp]Tipp

Wenn Sie die Grafiken in HTML und PDF Ausgabe verschieden skalieren wollen, müssen Sie in das mediaobject mehrere imageobjecte einfügen und diese unterschiedlich skalieren. Bei der Ausgabe müssen Sie den Parameter

<xsl:param name="preferred.mediaobject.role"></xsl:param>

entsprechend anpassen. Mit diesem Parameter können Sie bestimmen, welche der Grafiken bei der Ausgabe bevorzugt ausgegeben werden.

PDF Datei erzeugen

Wechseln Sie zur Publikation in Ihre DOS-Konsole.

  1. Starten Sie die PDF-Publikation durch den Standardaufruf: make_pdf [Projektordner] [XML-Datei ohne Dateiendung]

    make_pdf du1 du2_0 
  2. Es wird zuerst eine XLS:FO Datei ins Verzeichnis ../output/temp_output.fo erzeugt. Die Verarbeitung wird hier angehalten und kann mit Tastendruck fortgesetzt werden. Zu diesem Zeitpunkt können Sie die Datei noch bearbeiten, bevor Sie die Umwandlung in PDF mit einer beliebigen Taste fortsetzen. Dies ist zum Beispiel dann hilfreich, wenn Sie noch bestimmte Element einfügen oder entfernen wollen, etwa, wenn ein bestimmter Prozessor bestimmte Elemente von DocBook nicht verarbeitet.

  3. Die Ausgabe der PDF-Datei erfolgt ins Verzeichnis ../output/ausgabe.pdf

    Während der PDF-Generierung durch FOP (Formatting Objects Processor) kommt es zu einer Reihe von Fehlermeldungen, die daraus resultieren, dass FOP nicht alle Elemente der XSL:FO Spezifikation implementiert hat. Ignorieren Sie diese Fehlermeldungen solange eine komplette PDF-Datei ins Ausgabeverzeichnis exportiert wird.

    Sollte die Ausgabe jedoch durch FOP abgebrochen werden müssen Sie Ihre Umgebung evtl. umkonfigurieren oder zusätzliche Komponenten installieren, siehe Kapitel 11, FAQs

Anpassung der PDF-Ausgabe

Wenn Sie die PDF Datei erzeugt haben werden Sie feststellen, dass es an einigen Stellen noch Verbesserungsbedarf gibt, um ein optimales Printergebnis zu erreichen. Nachfolgend einige Tipps zur Verschönerung:

[Anmerkung]Anmerkung

Führen Sie die folgenden Anpassungen erst nach Fertigstellung Ihrer Dokumentation oder an einer Sicherheitskopie durch.

Schriftart wechseln

Die Schriftart wird in der Datei ./output/driver/driver_fo.xsl im Parameter

<xsl:param name="body.font.family">sans-serif</xsl:param>

festgelegt. Standardmäßig stellt FOP die Schriftarten: serif, sans-serif und monospace zur Verfügung, was in etwa Times, Helvetica und Courrier entspricht. Sie können aber auch jede andere True-Type Schriftart Ihres Systems hier angeben. Mehr zur Einbettung von Schriften siehe: Bob Stayton, DocBook XSL the Definitive Guide Adding a Font to FOP

Programmlistings

Damit Programmlistings nicht über den vorgesehenen Platz hinauslaufen empfiehlt es sich die Ausgabe entsprechend anzupassen, d.h. Zeilenumbrüche in Programmlistings einzufügen, auch wenn das teilweise die Lesbarkeit beeinträchtigt.

Seitenumbrüche in AXitd DU1

Entscheiden Sie sich einen harten Zeilenumbruch einzufügen, müssen Sie in der XML-Sourcedatei an die entsprechende Stelle die Prozessanweisung, z.B. wie hier zwischen zwei <sect2> Elementen , also Unterabschnitten eingeben. Verwenden Sie dazu einen Texteditor.

[Tipp]Tipp

Im XML Mind XML-Editor können Sie diese Processing Instruction (PI) als Kommentar eingeben, als Prozessanweisung funktioniert es nicht, weil kein Ziel der Anweisung angegeben ist. Rufen Sie dazu unter: Bearbeiten -> Kommentar -> Kommentar einfügen auf und geben Sie <?axitd-pagebreak ?> ein

</sect2> 
        <?axitd-pagebreak ?>  ---hier beginnt der neue sect2---
<sect2 id="html_single">

Diese Prozessanweisung wird in der driver_fo.xsl Datei abgefragt und mit einem Pagebreak in XSL:FO umgesetzt. (Beispiel aus driver-fo.xsl)

<!-- eigener pagebreak --> 
<xsl:template match="processing-instruction('axitd-pagebreak')">
      <fo:block break-before='page'></fo:block>
</xsl:template>

Sie können die Prozessanweisung natürlich auch entsprechend umbenennen.

Text-align

Wenn Sie Blocksätze anstelle der voreingestellten Flattersätze verwenden, werden die Blöcke bei langen Filenamen oft unschön dargestellt, weil die Trennregeln nicht greifen. Es empfiehlt sich lange Filenamen durch Leerzeichen an geeigneter Stelle zu trennen. Den Parameter zur Ausrichtung des Textes können Sie im driver-fo.xsl umstellen (left, justify (Blocksatz),right). In DU1 werden die filenames durch whitespaces getrennt ausgegeben um automatische Zeilenumbrüche zu ermöglichen.

<xsl:param name="alignment">left</xsl:param>

Publikation in Windows Help (chm-Format)

Die Ausgabe der HTML-Files für die chm-Erstellung verläuft ähnlich wie in der HTML-Chunk Erzeugung. Legen Sie zuerst Ihre Parameter in der Datei: DU1\publish\driver\driver_htmlhelp.xsl fest oder verwenden Sie die standardmäßig vorgegebenen.

<xsl:stylesheet
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      version="1.0"> <xsl:import
      href="..\..\xsl\htmlhelp\htmlhelp.xsl"/> 
      <!-- Navigation im HTMLTeil
      ermöglicht wichtig --> <xsl:param
      name="suppress.navigation" select="1"/> <!--
      Grafiken zum Navigieren --> <xsl:param
      name="navig.graphics" select="0"/> <!-- Titel
      der über der Hilfe angezeigt wird, nicht Dateiname -->
      <xsl:param name="htmlhelp.title"
      select="'AXitd'"/> <!-- === fügt Stylesheet ein
      === --> <xsl:param
      name="html.stylesheet.type">text/css</xsl:param>
      <xsl:param name="html.stylesheet"
      select="'html.css'"></xsl:param> <!--
      ========================= --> <!-- filename für output -->
      <xsl:param name="htmlhelp.chm" select="'docbook_env.chm'"/>

Legen Sie z.B. den Namen der zu erzeugenden komprimierten Hilfe fest. (fett markiert). Mehr dazu unter Bob Stayton at Sagehill: HTMLHELP Customization oder unter Jirka Koseks Anleitung bei Sourceforge

Wechseln Sie in der DOS Eingabe ins Verzeichnis: DU1\publish

  1. Starten Sie die HTML-help-Publikation durch den Standardaufruf: make_htmlhelp [Projektordner] [XML-Datei ohne Dateiendung]

    Die HTML-Dateien und die Projektdateien werden in das Ausgabeverzeichnis ..\output exportiert.

    Ihre Grafiken werden automatisch ins Verzeichnis ..\output\images kopiert. Dies geschieht auch, wenn Sie die gleiche Datei zum wiederholten Male publizieren und Sie Grafiken modifiziert haben. Es empfiehlt sich daher das DU1\output Verzeichnis von Zeit zu Zeit zu bereinigen.

    make_html_help du1 du2_0 
  2. Im output-Verzeichnis sind jetzt folgende Dateien abgelegt:

    [Anmerkung]Anmerkung

    Das Ausgabeverzeichnis für die generierten HTML-Seiten wird als Parameter übergeben

Starten Sie die in der Abbildung rot markierte Datei htmlhelp.hhp mit Doppelklick oder öffnen Sie diese aus dem Microsoft HTML Workshop.

[Anmerkung]Anmerkung

Dazu müssen Sie dem Microsoft HTMLHelp Workshop auf Ihrem Rechner installiert haben.

Im HTML-Workshop können Sie die Ausgabe nocheinmal bearbeiten (Schriftgröße, Navigation etc.) oder direkt kompilieren, indem Sie File -> Compile. auswählen und die Kompilierung starten. Mehr zur nachträglichen Anpassung in den integrierten Hilfeseiten des HTML-Workshops™.

Kontextsensitive HTML-Hilfen mit <?dbhh?>

Voraussetzung für die Erzeugung kontextsensitiver Hilfen ist das Vorhandensein einer map-Datei oder Zuordnungsdatei, die Ihnen von der SW-Entwicklung zur Verfügung gestellt wird. In dieser Datei muss definiert werden, für welche Dialoge (Bildschirme) eine kontextsensitive Hilfe angezeigt werden soll und welchen Identifikator (ID) diese Hilfe haben muss.

Um die Verknüpfung der Identifikatoren zu Ihrer Docbook Datei herzustellen, ist die Prozessanweisung <?dbhh topicname="some_title" topicid="4321"?> zu verwenden.

Geben Sie an die entsprechende Stelle in Ihrer Datei die enstprechende PI ein. Wichtig ist, dass die PI nur für die Abschnitte verwendet werden kann, für die später auch eine eigene HTML-Instanz erzeugt wird. (ID für Instanz muss vergeben sein)

<chapter id="zweck">
<?dbhh topicname="ID_zweck" topicid="1000"?>
 <title id="titel_zweck">Zweck</title>
   <para>Die vorliegende Dokumentation gibt Anleitung zur Installation und
    Einrichtung zur Bedienung von DocBook Umgebung. Aktuelle Version können
    Sie im Downloadbereich auf der <ulink url="http://www.axitd.de.vu">AXitd
    Homepage </ulink>erhalten. 
....
 </para>
</chapter>
<chapter id="quickstart">
<?dbhh topicname="ID_quick" topicid="1001"?>
 <title>Quickstart<indexterm>
    <primary>Quickstart</primary>
    </indexterm>
   </title>

...

Im vorliegenden Beispiel werden für die IDs: ID_zweck und ID_quick jeweils eine kontextsensitive Hilfeseite zur Verfügung gestellt.

Die HTMLhelp-XSL Stylesheets erzeugen nun automatisch die header-Dateien: alias.h und context.h, die in Ihr HTML-Projekt eingebunden werden. (Beim Kompilieren mit dem HTML Workshop)

alias.h verknüpft die IDs mit der jeweiligen HTML-Datei (hier werden die IDs als Dateiname verwendet)

ID_zweck=zweck.html
ID_quick=quickstart.html

context.h stellt die Verbindung zum HTML-Helpset her

#define ID_zweck   1000
#define ID_quick   1001

Die Ordnungszahlen dienen hierbei nur der internen Verwaltung des HTML-Help Workshops. Der Compiler mapt die numerischen IDs im header file mit den Help Topics.

Kompilieren Sie die Hilfe wie oben beschrieben.

Testen Sie, indem Sie im Menü Test ->HTMLHELP API aufrufen

Testen Sie die kontextsensitiven Instanzen, indem Sie im Feld Map number die Ordnungsnummern aus der context.h eingeben. Im Feld Window geben Sie: main ein. Im Feld Command: HH HELP CONTEXT

Wenn alles klappt sollten die entsprechenden Hilfeseiten aufgerufen werden können.

Publikation in JavaHelp

Die Publikation nach Javahelp ist etwas aufwendiger als die nach HTML-Help. Um die publizierten Dateien weiterzuverarbeiten benötigen Sie je nach Einsatzfall der Hilfe das JavaHelp™ System in der Version 1.1.3 oder 2. DocBook unterstützt in der vorliegenden Version die DTD 1.1.3. Mit wenigen Anpassungen können Sie aber auch Java Hilfen der Version 2 erzeugen. Im Folgenden wird die Vorgehensweise mit der Version 1.1.3 beschrieben.

Von der Logik sind die Steuerdateien der JavaHelp einfacher und zweckgebundener aufgebaut als die HTMLHelp Dateien. Sie lassen sich daher auch einfach selbst erzeugen oder manipulieren.

Sie können Java Hilfen für folgende Szenarios entwerfen.

  • Standalone Anwendung: Läuft ohne Web Browser

  • Netzwerk Anwendung: Für Intranet oder Intranetanwendung

  • Intergrierte Hilfe: In Ihre Anwendung integriert, läuft im Fenster Ihrer Applikation

  • Komponenten Hilfe: Für umfangreiche Anwendungen, die die Hilfe in jeder separaten Komponente zur Verfügung stellen.

  • Help Server: Kontextsensitive Hilfe für Client Server Anwendungen

Java Help Umgebung installieren

Laden Sie sich das JavaHelp System (Datei: javahelp-1_1_3.zip oder javahelp-2_0_02.zip) von der Sun JavaHelp Seite herunter. Entpacken Sie die Distribution in ein Verzeichnis Ihrer Wahl. Lesen Sie die Anweisungen zur Einrichtung der JavaHelp Umgebung in der beiliegenden Readme-Datei und Dokumentation.

Help Dateien generieren

Öffnen Sie eine DOS Konsole.

  1. Starten Sie die JavaHelp-Publikation durch den Standardaufruf: make_javahelp [Projektordner] [XML-Datei ohne Dateiendung]

    Ihre Grafiken werden automatisch ins Verzeichnis DU1\output\javahelp\images verschoben

    make_javahelp du1 du2_0 
  2. Überprüfen Sie die Ausgabe im Verzeichnis DU1\output\javehelp\index.html . Entspricht die Ausgabe nicht Ihren Wünschen, passen Sie die Datei DU1\publish\driver\driver_javahelp.xsl entsprechend an und wiederholen die Publikation. Verwenden Sie zur Anpassung die HTML-Parameter von DocBook.

    Speichern Sie die Änderungen ab.

Indexfile aufbereiten

Da JavaHelp Probleme mit einigen Unicode Steuerzeichen zu haben scheint, müssen Sie zuerst die Datei: jhelpidx.xml aus dem Verzeichnis DU1\output\javahelp mit einem XML- oder Texteditor öffnen und ändern.

Die betreffenden Zeichen sind XML Character Entities, die bei der Publikation kopiert werden. Insbesondere &#xA, &#8220, or &#x8221, Hard Return, Öffnende und schließende Anführungszeichen. Diese können offensichtlich vom integrierten HTML-Browser nicht angezeigt werden.

Entfernen Sie die betreffenden Zeichen und ersetzen Sie durch 'normale' Anführungszeichen. Entfernen Sie den Hard Return

[Tipp]Tipp

Alternativ können Sie auch die common/de.xml im XSL-Verzeichnis nach den Zeichen durchsuchen und durch eine Konfigurationsdatei anpassen. Dann sparen Sie sich die Aufbereitung bei jeder Publikation. Angeblich wird diese Fehlfunktion (nicht von DocBook sondern des JavaHelp Browsers) auch in einer späteren Stylesheet version von DocBook behoben.

Datenbank für Volltextsuche generieren

Als Nächstes müssen Sie eine Datenbank für die Volltextsuche generieren. Dazu steht Ihnen in Ihrem JavaHelp System das Tool:~\jh1.1.3\javahelp\bin\jhindexer.jar zur Verfügung. Für den Test der Datenbank das Tool ~\jh1.1.3\javahelp\bin\jsearch.jar

Datenbank erzeugen

Der jhindexer generiert die Datenbank für die Volltextsuche, die vom JavaHelp System benutzt wird um Treffer anzeigen zu können. Um die Datenbank zu erzeugen benutzen Sie folgendes Kommando.

[Tipp]Tipp

Sie können die erzeugte Datenbank auch im Standalone Betrieb benutzen, lesen Sie dazu die JavaHelp System Dokumentation:

Der allgemeine Aufruf lautet:

Win32 jhindexer [options] [file | folder]*

Für die DU1 Umgebung bedeutet das:

D:\tools\javahelp1_1_3\jh1.1.3\javahelp\bin>java -jar 
jhindexer.jar1 -c config2 -db
c:\du1\output\javahelp\JavaHelpSearch3 c:\du1\output\javahelp\4

Lesen Sie die JavaHelp System Dokumentation für weitere Optionen.

1

Aufruf des tools jhindexer aus dem Installationsverzeichnis Ihres JavaHelp Systems

2

Ihre verwendete Konfigurationsdatei mit dem Namen config. Diese dient für das JavaHelp System u.a. zum Adressieren der Pfadnamen und muss von Ihnen angepasst wird. Liegt in diesem Fall im Verzeichnis des jhindexers

3

Die Daten für die Datenbank werden im Verzeichnis JavaHelpSearch abgelegt, auf die das JavaHelp System standardmäßig zugreift

4

Das Verzeichnis über das die Volltextsuche-Datenbank erstellt wird

Noch ein paar Anmerkungen zum Config File: Dies dient u.a. zum Ändern der Pfadnamen, die beim Erzeugen der Volltextdatenbank gespeichert werden. Wenn sich die Pfade beim Entwickeln und im späteren Help System unterscheiden kann das System im Config File die Pfade wiederfinden

Weitere Anwendungsfälle sind das Einfügen von Stopwörtern, die nicht indiziert werden und die Definition von bestimmten Pfaden für die Indexierung. Mehr dazu in der Dokumentation zum JavaHelp System.

Datenbank für Volltextsuche testen

Öffnen Sie das Tool jhsearch aus Ihrem JavaHelp System

D:\tools\javahelp1_1_3\jh1.1.3\javahelp\bin>
java -jar jhsearch.jar 
c:\du1\output\javahelp\JavaHelpSearch

Der Standardaufruf aus dem Ordner javahelp\bin\ lautet:

Win32 jhsearch database_folder

jhsearch ist ein kommandobasiertes Programm um die Gültigkeit Ihrer erzeugten Datenbank zu testen. Wenn der Programmaufruf erfolgreich ist, meldet sich das Programm wie folgt:

Geben Sie einen Suchbegriff ein, bei erfolgreicher Suche bekommen Sie die Anzahl der Treffer und die zugehörigen Dateien in denen der Treffer auftaucht angezeigt.

JavaHelp im helpset Viewer testen

Nachdem Sie nun Index und Volltextsuche erzeugt und bereinigt haben, können Sie Ihre Hilfe in einer JavaHelp Konsole testen.

D:\tools\javahelp1_1_3\jh1.1.3\demos\bin\>java -jar hsviewer.jar

Es öffnet sich eine Auswahlbox für die Auswahl der Helpsetdatei

Klicken Sie auf Browse und wählen Sie Ihre *.hs Datei aus Ihrem javahelp-Verzeichnis aus (c:\du1\output\javahelp)

Dateien zur Publikation packen

Um die erzeugten Dateien weiter zu verteilen werden sie am Besten ins jar Format gepackt. Benutzen sie dazu das JAR Tool von Java. Packen Sie das helpset-file (*.hs) und die zugehörige map Datei mit in das jar-Verzeichnis. Zusätzlich natürlich die erzeugten HTML Dateien, die Grafiken und die Inhaltsverzeichnisdatei. Um sicherzugehen, dass nichts fehlt sollten Sie das gesamte ~/output/java_output Verzeichnis mit in Ihr Archiv packen

Informationen zur Verwendung und Konfiguration des JAR Tools erhalten Sie im SUN Themenbereich JAR

Publikation in RTF o. WML

Für die hier beschriebene Publikation benötigen Sie den FO- Konverter von XMLMind, den Sie in der Personal Edition kostenlos von der XMLMind Website herunterladen können.

Die folgende Beschreibung basiert auf der Version 2.2p1

Die Publikation ist auch mit anderen Werkzeugen und Methoden notwendig, auf die ich hier nicht näher eingehe, da die beschriebene Methode einfach und ohne Kosten durchzuführen sind und gute Ergebnisse liefern.

Verwenden Sie zum Aufruf des Konverters das XSL Utility, das Ihnen eine grafische Programmoberfläche für Ihre Konvertierung liefert (Aufruf: Programme -> XML Mind FO Converter -> XSL Utility)

Konfiguration

Nach Aufruf des XSL utilities müssen Sie folgende Konfigurationen durchführen:

  1. XML File Input. Geben Sie hier Ihr Input File ein:

  2. Transformation. Geben Sie hier die die Transformation nach RTF oder WML ein und wählen Sie danach den Schalter Edit aus, um das Stylesheet einzugeben

  3. XSL stylesheet. Wählen Sie aus dem Dialog das vorkonfigurierte AXITD Stylesheet aus und wählen Sie als FO Prozessor den XML Mind XFC ein:

Starten Sie nun die Konvertierung in das von Ihnen gewählte Verzeichnis durch Aufruf des Convert Schalters:

RTF bearbeiten

Öffnen Sie nun die erzeugte RTF- Datei aus dem Outputverzeichnis (du1/output) z.B. mit Microsoft Word™ und speichern die Datei im *.doc Format ab. Erfahrungsgemäß sind noch einige Finetune - Maßnahmen erforderlich z.B.

  • Felder aktualisieren (Inhaltsverzeichnis, Index)

  • Seitenumbrüche kontrollieren und anpassen

  • Aufzählungszeichen ersetzen

  • ......

Customization Layer (driver_xsl)

Die AXitd Docbook Umgebung verfügt über eine Reihe von vorkonfigurierten Stylesheets , die es erlauben die DocBook Ausgaben in die verschiedenen Formate Ihren persönlichen Bedürfnissen anzupassen. In der AXitd Umgebung sind die driver-files so voreingestellt, dass Sie in die Ausgabeformate HTML, HTML-help und PDF ohne weitere Einstellungen Technische Dokumentationen für SW und Industriegüter erstellen können. Einige AXitd-Parameter sind anschließend kurz beschrieben. Weiterführende Informationen dazu unter Bob Staytons Beschreibung bei Sagehill.

Wechseln Sie zur Anpassung ins Verzeichnis ~/du1/publish/driver/

Sie können hier folgende Dateien anpassen:

driver_html.xsl

Bestimmt die HTML Ausgabe (Ausgabe einer kompletten HTML Seite)

<xsl:stylesheet
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        version="1.0"> <xsl:import
        href="..\..\xsl\html\docbook.xsl"/> <!--
        +++Grafiken fuer Navigation unterdruecken++++++++++++ -->
        <xsl:param name="navig.graphics" select="0"/>
        <!-- ++++++++Piktogramme zulassen ++++++++++++++++ -->
        <xsl:param name="admon.graphics" select="1"/>1 
<!-- ++++++++++++Tabellen ++++++++++++++++++++++++
        --> <xsl:param name="html.cellspacing"
        select="'0.5'"/> <xsl:param
        name="html.cellpadding" select="'4'"/>
        <!-- +++++++generiert index: im Text muss an Stelle leerer Index
        stehen (<index/>)+++ --> <xsl:param
        name="generate.index" select="1"/>2
        ........ .......

Die Anpassungen sind im Wesentlichen kommentiert, Standardmäßig wird eine Kopf und Fußzeilengrafik erzeugt. Fügen Sie weitere Parameter nach unten genanntem Schema ein.

Eine Übersicht aller DocBook-Parameter für die HTML-Ausgabe finden Sie im Ordner: DU1/xsl/doc/html/index.html

Beispiel 6.1. Kommentierte Beispiele zur HTML Anpassung

1

Wählen Sie 1, wenn die Grafiken für Vorsicht, Achtung, Hinweis etc. angezeigt werden sollen, wählen Sie 0, wenn statt dessen nur der Wortlaut angezeigt werden soll.

2

Soll ein Index (Stichwortverzeichnis) erzeugt werden, so ist dieser Parameter auf 1 zu setzen.

[Anmerkung]Anmerkung

Im der XML Source muss ein leeres Index Element stehen, damit ein Index generiert wird, ansonsten hilft auch der Parameter 1 nicht weiter.

driver_html_chunks.xsl

Bestimmt die HTML Ausgabe in mehrere Seiten (Chunks)

<xsl:stylesheet
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        version="1.0"> <xsl:import
        href="..\..\xsl\html\chunk.xsl"/> <xsl:param
        name="navig.graphics" select="0"/> <xsl:param
        name="admon.graphics" select="1"/> <xsl:param
        name="html.cellspacing" select="'0.5'"/>
        <xsl:param name="html.cellpadding"
        select="'4'"/> <xsl:param
        name="generate.index" select="1"/> <!--
        Benutze die id-Namen als html-Namen -->1
        <xsl:param name="use.id.as.filename"
        select="'1'"> </xsl:param> <!--
        Navigation im HTMLTeil ermöglicht wichtig --> <xsl:param
        name="suppress.navigation" select="0"/> 
        <!--output directory for chunks -->2 
        <xsl:param name="base.dir" select="'..\umgebung_publish\output\'">
        </xsl:param> .....

Standardmäßig wird auch in dieser Ausgabe eine Titelgrafik als Kopfzeile erzeugt.

Die Anpassungen sind im Wesentlichen kommentiert, standardmäßig wird eine Kopf und Fußzeilengrafik erzeugt. Fügen Sie weitere Parameter nach unten genanntem Schema ein.

Eine Übersicht aller DocBook-Parameter für die HTML-Ausgabe finden Sie im Ordner: DU1\xsl\doc\html\index.html

Beispiel 6.2. Kommentierte Beispiele zur HTML-Chunk Anpassung

1

Wenn Sie in Ihrer Dokumentation für die Abschnitte Identifikatoren (IDs) vergeben haben, werden diese als Namen für die HTML-Dateien verwendet, wenn Sie den Parameter setzen. Dies erleichtert das spätere Auffinden im Output-Verzeichnis und die Kontrolle von Links.

2

Dieser Parameter bestimmt, in welches Verzeichnis die HTML Dateien ausgegeben werden. Geben Sie hier Ihr Ausgabeverzeichnis für die erzeugten HTML-Fragmente an. Beachten Sie, dass dieses Verzeichnis die Grafiken für alle Ausgabeformate, sowie evtl eingesetzte Stylesheets (css) enthalten muss.

driver_htmlhelp.xsl

Bestimmt die Ausgabe im HTML-Help Format

...... <!-- ========================= -->
        <!-- filename für output --> <xsl:param
        name="htmlhelp.chm"
        select="'handbook.chm'"/>1
        <!-- Piktogramme anzeigen --> <xsl:param
        name="admon.graphics" select="1"/> <!-- zeigt
        Favoriten an -->2 <xsl:param
        name="htmlhelp.show.favorities" select="1"/>
        <xsl:param name="html.cellspacing"
        select="'0.5'"/> <xsl:param
        name="html.cellpadding" select="'4'"/>
        <!-- benutze die hhk (Index Datei --> <xsl:param
        name="htmlhelp.use.hhk" select="1"/>
        ..............

Die Anpassungen sind im Wesentlichen kommentiert. Standardmäßig wird eine Kopf- und Fußzeilengrafik erzeugt. Fügen Sie weitere Parameter nach unten genanntem Schema ein.

Eine Übersicht aller DocBook-Parameter für die HTML-Ausgabe finden Sie im Ordner: .DU1\xsl\doc\html\index.html

Beispiel 6.3. Beispiel zur Anpassung der HTML Help Ausgabe

1

Name der komprimierten Hilfe

2

Diesen Parameter setzen, wenn die Hilfe das Register Favoriten erhalten soll

driver_htmlhelp_projectfiles.xsl

Dieser Driver unterscheidet sich vom driver_help nur dadurch, dass nicht erneut alle Inhaltsdateien ausgegeben werden sondern nur die Projektdateien, die zur Generierung der komprimierten Hilfe erforderlich sind. Benutzen Sie diese Datei, wenn Sie bereits die HTML Seiten ausgespielt haben und die Hilfe durch Verändern der Parameter noch anpassen wollen. Siehe:„driver_htmlhelp.xsl“

 .......<!-- Es werden nur Projectfiles erzeugt
        --> <xsl:param name="htmlhelp.only"
        select="1"></xsl:param> ..... 

driver_javahelp.xsl

Bestimmt die Ausgabe im JavaHelp Format

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="..\..\xsl\javahelp\javahelp.xsl"/>
<!-- axitd docbook du1.2 03.2005 -->
<!-- Navigation im HTMLTeil ermöglicht wichtig -->1
<xsl:param name="suppress.navigation" select="1"/>
<!-- Grafiken zum Navigieren -->
<xsl:param name="navig.graphics" select="0"/>
<!-- Titel der über der Hilfe angezeigt wird, nicht Dateiname -->
<xsl:param name="htmlhelp.title" select="'AXitd'"/>
<!-- === fügt Stylesheet ein === -->
<xsl:param name="html.stylesheet.type">text/css</xsl:param>
<xsl:param name="html.stylesheet" select="'global.css'"/>2
<!-- ========================= -->

...... 

Die Anpassungen sind im Wesentlichen kommentiert. Standardmäßig wird eine Kopf- und Fußzeilengrafik erzeugt. Fügen Sie weitere Parameter nach unten genanntem Schema ein.

Eine Übersicht aller DocBook-Parameter für die HTML-Ausgabe finden Sie im Ordner: DU1\xsl\doc\html\index.html

Beispiel 6.4. Beispiel zur Anpassung der JavaHelp Ausgabe

1

Soll die Navigation zur folgenden HTML-Seite im Navigationsfenster ermöglicht werden?

2

Jeder HTML Datei wird das Stylesheeet global.css zugewiesen

Konfigurationsdateien

Die Publikationsdateien liegen im Verzeichnis DU1/publish/ und sind das Herzstück der AXitd DocBook Umgebung. Sie steuern die verschiedenen Ausgabeformate in dem sie auf sogenannte driver-files (im Verzeichnis DU1/publish/driver) zugreifen

Diese driver-files sind für das Arbeiten in einer Umgebung technischer Dokumentation von Industriegütern vorbereitet. Für SW Dokumentationen u.ä. können Sie die Files entsprechend anpassen.

Im Folgenden sind die Start und driver-files und ihre Funktionsweise kurz beschrieben

make_pdf.bat

Erzeugt die XSL:FO Ausgangsdatei für PDF,RTF Ausgabe durch FOP oder anderen FO-Prozessoren (z.B. Antenna House XSLT Formatter oder RenderX XEP). Diese Datei wird nach Ihrer Bestätigung in eine PDF-Datei ausgegeben.

Die PDF Erzeugung wurde bewusst in die 2 Schritte: Erzeugung XSL:FO und von dort aus in PDF, getrennt um eventuelle Manipulationen am XSL:FO vornehmen zu können und die FO-Datei für Publikation in andere Medien zur Verfügung zu stellen. Wenn Sie diesen Schritt auslassen wollen können Sie mit FOP auch direkt aus Ihrem XML-Source PDF Dateien erzeugen, siehe dazu die FOP-Dokumentation

java -jar saxon.jar  -o ..\output\temp_output.fo 
..\Projects\%1\%2.xml driver\driver_fo.xsl "fop.extensions=1" 

....

fop -c userconfig.xml -fo "..\output\temp_output.fo" 
"..\output\ausgabe.pdf" 

make_pdf_module.bat

Erzeugt die PDF-Ausgabe, wenn Sie Module zu einem PDF File zusammenfassen wollen. Wie make_pdf.bat in zwei Prozess schritte aufgeteilt.

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar 
 com.icl.saxon.StyleSheet -o %output%\temp_output.fo 
%projects%\%1\%2.xml 
%publish%\driver\driver_fo.xsl 
fop.extensions="1" 
current.docid="%3"

In dieser batch werden die Module mit Referenz auf die ID des aufgerufenen Dokumentes (Parameter: current.docid) aufgerufen. Die Parameter für die Übergabe der Referenzdaten werden durch das driver file: driver_fo.xsl an den XSL Prozessor übergeben:

<!-- olinks -->
<xsl:param name="insert.xref.page.number">no</xsl:param>
<xsl:param name="use.local.olink.style" select="0"></xsl:param> 
<xsl:param name="target.database.document">olinkdb_fo.xml</xsl:param>
<xsl:param name="xref.label-title.separator">: </xsl:param>
<xsl:param name="xref.with.number.and.title" select="1"></xsl:param>

Titelseiten_template_erzeugen.bat

Um die Titelseiten in der PDF-Ausgabe auf Ihre Bedürfnisse anzupassen (Layout, wie z.B.Position der Titelzeile, Grafiken, Elemente etc. , (nicht Inhalt der Elemente, der wird in driver.xsl festgelegt) müssen Sie im ersten Schritt ein Stylesheet mytitlepage.xsl erzeugen.

Dazu bearbeiten Sie zuerst die Datei mytitlepage.spec.xml mit Ihren Vorgaben, woraus DocBook dann eine mytitlepage.xsl erstellt, die bei der Umwandlung in PDF berücksichtigt wird.

In der AXitd DocBook Umgebung ist bereits eine voreingestellte mytitlepage.spec.xml enthalten. Diese können Sie übernehmen oder anpassen.s. Verzeichnis: DU1/xsl/fo/mytitlepage.spec.xml

Näheres zur Erzeugung von Titelseiten für die PDF-Ausgabe siehe Dokumentation zu DocBook.

Wenn Sie Änderungen an der mytitlepage.spec.xml vornehmen können Sie diese mit der Titelseiten_template_erzeugen.bat in die mytitlepage.xsl umwandeln.

saxon -o
"..\xsl\fo\mytitlepage.xsl"
"..\xsl\fo\mytitlepage.spec.xml"
"..\xsl\template\titlepage.xsl"
pause

An der Batch-Datei selbst sind keine Anpassungen notwendig. Bei der nächsten Erzeugung einer PDF-Datei werden Ihre Änderungen, die Sie in der mytitlepage.spec.xml vorgenommen haben wirksam.

make_html_chunk.bat

Steuert die HTML-Ausgabe für Einzelseiten (Chunks), es wird die Anpassungsdatei driver_html_chunks.xsl angezogen.

Ihre XML-Datei wird in mehrere HTML-Einzelseiten zerhackt.

java -jar saxon.jar  "..\Projects\%1\%2.xml" 
"driver\driver_html_chunks.xsl"

Die Ausgabe erfolgt ins Verzeichnis .\output in das auch die zugehörige Grafiken exportiert werden.

[Tipp]Tipp

Sichern Sie die Daten nach Produktion in ein anderes Verzeichnis.(Nach Datum sortieren)

make_html.bat

Steuert die HTML-Ausgabe in eine einzelne HTML-Datei mit Inhaltsverzeichnis. Es wird die Konfigurationsdatei driver_html.xsl angezogen.

java -jar saxon.jar  -o "..\output\output.htm" 
"..\Projects\%1\%2.xml" "driver\driver_html.xsl"

make_html_module.bat

Steuert die HTML Ausgabe, wenn Sie mehrere Module zu einer HTML Datei zusammenfassen wollen.

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar
 com.icl.saxon.StyleSheet 
-o %output%\output.htm 
%projects%\%1\%2.xml 
%publish%\driver\driver_html.xsl 
target.database.document="olinkdb_html.xml" 
olink.base.uri="output.htm" 
current.docid="%3"

Beim Aufrufen des Befehls muss als dritter Parameter die ID des aufrufenden Dokumentes (current.docid) mit angegeben werden. Als Ausgabedatei ist die Datei du1\output\output.htm voreingestellt. Die Referenzen werden mit der target database olinkdb_html.xml aufgelöst, die wiederum auf das Datenfile xxxxx_html.db verweist, die im gleichen Verzeichnis liegt.

make_htmlhelp.bat

Steuert die HTML-Help Ausgabe. Es wird die Konfigurationsdatei driver_htmlhelp.xsl angezogen.

java -jar saxon.jar   "..\Projects\%1\%2.xml" 
"driver\driver_htmlhelp_projectfiles.xsl" 

make_javahelp.bat

Steuert die JavaHelp Ausgabe. Es wird die Konfigurationsdatei driver_javahelp.xsl angezogen.

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar  com.icl.saxon.StyleSheet 
 %projects%\%1\%2.xml %publish%\driver\driver_javahelp.xsl base.dir=%output%\javahelp\

make_javahelp_profile.bat

Steuert die bedingte JavaHelp Ausgabe. Es wird die Konfigurationsdatei driver_javahelp_profile.xsl angezogen.

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar 
 com.icl.saxon.StyleSheet 
 %projects%\%1\%2.xml %publish%\driver\driver_javahelp_profile.xsl 
base.dir=%output%\javahelp\

make_htmlhelp_config.bat

Steuert die Ausgabe der HTML-Help Produktion, wenn Sie nur neue Projektdateien erzeugen wollen (z.B. nach Änderung der HTML-help driver Files etc.) Ihre Projektinhalte aber ansonsten gleich bleiben. Es wird die Anpassungsdatei driver_htmlhelp_projektfiles.xsl angezogen.

 java -jar saxon.jar   "..\Projects\%1\%2.xml" 
"driver\driver_htmlhelp_projectfiles.xsl" 

resolve_modules.bat

Erzeugt mittels des libxml2 tools xmllint eine temporäre XML-Datei, in der die XIncludes durch den Inhalt der referenzierten Module ersetzt werden:

%xmllint%xmllint.exe --xinclude 
%projects%\%1\%2.xml > %projects%\%1\modules_resolved.xml

Die temporäre XML-Datei heißt immer: modules_resolved.xml, wird ins aktuelle Projektverzeichnis publiziert und kann mit den normalen Stylesheets weiterverarbeitet werden.

make_datafile_html.bat

Dient zum Erzeugen des data files für die Zusammenfassung mehrerer Module zu einer HTML Seite.

%xmllint%xsltproc.exe 
--xinclude 
--stringparam collect.xref.targets "only" 
--stringparam targets.filename "%projects%\%1\%2_html.db" 
%home%\xsl\html\docbook.xsl 
%projects%\%1\%2.xml

Für die Produktion kommt das Werkzeug xsltproc™ aus dem Verzeichnis C:\du1\xmllint2\ zum Einsatz, das die im aufrufenden XML-file enthaltenen XIncludes auflöst und eine komplette Datei für alle Referenzen in den verknüpften Modulen erstellt. Die Ausgabe erfolgt in die Datei: xxxxx_html.db, die ins root Verzeichnis Ihres Projektes abgelegt wird. Wird bei der Publikation einer HTML Seite mit dem Befehl make_html_module verarbeitet.

make_datafile_pdf.bat

Dient zum Erzeugen des data files für die Zusammenfassung mehrerer Module zu einer PDF Datei.

%xmllint%xsltproc.exe 
--xinclude 
--stringparam collect.xref.targets "only" 
--stringparam targets.filename "%projects%\%1\%2_pdf.db" 
%home%\xsl\fo\docbook.xsl 
%projects%\%1\%2.xml

Für die Produktion kommt das Werkzeug xsltproc™ aus dem Verzeichnis C:\du1\xmllint2\ zum Einsatz, das die im aufrufenden XML-file enthaltenen XIncludes auflöst und eine komplette Datei für alle Referenzen in den verknüpften Modulen erstellt. Die Ausgabe erfolgt in die Datei: xxxxx_fo.db, die ins root Verzeichnis Ihres Projektes abgelegt wird. Wird bei der Publikation einer HTML Seite mit dem Befehl make_pdf_module verarbeitet.

make_freemind.bat

Dient zum Erzeugen eines mindmaps für eine Projektübersicht.

%xmllint%\xsltproc -o %output%\%2.mm 
#%publish%\driver\tools\docbk2mm.xslt 
%projects%\%1\%2.xml

Für die Produktion kommt das Werkzeug xsltproc™ aus dem Verzeichnis C:\du1\xmllint2\ zum Einsatz, die mittels des Stylesheets docbk2mm.xslt eine Datei erzeugt, die Sie in Freemind öffnen können.

make_imagelist.bat

Erzeugt eine HTML Liste der verwendeten Grafiken.

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar  
com.icl.saxon.StyleSheet 
-o %output%\images.htm 
%projects%\%1\%2.xml 
%publish%\driver\tools\imagedata.xsl 

Mittels des Stylesheets imagedata.xsl wird in das output Verzeichnis eine HTML Datei mit einer Übersicht über alle im aufgerufenen Dokument verwendeten Grafiken erzeugt.

Kapitel 7. Modulare Dokumente

Ab einer bestimmten Größe der Dokumente ist es vorteilhaft, die Dokumentation in kleinere Einheiten zu unterteilen. Dies hat folgende Vorteile:

  • Kleinere Einheiten sind besser händelbar

  • Die Einheiten können in anderen Dokumenten verwendet werden

  • Mehrere Autoren können an einem Dokument schreiben und die Einheiten austauschen

  • Versionskontrolle wird vereinfacht

  • Übersetzungsmodule können besser verwaltet werden

  • Verwaltung in einem CMS vereinfacht

Trotz dieser Vorteile stehen dem modularen Ansatz auch einige Nachteile entgegen, so dass Sie vor Beginn Ihrer Dokumentation genau entscheiden sollten, welchen Ansatz Sie verfolgen:

  • Umfangreiche manuelle Schritte erforderlich

  • Übersichtlichkeit kann verloren gehen

  • Unterstützung in DocBook recht kompliziert gelöst

  • mehr Prozess schritte erforderlich

  • Verlinken von Modulen wird bei der PDF-Ausgabe durch FOP nicht unterstützt

Die AXitd Umgebung unterstützt standardmäßig die Ausgabeformate: HTML (Zusammenfassung aller Module in eine HTML Datei) und PDF (Zusammenfassung aller Module in eine PDF-Datei). Die Beschränkung auf diese beiden Ausgabeformate hat folgende Vorteile:

  1. Es muss nur ein datafile für alle Module erzeugt werden, weil Ausgabeverzeichnis von PDF und HTML bekannt sind

  2. Die AXitd Standdardfiles können für Ihre Dokumentation mit geringen Änderungen übernommen werden

  3. Auch wenn Sie neue Module anlegen müssen Sie die Grunddatenbanken für HTML und PDF nicht verändern

  4. Wichtigster Vorteil: Bei verteilter Datenhaltung der Module müssen Sie die IDs der anderen Module nicht kennen, Ziel auf ID des root- Dokumentes genügt, es müssen nur die Einsprungpunkte bekannt sein, etwa wenn Sie vorher definiert wurden oder in einem standardisierten Verfahren festgelegt sind.

Für weitere Ausgabeformen müssen Sie die Umgebung entsprechend anpassen.

Allgemein ist die Vorgehensweise mit modularen DocBook Dokumenten immer dann empfehlenswert, wenn Sie ein CMS oder DMS zur Verwaltung Ihrer Module zur Verfügung haben. Module in Handarbeit zu verwalten und zu publizieren erfordert schon eine gewisse Disziplin und Kontinuität Ihrer Dokumentation, ist aber dennoch möglich.

Übersicht

Folgende Schritte sind für die Produktion von modularen DocBook Dokumenten durchzuführen:

  1. Legen Sie im root-Projektverzeichnis ein Masterdokument an

  2. Legen Sie weitere Module in Unterordnern an, dazugehörig die image-ordner für die Grafiken. Registrieren Sie die Module im Masterdokument

  3. Verlinken Sie, wenn gewünscht die Module untereinander mit olink Kommandos. Innerhalb der Module können Sie xrefs oder link Kommandos für Verweise verwenden. Verweisziele müssen Ihnen bekannt sein.

  4. Wenn Sie zur Verlinkung der Module untereinander den Befehl olink verwendet haben müssen Sie einmalig für jede Publikation eine target database in den root Ordner Ihres Projektes anlegen. (olinkdb_fo.xml oder olinkdb_html.xml)

  5. Erzeugen Sie für jede Publikation ein datafile , verwenden Sie dazu den Befehl make_datafile_pdf oder make_datafile_html

  6. Lösen Sie die XIncludes auf, indem Sie eine temporäre XML Datei erzeugen, in der die Inhalte der verlinkten Dateien eingebettet sind. Benutzen Sie dazu den Befehl: resolve_modules.

  7. Publizieren Sie die temporäre XML Datei modules_resolved.xml mit den Kommandos make_html_module oder make_pdf_module.

  8. Wenn Sie die Inhalte der einzelnen Module ändern, sollten Sie vor einer neuen Publikation auf jeden Fall folgende Komponenten aktualisieren:

    • datafiles für die jeweilge Publikation (mit make_datafile_pdf oder make_datafile_html)

    • temporäre XML Datei: resolved_modules.xml im Root Verzeichnis (mit resolve_modules)

  9. Wenn Sie Module hinzufügen müssen Sie folgende Komponenten aktualisieren:

    1. Masterdokument erweitern

    2. datafile aktualisieren

    3. XIncludes auflösen (resolved_modules.xml erzeugen)

Konzept von XInclude

Bevor XIncludes zur Verfügung standen mussten externe Dokumente mit Entitäten oder Xlinks eingefügt werden. Mit XIncludes steht nun eine eigene Sprache für das Einfügen und Zusammenfügen von modularen Dokumentationen zur Verfügung.

Kurz vor Weihnachten 2004 hat das W3-Konsortium den Standard XML Inclusion verabschiedet, der abgekürzt XInclude genannt wird. Ziel dieser auf XML basierenden Sprache ist es, ein Verfahren festzulegen, wie bestehende Dateien in ein XML-Dokument eingefügt oder mehrere Dateien zu einem einzigen Dokument zusammengeführt werden können. XInclude ist eine einfache Sprache, die im Prinzip nur aus zwei Elementen besteht. xi:include und xi:fallback

Unterstützung von XInclude in aktuellen Programmiersprachen und XML-Parsern Als erster eigenständiger XML-Parser unterstützt libxml den XInclude-Standard. In AXitd Umgebung durch das libxml Werkzeug xmllint™ und xsltproc™ im Verzeichnis du1\xmllint2 Der Xerces-Parser in der Java-Fassung unterstützt ebenfalls XInclude und ist Bestandteil der JAXP-API (Java API für XML Processing). Sie finden Ihn im Verzeichnis du1\saxon.

Die Module werden so aufgebaut, dass jedes Modul für sich ein gültiges XML Dokument ist und nach der DocBook DTD validiert werden kann. Das Masterdokument ist außerdem ein gültiges DocBook Dokument, nachdem die XIncludes aufgelöst werden.

Was bedeutet dies für die vorliegende AXitd Umgebung?

Zuerst wird ein Masterdokument gebildet, in dem die Unterdokumente mittels XIncludes referenziert werden.

Diese Gesamtdokument muss manuell erstellt werden, ein Beispieldokument dafür ist im Verzeichnis c:\du1\Projects\beispiel_modul\master.xml enthalten.

Es ist außerdem möglich, die verknüpften Module mittels Xincludes weiter zu verschachteln, d.h. in Unterdokumente weitere Referenzierungen zu kleineren Einheiten einzubauen.

Der Verweis zu den Dokumenten kann über einen absoluten Pfadnamen oder eine relative Angabe erfolgen. Liegen die Module in Unterordnern, werden die Pfade beim Auflösen der XIncludes durch xml:base Elemente ersetzt, die bei der Publikation wiederum durch die Inhalte der referenzierten Dateien ersetzt werden.

[Anmerkung]Anmerkung

XIncludes sind kein Bestandteil der DocBook DTD. Wenn Sie eine Masterdokument mit Referenzen erstellt haben, werden Sie eine Fehlermeldung bekommen, dass das Dokument nicht valide ist. Um diese zu vermeiden kann die DocBook DTD entsprechend modifiziert werden, die Xincludes beim Parsen entsprechend berücksichtigt werden, oder vor dem Publizieren eine gültige DocBook Datei erzeugt werden, in der die XIncludes aufgelöst sind. In der AXitd DocBook Umgebung wird die letztere Vorgehensweise verwendet, indem eine temporäre Datei in den jeweiligen Projektordner abgelegt wird, die dann wie Einzeldokumente weiterverarbeitet werden kann.

Darüberhinaus können Sie außer auf Module auch auf andere, nicht DocBook basierteTexte verweisen, etwa auf einen Programmcode oder ähnliches um z.B. auch auf dynamische Inhalte zugreifen zu können. In diesem Fall müssen Sie die XIncludes entsprechend attributieren.

Siehe dazu auch XInclude Spezifikation

Dokumentation planen und beginnen

Vor Beginn der Dokumentation müssen Sie festlegen, wie die Struktur der Dokumentation aufgebaut werden soll, und welche Unterkapitel und weitere kleinere Einheiten gebildet werden sollen.

Beispielhaft wird hier die Vorgehensweise mit einem Masterdokument und mehreren Unterkapiteln einer Ebene in verschiedenen Unterordnern beschrieben. Eine weitere Verschachtelung wird nicht vorgenommen.

Masterdokument anlegen

Erstellen Sie zuerst ein Masterdokument der Ebene article, book oder set in einem übergeordneten Projektordner (Unterordner du1\projects). Das Masterdokument ist eine Schablone die vorgibt, in welcher Reihenfolge welche Module publiziert werden sollen, kann aber gleichzeitig auch beliebige DocBook Dokumente enthalten.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"../../struktur/DocBook/docbookx.dtd" 1
[
<!ENTITY intro "part1/intro.xml">
<!ENTITY basics "part1/getting_started.xml">2

]>
<book>

<title>User Guide</title>
<subtitle>This should show how it should work with modules</subtitle>3

<xi:include href="&intro;" xmlns:xi="http://www.w3.org/2001/XInclude"/>4
<xi:include href="&basics;" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="end/end.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:fallback>
					5
			<para>
				<emphasis>FIXME: MISSING XINCLUDE CONTENT</emphasis>
			</para>
		</xi:fallback>
	</xi:include>

</book>

Das Masterdokument ist folgendermaßen aufgebaut:

1

DTD und Kopf des Moduls (validiert gegen book Element). Masterdokument ist ein normales Docbook Dokument (set, book), allerdings ist XInclude kein DocBook Element, so dass es beim Validieren gegen die DocBook DTD zur Fehlermeldung kommt. Falls dies stört, kann die DTD entsprechend modifiziert werden und in die driver files eingebunden werden. In XXE kann es geöffnet und bearbeitet werden ohne dass es zur Fehlermeldung kommt.

2

Entitäten mit Verweis auf die verknüpften Module. Nicht unbedingt notwendig, Pfade können auch direkt in die hrefs geschrieben werden. Dient aber der besseren Lesbarkeit und Editierbarkeit. Die Module sind in Unterordnern abgelegt. Ermöglicht bessere Verwaltung der Module.

3

Inhalt des Masterdokumentes. Das Masterdokument wird beim späteren Publizieren als ganz normales DocBook Dokument verarbeitet, daher sind alle DocBook Elemente erlaubt.

4

Verweis auf die Module mit XInclude. Welche Hierarchiebene die Module haben wird in den Modulen selbst angegeben. Hier handelt es sich um chapter Elemente. Die Module können ebenfalls selbst Verweise auf andere Dokumente enthalten.

5

Fallback, falls ein Modul (noch) nicht existiert. In der Ausgabe wird der Text: FIXME: MISSING XINCLUDE CONTENT als Erinnerung ausgegeben, beim Auflösen der XIncludes, kommt es zur Fehlermeldung, allerdings wird Prozess nicht abgebrochen.

[Anmerkung]Anmerkung

Kommt (zumindest bei mir) aber zu Fehlermeldungen bei der PDF Publikation, weil ein nicht zusammenhängender XSL:FO block gebildet wird, der von FOP nicht verarbeitet werden kann. Daher bei PDF Publikation mit Vorsicht zu genießen.

Module anlegen

[Anmerkung]Anmerkung

Beispieldokumente für Module sind im Ordner du1\Projekte\beispiel_modul\part1

Die Module sind gültige DocBook Dokumente, und können daher einzeln validiert oder prozessiert werden. Die Deklaration bestimmt, in welcher Ebene sie ins Master Dokument eingefügt werden. Im Beispiel handelt es sich um Module in der chapter Ebene, das nach den DocBook Regeln erstellt wird. Für die bessere Verwaltung ist es sinnvoll die Module in Unterordnern abzulegen. Es ist unbedingt notwendig, das Attribut id des übergeordneten Knotens (hier chapter) zu vergeben.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"../../../struktur/DocBook/docbookx.dtd">
<chapter id="intro">
	<title>Introduction to the documentation</title>

	<para>This guide shows you how to use the software.</para>
	<para>If you don&#39;t want to believe, try it</para>
</chapter>

Es ist sinnvoll den Grafikordner (verwenden Sie die Bezeichnung images) in den selben Unterordner zu platzieren, um Austauschbarkeit und Versionierbarkeit zu gewährleisten.

Module erstellen

Beim Schreiben und anlegen von modularen Dokumenten sind insbesondere 2 Punkte zu berücksichtigen, die in den folgenden Unterabschnitten näher erläutert werden:

  1. Legen Sie die Grafiken in die Unterordner des jeweiligen Dokumentes ab

    [Anmerkung]Anmerkung

    Siehe dazu Beispielprojekt: du1\Projekte\beispiel_modul\part1\images

  2. Verwenden Sie olinks anstelle von xrefs oder link, wenn Sie auf andere Module verweisen

Grafiken und Pfadangaben

In der Beispieldatei: getting_started.xml, die sich im Unterordner part1 des Projektes beispiel_modul befindet, sind 2 Grafiken eingebunden. Die erste Grafik hat einen relativen Verweis auf das Grafikverzeichnis des Hauptordners beispiel_modul/images, die zweite Grafik ist auf den Grafikordner im Unterverzeichnis beispiel_modul/part1/images verlinkt. Beide Grafiken werden korrekt angezeigt und sind auch in der Ausgabe anzeigbar. Da bei beiden Grafiken nur ein relativer Verweis in der Form ../images/grafik.gif den Speicherort der Grafik verrät ist es wichtig zu verstehen, wie die Grafikverweise von XInclude aufgelöst werden.

  • Im Verarbeitungsprozess werden alle Module in ein Gesamtdokument überführt und die Verweise aufgelöst.

  • Bei der Verarbeitung weist ein xml:base Attribut auf die Herkunft der Datei oder des Verweises hin, wenn Sie nicht aus dem root Ordner stammt

  • Durch das Publizieren mit den XSL Stylesheets werden die korrekten fileref Attribute dadurch erzeugt, indem die Stylesheets den Bezug mittels der xml:base des Moduls auflösen.

  • In der AXitd Publikationsumgebung werden beim Aufruf der resolve_modules.bat die Grafikunterordner für die Publikation ins output Verzeichnis kopiert, um die Grafiken auch für die Ausgabe in der richtigen Struktur zur Verfügung zu haben.

    [Tipp]Tipp

    Verschieben oder sichern Sie die Unterordnerstruktur des output Ordners nach Publikation. Die Unterordner werden nicht automatisch gelöscht.

Obwohl Sie die Grafiken in einem beliebigen Unterverzeichnis ablegen können, ist es sinnvoll den Grafikordner (verwenden Sie die Bezeichnung images) in den Unterordner des jeweiligen Dokumentes zu platzieren, um Austauschbarkeit und Versionierbarkeit zu gewährleisten.

Verlinkung von Modulen

Module werden untereinander durch das Kommando olink verknüpft. Innerhalb eines Dokumentes können xrefs und link verwendet werden. Damit der XSLT Prozessor erkennt, in welchem Zusammenhang die Dokumente stehen, muss einmalig eine Datenbank mit diesen Informationen gebildet werden.

Vorbereitung

Bevor Sie Module miteinander verlinken sollten Sie sich im klaren darüber sein, welche Module Sie in welcher Ebene miteinander verlinken wollen und in welcher Hierarchiesstruktur Ihre Dokumentation angelegt und/oder publiziert werden soll.

Außerdem müssen Sie festlegen, welche Ausgabeform die bevorzugte sein soll. (Für verschiedene Ausgabeformen benötigen Sie verschiedene Target Database )

Diese Überlegungen sollten in einer sog. Target Database münden, die ihre Informationen wiederum aus den datafiles der einzelnen Module holt.

Data file erzeugen

[Anmerkung]Anmerkung

Beispiel data files befinden sich im Ordner du1\Projekte\beispiel_modul\master_html.db bzw. du1\Projekte\beispiel_modul\master_fo.db

Die Referenzen aller Module werden in einer Datei abgelegt, dem sogenannten data file. Dies ist eine Informationsübersicht über alle möglichen Ziele auf die ein Querverweis gesetzt werden kann. Es wird mit folgendem Aufruf vor Publikation erzeugt . Das data file wird später in die Target Database eingebunden.

C:\du1\xmllint2>
xsltproc --stringparam collect.xref.targets "only" 
         --stringparam targets.filename "intro.db"
         ..\xsl\html\docbook.xsl 
         ..\Projects\beispiel_modul\master.xml


Writing intro.db for chapter(introduction_sw5)

In der AXitd Umgebung Aufruf durch das Kommando make_datafile_pdf oder make_datafile_html (Syntax: make_datafile_xxx [Projektordner] [XML-Datei ohne Dateiendung] abkürzen. Dadurch wird für das XML-Modul, dass Sie aufrufen, ein data file mit dem Namen der zugehörigen XML Datei und der Endung *_html.db oder *_fo.db. erzeugt.

Beispielaufruf für das Modul master.xml im Verzeichnis beispiel_modul:

C:\du1\publish>make_datafile_html beispiel_modul  master

Durch diesen Aufruf wird für das Modul master.xml das data file master_html.db ins Unterverzeichnis du1\projects\beispiel_modul erzeugt.

[Anmerkung]Anmerkung

Die Datei wird immer durch den Aufruf des Masterdokumentes (im Beispiel master.xml) aufgerufen

Das data file fasst alle die Linkinformationen aller Module zusammen, indem es die im Masterdokument vorhandenen XIncludes auflöst.

[Achtung]Achtung

Wenn Sie als Ausgabeform mehrere HTML-Dateien oder multiple PDF Dateien planen müssen Sie für jedes Modul ein data file erzeugen und Ihre olink Datenbank entsprechend anpassen.

Target Database

[Anmerkung]Anmerkung

Beispiel für die target database im Verzeichnis du1\projects\beispiel_modul\olinkdb_fo.xml bzw. du1\projects\beispiel_modul\olinkdb_html.xml

Bevor Sie mit dem Erstellen der Inhalte beginnen müssen Sie einmalig manuell eine target database erstellen und im Projektverzeichnis ablegen.

Im Falle der Ausgabe einer HTML-Datei bzw. der Zusammenfassung der Module zu einer PDF Datei enthält die target database einfach nur den Verweis zum erzeugten data file und muss auch bei Erweiterung um Module nicht angepasst werden.

Bei einer Ausgabe in mehrere HTML Dateien oder mehrerer PDF Dateien enthält die relative Struktur, wie Sie im HTML Output publiziert werden soll und legt diese in einem sitemap Element ab. Die Verzeichnisstruktur spiegelt nur die Struktur des Outputs wider, wie Ihre Quelldokumente strukturiert d.h. in welchen Unterordnern sie abgelegt sind ist davon unabhängig. Bei Erweiterung von Modulen müssen Sie die Datenbank bei diesen Ausgabeformen anpassen.

Beispiel 7.1. Beispiel: target database für Output einer (non chunked) HTML Datei

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE targetset SYSTEM "../../xsl/common/targetdatabase.dtd" 1
[
<!ENTITY main_targets SYSTEM "master_html.db">2
]>

<targetset>
 <targetsetinfo> example target database </targetsetinfo>
3
     
	    <sitemap>
		    <dir name="root">
			     <document targetdoc="doku_sw5">
				     &main_targets;
				    </document>
		     </dir>
	     </sitemap>
</targetset>

1

DTD targetset, immer im angegebenen Verzeichnis

2

Verweis auf das globale data files, das wie oben beschrieben vor Publikation gebildet werden muss.

3

sitemap Element, in das die Verknüpfungen der einzelnen Module und die Hierarchie zueinander abgebildet werden

Die Referenzbasis (output.htm) wird bei der Publikation an den Prozessor übergeben. Beispiel aus make_html_module.bat:

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar  com.icl.saxon.StyleSheet 
-o %output%\output.htm %projects%\%1\%2.xml %publish%\driver\driver_html.xsl 
target.database.document="..\..\Projects\beispiel_modul\olinkdb_html.xml" 
olink.base.uri="output.htm" current.docid="%3"

Sie kann bei einer fixen Bezeichnung auch alternativ dazu im driver File definiert sein.

[Anmerkung]Anmerkung

Wenn Sie den Ausgabenamen (z.B. output.html) vor Publikation verändert haben müssen Sie auch die Datei make_html_module.bat entsprechend anpassen.

Werden die Module in mehrere HTML Module ausgegeben (chunk mode), muss das sitemap Element entsprechend der Unterordnerstruktur angepasst werden.

Linkziele

Wenn Sie die Dokumente standardmäßig in eine HTML oder PDF Datei zusammenfassen (Standard in AXitd Umgebung), werden die Linkziele als olink ausgezeichnet und folgendermaßen referenziert:

olink hat zwei Mussattribute, targetdoc und targetptr. targetdoc bezeichnet das aufgerufene Dokument (Modul) tartgetptr das Verweisziel (pointer). Verweisen Sie mit targetdoc immer auf die ID des Hauptdokumentes (im Beispiel 'doku_sw5') und mit targetptr auf die ID des anzuspringenden Elementes, Abschnittes etc. Wenn mehrere Autoren verschiedene Module erstellen, muss Ihnen also nur die ID des Verweiszieles, nicht aber die ID des Dokumentes bekannt sein. Es empfiehlt sich eine standardisierte Vergabe der Identifikatoren.

Wenn Sie Dokumente in mehrere HTML Dokumente ausgeben wollen oder auf verteilte PDF Dateien, müssen Sie mit targetdoc die ID des Zielmodules und mit targetptr die ID des anzuspringenden Elementes, Abschnittes etc ansteuern. Die Auflösung der Links geschieht dann über die separaten data files und deren Positionierung in der target database, die Sie entsprechend anpassen müssen. Wenn Sie über ein Content Management System arbeiten ist diese Vorgehensweise standardmäßig zu verwenden.

Erfassen von Dokumenten in XXE

XML Mind XML Editor unterstützt das Arbeiten mit modularen Dokumenten, Sie können sowohl das Masterdokument als auch die referenzierten Dokumente bearbeiten und zwischen ihnen wechseln.

Masterdokument öffnen

Zum Bearbeiten Ihrer modularen Dokumentation öffnen Sie zuerst das Masterdokument.

XXE meldet Ihnen, dass das zu öffnende Dokument Verweise mit XInclude enthält und gibt Ihnen Hinweise, wie die Dokumente zu bearbeiten sind. Das Prinzip ist ganz einfach: XXE kennzeichnet die referenzierten Dokumente mit einem grauen Hintergrund und sperrt sie zunächst für die Bearbeitung. Alle Dokumentteile des Masterdokumentes werden mit einem gewöhnlichen weißen Hintergrund gekennzeichnet und sind wie in einem ganz normalen DocBook Dokument zu bearbeiten.

[Anmerkung]Anmerkung

Beachten Sie, dass das Masterdokument durch die Verwendung der XIncludes kein gültiges DocBook Dokument mehr ist und als ungültig validiert wird. Um sicher zu gehen, dass es in den folgenden Schritten korrekt weiterverarbeitet wird können Sie es mit einem XInclude fähigen Parser (z.B. Xerces) validieren

Referenziertes Dokument öffnen und bearbeiten

Um ein referenziertes Modul zu bearbeiten müssen Sie zuerst den Cursor an die zu bearbeitende Stelle im Dokument positionieren. Wählen Sie dann aus dem Menü: Bearbeiten -> Dokumententenverweis -> Bearbeite referenziertes Dokument.

XXE öffnet das referenzierte Dokument zum Bearbeiten im normalen Editiermodus. Nehmen Sie Ihre Eingaben vor und wechseln Sie danach zurück ins Masterdokument indem Sie Bearbeiten -> Dokumententenverweis -> Bearbeite Ausgangsdokument aus dem Menü wählen.

[Achtung]Achtung

Die im Modul gemachten Änderungen sind leider nicht im Masterdokument sichtbar. Um diese anzeigen zu lassen müssen Sie das Masterdokument schließen und erneut öffnen.

Publikation Gesamtdokumentation

[Anmerkung]Anmerkung

Beispiel temporärer Gesamtdatei im Ordner du1\projects\beispiel_document\modules_resolved.xml

Vor Publikation müssen Sie zuerst ein temporäres Gesamtdokument erstellen. Damit werden die referenzierten Dokumente in das Masterdokument überführt. Man spricht vom 'Auflösen der XIncludes'. In AXitd DU1 wird mittels xmllint™ ein temporäres XML-Dokument erzeugt, das danach zur weiteren Publikation verarbeitet werden kann.

Die Publikation erfolgt in AXitd Du1 immer in zwei Schritten, die Sie nacheinander ausführen müssen:

  1. Erzeugen Sie das temporäre XML Dokument mit dem Befehl resolve_modules.bat in Ihr aktuelles Projektverzeichnis

  2. Verarbeiten Sie das temporäre XML Dokument aus Ihrem Projektordner und publizieren Sie es ins output Verzeichnis ( Wenn Sie eine HTML Publikation erzeugen wollen z.B.mit dem Befehl make_html_module.bat)

XIncludes auflösen

Für die Weiterverarbeitung müssen Sie vor jeder Publikation zuerst eine temporäre XML Datei erzeugen, in der der Inhalt der referenzierten Module implementiert ist, der von den Stylesheets weiterverarbeitet werden kann.

Öffnen Sie eine Windows Konsole und geben Sie folgenden AXitd Befehl ein:

resolve_modules [Projektordner des Masterdokumentes] [Dateiname des Masterdokumentes ohne Dateiendung].

Für das Beispieldokument master.xml im Projektordner beispiel_modul geben Sie folgendes Kommando ein:

resolve_modules beispiel_modul master

Es wird die temporäre Datei modules_resolved.xml in den von Ihnen gewählten Projektordner erzeugt. Diese kann nun publiziert werden.

Wenn Sie die die Datei modules_resolved.xml editieren, können Sie erkennen, dass die XIncludes durch den Inhalt der referenzierten Datei und dem xml:base Attribut im Hauptknoten ersetzt wurden.

<chapter id="getting_started" xml:base="part1/getting_started.xml">

Gesamtdatei nach HTML publizieren

Die Datei modules_resolved.xml in Ihrem Projektverzeichnis können Sie nun mit dem AXitd Publikationsbefehl make_html_module zur Erzeugung einer HTML-Datei weiterverarbeiten.

make_html_module [Projektordner, in der die temporäre Gesamtdatei erzeugt wurde] [temporäre Datei, immer modules resolved.xml] [id des root-Dokumentes]

make_html_module beispiel_modul modules_resolved.xml doku_sw5

um die Verarbeitung besser zu verstehen, folgend der Aufruf in der batch- Datei:

java.exe -cp %saxon%saxon.jar;%home%\xsl\extensions\saxon652.jar 
 com.icl.saxon.StyleSheet -o %output%\output.htm 
%projects%\%1\%2.xml %publish%\driver\driver_html.xsl 
target.database.document="olinkdb.xml" olink.base.uri="output.htm" 
current.docid="%3" 

Mit dem dritten Parameter,im Beispiel doku_sw5, wird die ID des root Dokumentes der Dokumentation an den XSL Processor übergeben. Diese ist notwendig, um die Ausgangsbasis für die Verlinkung der Module untereinander zu kennzeichnen, da diese aus den XSL Stylesheets nicht erkennbar ist. Der Prozessor kann aufgrund dieser Angabe in der angegebene Datenbank olinkdb.xml abrufen, mit welchem Dokument er mit der Auflösung der olinks beginnen muss, und in welcher Beziehung die Dokumente zueinander stehen.

[Anmerkung]Anmerkung

Für die HTML Publikation muss die Bezeichnung der olink-Datenbank olinkdb.xml beibehalten werden, ansonsten müssen Sie die make_html_module.bat entsprechend abändern.

Die Ausgabe output.html wird wie gewohnt in das output Verzeichnis \du1\output publiziert und kann beliebig umbenannt werden.

Gesamtdatei nach PDF publizieren

In der AXitd Umgebung wird bei der PDF Publikation davon ausgegangen, dass Sie aus Ihren erstellten Modulen ein Gesamtdokument in einer PDF Datei zusammenfassen wollen. Wollen Sie für jedes Modul eine eigene PDF Datei erzeugen und die erzeugten PDF-Dateien miteinander verlinken, ist die Umgebung entsprechend anzupassen.

Zur Publikation nach PDF müssen Sie den Befehl make_pdf_module benutzen, nachdem Sie folgende Voraussetzungen geschaffen haben.

  1. Für die Publikation nach PDF benötigen Sie eine eigene olink-Datenbank olinkdb_fo.xml, die zur Auflösung der olinks nach PDF einmalig manuell erzeugt werden muss.

  2. Für alle Module wird ein einziges Datenfile (im Beispielordner master_fo.db) in den root-Projektordner erstellt, benutzen Sie dazu den Befehl make_datafile_pdf

Datenfile für PDF erzeugen

Erzeugen Sie ein Datenfile für die PDF Ausgabe, indem Sie den Befehl: make_datafile_pdf [Projektordner] [XML root Datei] eingeben. Im Beispiel:

make_datafile_pdf beispiel_modul master

Es wird nun für alle Module, einschließlich des Master Modules ein Datenfile erstellt, indem die im master.xml enthaltenen XIncludes aufgelöst und die olinks und deren Anker eingebettet werden.

Für das Verlinken der Module untereinander reicht es nun aus, als Zieldokument immer die ID des Masterdokumentes (doku_sw5) anzugeben, die IDs der anderen Module müssen nicht bekannt sein.

Das Datenfile dateiname_fo.db wird in das Projektverzeichnis erzeugt und muss bei jeder Veränderung eines der Module neu erzeugt werden. Dabei kommt der XSL Prozessor xsltproc zum Einsatz, der gleichzeitig die XIncludes auflöst.

Erzeugen Sie danach einmalig eine Datenbank olinkdb_fo.xml wie nachfolgend beschrieben:

Datenbank für FO erzeugen

In der Datenbank reicht es aus, auf das im vorigen Schritt erzeugte Datenfile zu verweisen. Sie muss daher nur einmalig manuell erzeugt werden und muss auch beim Zufügen neuer Module nicht aktualisiert werden.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE targetset SYSTEM "../../xsl/common/targetdatabase.dtd" [
<!ENTITY intro_targets SYSTEM "part1/intro_fo.db">
<!ENTITY gs_targets SYSTEM "part1/getting_started_fo.db">
<!ENTITY main_targets SYSTEM "master_fo.db">
]>
<targetset>
	<sitemap>
		<dir name="root">
			<document targetdoc="doku_sw5">
				&main_targets;
				
			</document>
		</dir>
	</sitemap>
</targetset>

PDF Datei erzeugen

Erzeugen Sie die PDF Ausgabe mit dem Befehl make_pdf_modul [Projektordner] [resolved_modules.xml] [id des root-dokumentes für Dokumentation].

make_pdf_modul resolved_modules.xml doku_sw5

Die Datei resolved_modules.xml muss vorher wie oben beschrieben erzeugt werden.

Die PDF Datei ausgabe_neu.pdf wird in das Ausgabeverzeichnis \du1\output publiziert.

Publikation andere Formate

Wird hier nur kurz beschrieben, entsprechende Befehle werden in späterer Version zur Verfügung gestellt.

Publikation CHM oder javahelp

Basiert auf der HTML Chunk Ausgabe, dafür ist eigene Target Database erforderlich, wird später beschrieben.

Publikation RTF oder WML

Bereiten Sie die Datei resolved_modules.xml analog der Vorgehensweise für modulare PDF Dokumente vor. „Gesamtdatei nach PDF publizieren“

Öffnen Sie das XSL Utility , wie unter RTF Publikation beschrieben. „Publikation in RTF o. WML“

Editieren Sie die Parameter für den Aufruf des driver_fo Stylesheets, und geben Sie die folgenden beiden Parameter ein:

  • current.docid: ID des Ausgangsdokument (im Beispiel doku_sw5)

  • target.database.docfile: Speicherpfad der olinkdb_fo.xml für die Publikation

Der filename muss analog der Abbildung im Format file:///C:/... eingegeben werden.

Starten Sie die Konvertierung nachdem Sie das Ausgabeverzeichnis festgelegt haben.

Die Verlinkung müsste in die erzeugte Ausgabedatei übernommen worden sein.

Publikation Profiling

Um bedingte Dokumente zu erstellen müssen Sie für jedes Dokument ein separates Datenfile erstellen. Erzeugen Sie für verschiedene Profile verschiedene data files, indem Sie die batchdatei make_html_module bzw. make_pdf_module editieren und den Ausgabenamen anpassen. Rufen sie die modifizierte Batchdatei dann mit Ihren Profiling Parametern auf.

Publizieren Sie in die verschiedenen Ausgaben mit Verweis auf die für die Profile erzeugten Datafiles. Erzeugen Sie dafür am besten für jedes Profil eine target database.

Verwendung sitemap Element

Da die von Ihnen erzeugte Datenfiles bzw. die von Ihnen erzeugte target database gültige XML Dokumente sind und gleichzeitig die Struktur Ihrer Gesamtdokumentation wiedergeben können Sie die darin enthaltenen Informationen für Informationszwecke benutzen, indem Sie sie mit XSLT Transformationen umwandeln.

z.B. sitemap als Navigation in der HTML Ausgabe oder Navigationsleiste am Modulstart. Ausführung wird später beschrieben.

Kapitel 8. Übersetzungsmanagement

Erstübersetzung

Als Erstübersetzung wird hier die erste Übersetzung einer DocBook XML Datei bezeichnet, die noch keine Revisionsstände hat. Beispielhaft wird eine Übersetzung im Translation Memory System Trados ™durchgespielt.

Vorbereitung TM System

Zum Bearbeiten von XML-Dateien verwendet Trados das Programm Tag Editor. Dieses Programm benötigt für die Bearbeitung eine ini-Datei, die über einen sog. DTD Wizard erzeugt werden kann.

In DU1 ist eine Trados .ini Datei im Verzeichnis struktur\DocBook\DocBookUmgebung.ini abgelegt. Verwenden Sie diese Datei beim Bearbeiten und Analysieren von DocBook Dokumenten.

Übersetzungspaket vorbereiten

Erstellen Sie einen Ordner translations, der folgende Inhalte enthält:

  1. images: Verwendete Grafiken (Zur Voransicht für die Übersetzer)

  2. Struktur: DTD (Für Analyse und Bearbeitungsmodus)

  3. Quelldatei

  4. xsl: die DocBook Stylesheets (Zur Voransicht für die Übersetzer)

Editieren Sie die Quelldatei und ändern Sie den Header:

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="xsl\html\docbook.xsl"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"struktur/DocBook/docbookx.dtd"> 

Dies ist notwendig, um das Stylesheet für die Voransicht im Tag Editor anzuziehen und die DTD entsprechend auf den Übersetzungsordner zu verweisen.

Packen Sie den Ordner und senden Sie ihn mit Anleitung an die Übersetzer

Übersetzung von DocBook XML-Dateien

  1. Entpacken Sie das zip -file xxx.zip in einen Ordner, es bildet sich folgende Ordnerstruktur:

  2. Öffnen Sie die Datei xxx.xml im Tag Editor. Sie werden aufgefordert eine ini-Datei auszuwählen. Wählen Sie die Datei DocBookUmgebung.ini aus, die sich im Unterordner: struktur/Docbook befindet.

    In der Trados Workbench :

    Menü Optionen > Translation Memory-Optionen...

    Im Trados TagEditor:

    Extras > DTD-Einstellungen ... > Hinzu ... > Eine Datei mit DTD-Einstellungen öffnen aktivieren ...

    Verwenden Sie diese Datei auch zur Analyse der XML-Datei indem Sie diese unter tools -> SGML/XML DTD eingeben. Für die korrekte Analyse ist es unbedingt notwendig, dass Sie genau diese Datei verwenden. Vorgehensweise:

    1. Im Fenster "Translation Memory-Optionen..." das Register "Extras" anklicken.

    2. Im Bereich "Dateien mit DTD-Einstellungen" im Feld "SGML/XML" (NICHT HTML!!!) die mitgelieferte ini-Datei angeben.

  3. Anmerkung zur Übersetzung. Bei den Elementen indexterm, primary und secondary handelt es sich um den Indexeintrag und den Unterindexeintrag, diese Elemente müssen unbedingt übersetzt werden.

    In der Ausgabe sieht das folgendermaßen aus:

    Rote Pfeile

    Primary Element

    Blaue Pfeile

    Secondary Element

    Prüfen Sie nach Übersetzung in der Previewfunktion ob der Index korrekt gebildet wurde (befindet sich am Ende des Dokumentes)

  4. Nach Beendigung der Übersetzung brauchen Sie nur die xxx.xml Datei zurückzuschicken, alles andere können Sie für die nächste DocBook Übersetzung verwenden.

Publikation der Übersetzung

Passen Sie evtl. den Dateinamen so an, dass die Sprachversion erkenntlich ist und die Quelldatei nicht überschrieben wird. Wenn Sie sprachabhängige Grafiken verwenden müssen Sie die übersetzte Datei in einem eigenen Ordner in der Verzeichnisebene von Projects ablegen, wenn nicht können Sie sie in das Verzeichnis der Quelldatei ablegen.

Zuerst müssen die Header der übersetzten Quelldateien wieder entsprechend angepasst werden. Bei häufigen Übersetzungsprozessen empfiehlt es sich ein Transformationsskript für die Übersetzung zu verwenden

Als nächstes muss der entsprechende Language Code im Kopf des DocBook Root Elementes (wenn Sie verschiedensprachige Abschnitte verwenden, müssen Sie an allen Stellen anpassen) eingesetzt werden.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"struktur/DocBook/docbookx.dtd">
<book lang="it">
  <title>Fehlerkompendium</title>

  <subtitle>d-lab.2</subtitle>
 

Die weitere Publikation erfolgt analog zur Quelldatei.

Übersetzung Update

Als Update wird hier die die erste oder eine Folgerevision einer DocBook XML Datei bezeichnet.

Identifikation Änderungen

Identifikation und Separation von Änderungen

Übersetzung der Änderungen

Übersetzung von Änderungen im Gesamtzusammenhang

Publikation von Updates

Reset der Ursprungsdatei

Kapitel 9. Bedingter Text (Profiling)

Profiling dient in der Technischen Dokumentation folgenden Zwecken:

  • Bedingter Text. Für bestimmte Zwecke wird nur bestimmter Text ausgegeben, z.B. gilt ein Text für alle Kunden, bestimmte Passagen aber nur für eine bestimmte Kunden oder Kundengruppen, dazu werden verschiedene Publikationen erzeugt

  • Revisionsmanagement. Publikation verschiedener Revisionsstände

Für das Profiling werden in DocBook verschiedene Attribute verwendet. Im Prinzip können Sie die meisten Attribute für die bedingte Ausgabe verwenden. Hier werden die Attribute condition und role näher betrachtet.

Einzelne Textpassagen mit bedingtem Text

Textpassagen können mit dem phrase Element ausgezeichnet werden. Bsp:

<para>To open a file, select File Open. 
<phrase os="win">The default
configuration lists share drives such as E: as well as the C: hard 
drive.</phrase>
				<phrase os="linux">The default 
configuration lists NFS-mounted filesystems 
as well as local 
filesystems.</phrase> 
Choose the file from the list.</para>

Damit haben Sie die Möglichkeit z.B. für verschiedene Varianten Ihrer Geräte verschiedene Parameter auszugeben.

Mehrere Profiling Bedingungen

Werden mehrere Bedingungen wie z.B. os und role als Profile verwendet, so müssen die einzelnen Bedingungen später bei der Ausgabe einzeln berücksichtigt werden. Haben Sie 2 mögliche Attributwerte müssen Sie diese bei der Publikation beide berücksichtigen indem Sie beide als Profiling-Bedingungen angeben. [z.B. profile.condition="internal;external"]. Verschiedene Bedingungen können Sie durch mehrmaliges Profiling (2stufig) erzeugen, indem Sie die bereits 'profilte' Version nochmal einem Profiling unterziehen.

Profiling Prozess

Es gibt 2 Möglichkeiten das Profiling zu starten:

  1. In einem Durchgang - Der Profiling-Inhalt wird temporär gespeichert und dann in Ihrer gewünschten Publikation ausgegeben.

  2. Zweistufig. Mit einem separaten Stylesheet wird zuerst ein temporäres File erzeugt, dass dann mit den normalen DocBook Stylesheets weiterverarbeitet werden kann. Diese Methode muss verwendet werden, wenn das Dokument xref oder olink Elemente enthält.

Einstufiges Profiling in DU1

Folgende Stylesheets werden verwendet:

HTML Einzelseitenhtml/profile-docbook.xsl
HTML Chunkshtml/profile-chunk.xsl
HTML Helphtmlhelp /profile-htmlhelp.xsl
JavaHelpjavahelp/profile-javahelp.xsl
XSL:FOfo/profile-docbook.xsl

Beim Aufruf der Stylesheets müssen die gewünschten Profiling Parameter angegeben werden. In der AXitd Du1 Docbook Umgebung sieht der Aufruf dazu folgendermaßen aus. (Beispiel für html, andere Ausgabeformen analog)

pdf:
make_pdf_profile 
du1 du2_0 "profile.condition=internal"

html-chunk:
					make_html_chunk_profile 
du1 du2_0 "profile.condition=internal"

html-help:
make_htmlhelp_profile 
du1 du2_0 "profile.condition=internal"

javahelp:
make_javahelp_profile 
du1 du2_0 "profile.condition=internal"

html:make_html_profile 
du1 du2_01  "profile.condition=internal"2
1

Name Ihrer XML Datei ohne Endung .xml

2

Bedingung, nach der gefiltert werden soll

Im Output werden nun alle Elemente, die das Attribut profile.condition="internal" haben, ausgespielt und zusätzlich alle, deren condition Attribut leer ist. Alle Elemente, bei denen das Attribut condition nicht internal heißt und nicht leer sind werden nicht ausgespielt. (condition=external).

[Anmerkung]Anmerkung

Sie können auch alle Textpassagen ausspielen, die kein Attribut haben, d.h. hier die weder als 'internal' noch als 'external' gekennzeichnet sind und damit für alle übrigen Leser gelten, indem Sie die Profile-Bedingung leer lassen ("profile.condition=''")

Besondere Betrachtung verdient das Attribut role. Dieses sollte nur in Ausnahmefällen für das Profiling verwendet werden, da es auch für andere Zwecke, wie z.B. bei inline-Auszeichnungen <emphasis role="bold> verwendet wird und diese dann bei bedingtem Text nicht ausgespielt werden.

Zweistufiges Profiling in DU1

Beim 2stufigen Profiling wird ein temporäres XML-File in das Project-Verzeichnis gespielt, das von dort aus mit den 'normalen' Publikationsmitteln weiterverarbeitet wird.

Wie schon oben beschrieben ist dies immer dann vorzuziehen, wenn xrefs und olinks verwendet wurden, die aus dem temporären File aufgelöst werden können.

  1. Erzeugen Sie das temporäre file profile_temp.xml mit Hilfe des Publikationsscripts profile.bat aus dem publishing-Verzeichnis:

    profile du1 du2_0 "profile.condition=internal"

    Die Ausgabe des Prozesses liegt im Projektordner parallel zu Ihrem XML-File, in diesem Falle im Ordner: Project1/profile_temp.xml und beinhaltet alle Elemente, die das Attribut condition = internal haben.

  2. Verarbeiten Sie das temporäre file: profile_temp.xml mit den normalen Publikationsschritten (z.B. HTML)

    make_html du1 du2_01
    1

    Dies ist der Name des temporären Profile-files, standardmäßig profile_temp.xml ( Eingabe ohne Dateiendung)

    Die Ausgabe findet sich wie gewohnt im output-Verzeichnis wieder.

Standardproduktionen mit Profiling

Wenn Sie wiederkehrende Produktionen mit immer den gleichen Profiling Bedingungen haben, bietet es sich an, diese Bedingungen in einer Konfigurationsdatei festzulegen. DocBook XSL stellt dafür die Parameter

  • profile.arch

  • profile.condition

  • profile.role

  • profile......

zur Verfügung. Schreiben Sie sich einen Customization Layer mit den gewünschten Ausgabemasken und importieren die AXitd Konfigurationsdatei hinein.

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
<!-- The local path to Norm Walsh's DocBook FO stylesheets -->
<xsl:import href="file//driver_fo.xsl"/>
<!-- The local path to your common customization stylesheet -->
<!-- ***************  Profiling  *********************  -->
<xsl:param name="profile.condition" select="'pdf'"/>
<!-- ***************************************************  -->

Dieses Beispiel könnte immer dann angewendet werden, wenn eine Ausgabe mit Inhalten, die nur für die Druckausgabe gewünscht ist, ausgegeben werden soll. Sinnvoll ist diese Vorgehensweise natürlich erst, wenn Sie mehrere Profiling Bedingungen verwenden oder wenn Sie verschiedenen PDF-Ausgaben erzeugen wollen.

Für die PDF Produktion müssen Sie sich nun eine separate batch-Datei schreiben, in der Ihr neues XSL-File angezogen wird. (z.B. make_pdf_kunde1)

Kapitel 10. Tools

In diesem Kapitel werden die Werkzeuge und Stylesheets beschrieben, die im Verzeichnis DU1\publish\driver\tools abgelegt sind.

Mindmap: freemind export

Wenn Sie eine Übersicht über Ihr Dokumentationsprojekt haben wollen oder einen Projektplan bzw. offene Punkte planen und besprechen wollen, bietet es sich an, eine Übersicht in Form eines mindmaps anzufertigen. Damit Sie nicht alle Strukturpunkte von Hand eingeben müssen können Sie ein mindmap Ihrer Docbook Datei über den Befehl make_freemind [Project] [xml-Datei ohne Endung] erzeugen.

make_freemind du1 du2_0

erzeugt die Datei du2_0.mm in das Output Verzeichnis du1/output/. Sie können die Datei mit dem Open Source Mindmanager Freemind, das sie von der sourceforge Seite herunterladen können (getestet in aktueller Version 0.8.0) öffnen.

Die so erzeugten Mindmaps bieten sich z.B an, um den IST Stand Ihres Projektes festzuhalten und zu präsentieren oder weitere Schritte zu planen. Ein Beispielmindmap ist im Ordner C:\du1\Projects\DU1\du2_0.mm abgelegt.

Aus freemind können Sie die mindmaps dann auch exportieren und z.B. in HTML Ihre Struktur ablegen:

Übersicht über verwendete Grafiken

Wenn Sie eine Übersicht über alle vorhandenen Grafiken erzeugen wollen, wechseln Sie ins Verzeichnis DU1\publish und starten in einer DOS-Box die die Batch Datei make_imagelist.bat mit dem Standardaufruf: make_imagelist [Projektverzeichnis] [XML-Datei ohne Dateiendung]

make_imagelist du1 du2_0

Die Ausgabe erfolgt ins Verzeichnis ..\output\images.htm

Die Beschreibung der Grafiken erhalten Sie, indem Sie das role Attribut des Elementes imagedata verwenden.

Remap Tool

Transformation von Attributen

Dient zum Umwandeln von Attributen in Elemente. Zum Umwandeln muss Ihre XML-Datei mit der remap.xsl transformiert werden. Verwenden Sie das remap Attribut um Elemente später umzuformieren.

Vor Transformation:

 <helpproject status="draft" remap="article">
       ...
    <topic revisionflag="changed" remap="section">
        ...
    </topic>
  </helpproject>

Nach Transformation:

  <article status="draft">
       ...
    <section revisionflag="changed">
        ...
    </section>
  </article>

Das Transformationsskript kann als Grundlage verschiedenster Transformationen angepasst werden.

DOCBook XSL Configurator

Author: Steve Whitlatch 2004

Zweck

DocBook XSL Configurator is a Java application used to create DocBook XSL FO customization layers. The application presents users with a tabbed pane containing several tables. Each row in each table contains several cells, one of which is editable and contains the text of the default setting for a specific DocBook XSL FO parameter. Users create projects containing paths to DocBook XML, common-customization XSL, an external XSLT processor, etc. Users then click through the tables, select DocBook XSL FO parameters they want to include in a customization layer, edit those parameters, include the customization layer in a project, write out the customization layer as an XSL file, and apply the XSL to the project's XML using the project's specified XSLT processor.

DocBook XSL Configurator version 0.5.3_1661 is an alpha release. It supports version 1.66.1 of the DocBook XSL FO parameter set. It does not yet support the DocBook XSL HTML parameter set.

Default FO parameter settings, help text, and guidelines for attribute sets ("property sets") are taken from the DocBook XSL package's FO documentation. Attribute set defaults are just guidelines. Attribute sets typically can contain additional parameters not included in the defaults. Some parameters, though legal, may be inappropriate in some cases. Consult the latest version of the XSL W3C Recommendation at: http://www.w3.org/TR/xsl/ for more exact information on an attribute set.

DocBook XSL Configurator also includes a "From the Wild" table that provides users with nifty little snippets of XSL intended to help with formatting not implemented in the DocBook XSL FO parameter set. Currently, the number of these snippets is very small; however, the "From the Wild" snippet collection has the potential to grow very large and be very helpful.

Target Audience

If you are a beginner with DocBook XSL, DocBook XSL Configurator can help you a great deal by bringing all the DocBook XSL FO parameters together, with help, in a GUI. You don't have to switch windows seeking help, and you don't have to manually type out the file containing the XSL FO customization layer.

If you are an expert with DocBook XSL, this application may still be of use to you. You may benefit from the speed with which you can create and edit customization layers; you may find that DocBook XSL Configurator projects help you organize documentation sets; or, you may find the application useful for saving customization layers and associating them with specific DocBook XML instances.

XSL Configurator starten

Wenn Sie Ihre Umgebungsvariablen bereits auf AXitd DU1 gesetzt haben, starten Sie den XSL Configurator mit dem Aufruf: xsl_config aus einer DOS- Konsole.

Wenn nicht, wechseln Sie ins Verzeichnis: publish\driver\tools\DBXSLcfg_0.5.3_1661\ und starten die Applikation mit dem Aufruf: java -jar DocBookXSLConfigurator.jar

Mit dem XSL Configurator arbeiten

Der XSL Configurator unterstützt Sie beim Schreiben von Konfigurationsdateien für XSL:FO.

Besonders hilfreich ist die Kategorisierung der Parameter in der linken Menüübersicht. Diese ist auch für erfahrene Anwender hilfreich, da man sich nicht immer alle Parameter heraussuchen muss.

Wählen Sie die einzelnen Kategorien aus und setzen Sie die gewünschten Parameter indem Sie diese in der Spalte: Include in XSL ankreuzen.

Erzeugen Sie Ihre Konfigurationsdatei, indem Sie den Button drücken oder aus dem Menü Execute -> Write XSL File auswählen.

Sie werden noch aufgefordert den Speicherort anzugeben, danach startet die Generierung des XSL Files.

Binden Sie das erzeugte Konfigurationsfile mit XSL:include in die Datei D:\_xml\du1_2\publish\driver\driver_fo.xsl ein um die AXitd DU1 Funktionen nutzen zu können.

Außerdem können Sie mit dem XSL Configurator auch direkt PDF und Postscriptdateien erzeugen. Dazu müssen Sie das tool entsprechend konfigurieren. lesen Sie dazu die Projektdokumentation.

Kapitel 11. FAQs

Inhaltsverzeichnis

FAQs

FAQs

1. FOP gibt Fehlermeldungen über fehlende Schriften aus.
2. FOP gibt Fehlermeldungen über unsufficient memory aus
3. Was bedeuten die Fehlermeldungen beim Erzeugen der PDF Ausgabe?
4. Warum sind im Verzeichnis FOP 2 Versionen von fop.jar vorhanden?
5. FOP kann Grafikformate nicht verarbeiten, es kommt zu Fehlermeldungen, die z.B ähnlich der folgenden sind:
1.

FOP gibt Fehlermeldungen über fehlende Schriften aus.

Im Verzeichnis ../config/fop/ gibt es eine Datei userconfig.xml, in der Sie die Schriften definieren müssen. Die Schriften müssen Sie vorher im Verzeichnis config/fonts anlegen. Weiterführende Dokumentation zu FOP ist unter ../FOP\build\site\index.html zu finden. Vorgehensweise zum Einbetten von Schriften ist auch von Dave Pawson beschrieben: Adding a Font to FOP.

2.

FOP gibt Fehlermeldungen über unsufficient memory aus

Java Runtime Environment bzw JVM stellen standardmäßig nur 2 MB Speicher für die Transformation zur Verfügung. Um mehr freizugeben, passen Sie die Datei DU1\FOP\fop.bat folgendermaßen an: (ergänzen Sie die fett markierten Parameter)

@ECHO OFF set LIBDIR=lib set
     LOCALCLASSPATH=build/fop.jar set
     LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\xml-apis.jar set
     LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\xercesImpl-2.2.1.jar
     set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\xalan-2.4.1.jar set
     LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\batik.jar set
     LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\avalon-framework...
     set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\bsf.jar set
     LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\jimi-1.0.jar set
     LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\jai_core.jar set
     LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\jai_codec.jar
     java -Xmx256MB -Xms256MB -cp
     %LOCALCLASSPATH% org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
     pause

Details dazu können Sie den Parametern von JRE unter www.sun.com entnehmen

3.

Was bedeuten die Fehlermeldungen beim Erzeugen der PDF Ausgabe?

FOP hat in der eingesetzten Version (und auch in der aktuellen) nicht alle Elemente der XSL:FO Spezifikation berücksichtigt, die in DocBook aber definiert werden. Versuchen Sie es mit einem anderen Formatter z.B. Anntenna House XSLT Formatter, dort sind alle in DocBook verwendeten Parameter berücksichtigt.

4.

Warum sind im Verzeichnis FOP 2 Versionen von fop.jar vorhanden?

In der neuesten Version hat Apache wohl aus Patentgründen die Hypernation-Tabellen einiger Sprachen, unter anderem auch in de (Trennung am Zeilenende) herausgelassen. Daher wird in DU1 die ältere FOP Version verwendet um unschöne Blöcke zu vermeiden. Sollten bei der Produktion Fehler auftauchen, so können die beiden Dateien im Verzeichnis: ../Du1/FOP/build/ einfach in der Namensgebung vertauscht werden wenn dadurch ein besseres Ergebnis erreicht wird. (Z.B. werden die Inhaltsverzeichnisse dann sauberer formatiert)

5.

FOP kann Grafikformate nicht verarbeiten, es kommt zu Fehlermeldungen, die z.B ähnlich der folgenden sind:

[ERROR] Error while creating area :
No ImageReader for this type of image (file:test.png)
[INFO] Reverting to TIFF image handling through JAI:
Error while loading image
file:test.tiff 

Standardmäßig verarbeitet FOP nur GIF und JPEG images. Um andere Grafikformate bearbeiten zu können brauchen Sie die Bibliotheken JIMI oder JAI von SUN. JIMI und JAI sind zwei verschiedene Grafikbibliotheken von Sun. Falls JAI beim Kompilierungsvorgang gefunden wird, wird JIMI überhaupt nicht mehr beachtet. Man kann entweder die Eine oder die Andere verwenden. Sofern man unter Windows und Linux mit einer aktuellen VM von Sun arbeitet, ist JAI vorzuziehen, da diese Bibliothek neuer und schneller als JIMI ist.

JIMI Because of licensing issues, the JIMI image library is not included in the FOP distribution. First, download <http://java.sun.com/products/jimi> and install it. Then, copy the file "JimiProClasses.zip" from the archive to {fop-install-dir}/lib/jimi-1.0.jar. Please note that FOP binary distributions are compiled with JIMI support, so there is no need for you to build FOP to add the support. If jimi-1.0.jar is installed in the right place, it will automatically be used by FOP, otherwise it will not. JAI (Java Advanced Imaging API) JAI support is available for Release 0.20.5 and later. The comments in this section do not apply to releases earlier than 0.20.5. FOP has been compiled with JAI support, but JAI is not included in the FOP distribution. To use it, install JAI <http://java.sun.com/products/java-media/jai>, then copy the jai_core.jar and the jai_codec.jar files to {fop-install-dir}/lib. JAI is much faster than JIMI, but is not available for all platforms. See What platforms are supported? <http://java.sun.com/products/java-media/jai/forDevelopers/jaifaq.html> on the JAI FAQ page for more details. >

Anhang A. Referenz Befehle in DU1

Tabelle A.1. Kommandos

SyntaxFunktionBeispiel
make_imagelist [Projekt] [Datei]Gesamtübersicht über verwendete Grafikenimagelist du1 du2_0
make_chunk_profile [Projekt] [Datei] [Bedingung]Einstufige bedingte Ausgabe mehrerer HTML-Dateienmake_chunk_profile du1 du2_0 "profile.condition=external"
make_freemind [projekt] [Datei]Erzeugt Mindmap für freemind mindmap editormake_freemind du1 du2_0
make_html [Projekt] [Datei]Ausgabe in einer HTML-Dateimake_html du1 du2_0
make_html_module [Projekt] [Datei] [current.id]Ausgabe in einer HTML-Datei, fasst dabei mehrere DocBook Module zusammen, Aufruf zusammen mit der Übergabe der ID des aufgerufenen Dokumentesmake_html_module beispiel_modul master doku_sw5
make_html_chunk [Projekt] [Datei]Ausgabe in mehreren HTML-Dateienmake_html_chunk du1 du2_0
make_datafile_html [Projekt] [Datei]erzeugt data file für HTML Publikation, das Referenzen für Module enthält, Aufruf immer mit dem Masterdokumentmake_datafile_html beispiel_module master
make_datafile_pdf [Projekt] [Datei]erzeugt data file für PDF Publikation, das Referenzen für Module enthält, Aufruf immer mit dem Masterdokumentmake_datafile_pdf beispiel_module master
make_html_profile [Projekt] [Datei] [Bedingung]Einstufige bedingte Ausgabe einer HTML-Dateimake_html_profile du1 du2_0 "profile.condition=external"
make_htmlhelp [Projekt] [Datei]Erzeugt HTML-Hilfe (muss noch im HTML-Workshop konvertiert werden)make_htmlhelp du1 du2_0
make_htmlhelp_config [Projekt] [Datei]Erzeugt nur die Projektdateien der HTML-Hilfe, wenn Sie Änderungen an den Stylesheets vorgenommen habenmake_htmlhelp_config du1 du2_0
make_htmlhelp_profile [Projekt] [Datei] [Bedingung]Einstufige bedingte Ausgabe einer HTML-Hilfe (muss noch im HTML-Workshop konvertiert werden)make_html_profile du1 du2_0 "profile.condition=external"
make_javahelp [Projekt] [Datei]Erzeugt Java-Hilfemake_javahelp du1 du1_2
make_javahelp_profile [Projekt] [Datei]Erzeugt bedingte Java-Hilfemake_javahelp_profile du1 du2_0
make_new [Projekt] [Datei]Erzeugt einen neuen Ordner mit einer neuen XML Datei, die in DU1 publiziert werden kannmake_new Project3 meine_datei
make_pdf [Projekt] [Datei]Erzeugt PDF Dateimake_pdf du1 du2_0
make_pdf_module [Projekt] [Datei] [current.id]Ausgabe in einer PDF, fasst dabei mehrere DocBook Module zusammen, Aufruf zusammen mit der Übergabe der ID des aufgerufenen Dokumentesmake_pdf_module beispiel_modul master doku_sw5
make_pdf_profile [Projekt] [Datei] [Bedingung]Einstufige bedingte Ausgabe einer PDF-Dateimake_pdf_profile du1 du2_0 "profile.condition=external"
profile [Projekt] [Datei], danach z.B. make_html[Projekt] [temp_profile]Erzeugt profile_temp.xml Datei für zweistufiges Profiling in das Projektverzeichnis. Diese Datei kann danach mit Publikationsskript umgewandelt werdenprofile du1 du2_0 danach z.B. make_html_chunk du1 profile_temp
resolve_modules [Projekt] [Datei]Löst die XIncludes der aufgerufenen Datei auf und erzeugt eine temporäre Datei: modules_resolved, in der die referenzierten Inhalte eingefügt sind.resolve_modules beispiel_modul master, danach z.B.make_html_module beispiel_modul modules_resolved
start_du1.batÜbersicht über Befehle Du1. Startet neues FensterStart durch Doppelklick aus dem Verzeichnis publish
test_html.batFür Testzwecke: Nach Installation HTML-Ausgabe erzeugenStart durch Doppelklick aus dem Verzeichnis publish
test_pdf.batFür Testzwecke: Nach Installation PDF-Ausgabe erzeugenStart durch Doppelklick aus dem Verzeichnis publish
make_titelseiten.batErzeugt die das Vorgabestylesheet für die TitelseitenStart durch Doppelklick aus dem Verzeichnis publish
xsl_configruft den DOCBook XSL Configurator aufxsl_config

Anhang B. DocBook mit XXE

XXE ist einer der vielen XML-Editoren, die das Editieren von DocBook Dokumenten mit einer Vielzahl von vordefinierten Funktionen und Ansichten unterstützen. Zum professionellen Arbeiten würde ich ihn wegen einiger Unzulänglichkeiten nur bedingt empfehlen. Für den Einstieg ist er allerdings gut geeignet und hat einen großen Vorteil: In der Standardversion ist dieser Editor kostenlos erhältlich. Um den Einstieg zu erleichtern habe ich die wichtigsten Funktionen kurz beschrieben.

Nachfolgend werden die wichtigsten Schritte für ein Erstellen von DocBook Dokumenten mit XML Mind XML Editor beschrieben. Nach jedem Abschnitt sind die wichtigsten Attribute für die jeweiligen Elemente in einer Tabelle zusammengefasst.

Allgemein

Sie können den Editor in der Standardversion von der XMLMind Webseite herunterladen. Installieren Sie ihn wie dort beschrieben.

Starten Sie indem Sie ein leeres Dokument mit dem AXitd Befehl: make_new erzeugen. Öffnen Sie das Dokument über das Menü: Datei - Öffnen.

Arbeitsbereiche

XXE ist in drei Haupt-Arbeitsbereiche eingeteilt:

Tabelle B.1. Arbeitsbereiche XXE

BereichErklärung
Strukturfenster: Hier wird die hierarchische Struktur der Elemente abgebildet. Wenn Sie mit dem Cursor in einem Element sind wird das Element auf der linken Seite aufgeklappt. Sie können Text und Elemente auch in diesem Arbeitsbereich eingeben. Dieser Arbeitsbereich ist insbesondere wichtig, um Elemente und deren Elternelemente anzuwählen, die Sie im mittleren Arbeitsbereich mit dem Cursor erreichen können. Sie können Elemente durch anklicken des Minuszeichens zusammenklappen um die Navigation zu erleichtern.
Dokumentfenster: Hier erstellen Sie die Inhalte des Dokumentes. Die Darstellung wird über ein css-Stylesheet unterstützt- Sie können neue Elemente über das Kontextmenü mit der rechten Maustaste, mit den Symbolen in der Menüleiste oder über den rechten Arbeitsbereich einfügen. Sie können Kapitel oder Unterkapitel mit der der linken Maustaste durch Klicken auf das Dreieckssymbol zusammenklappen um die Übersichtlichkeit zu erhöhen.
Informationsfenster. Der rechte Arbeitsbereich ist in 6 weitere Unterbereich eingeteilt der sich über die Reitersymbole im unteren Bereich auswählen lassen. XXE wählt automatisch das Register aus, dass Sie im jeweiligen Kontext gerade benötigen. Das Attributefenster zeigt Ihnen die zu dem Element, welches Sie im Dokumentenfenster oder im Strukturfenster ausgewählt haben passenden Attribute an. Sie können die Attribute in den Wert-Feldern eingeben. Sie können die Werte auch im unteren Bereich in die vorgesehenen Felder eintragen. Wenn im rechten Bereich ein anderes Arbeitsfenster angezeigt wird können Sie das Attributefenster durch Klicken auf das Registersymbol aufrufen
Das Elementefenster zeigt Ihnen an, welche Elemente Sie nach, vor oder für ein Element einsetzen können. Es werden nur die Elemente angezeigt, die an dieser Stelle möglich sind. Wenn im rechten Bereich ein anderes Arbeitsfenster angezeigt wird können Sie das Attributefenster durch Klicken auf das Registersymbol D aufrufen
Die weiteren Fenster im rechten Arbeitsbereich sind das Suchfenster, das Rechtschreibhilfefenster, das Fenster für Sonderzeichen und das Meldungsfenster, das automatisch erscheint, wenn ein Strukturbruch vorliegt. Sie können die jeweiligen Fenster durch Anklicken der Registersymbole im unteren Bereich anwählen.

Navigation

Um sich im Dokument zu orientieren ist insbesondere die Anzeige im unteren Bereich der Menüleiste hilfreich. Hier wird die Hierarchiebene angezeigt, in der sich der Cursor im Moment befindet.

Um diese Information für das Navigieren zu nutzen müssen Sie folgendermaßen vorgehen:

Angenommen der Cursor steht wie in der Abbildung auf dem Element imagedata, Sie wollen aber das gesamte mediaobject markieren. Sie können nun entweder über die Pfeilsymbole in der Menüleiste die Auswahl erweitern.

Dazu klicken Sie auf den Pfeil nach oben, solange, bis das gewünschte Elternelement angezeigt wird. In die anderen Richtungen können Sie die Auswahl verkleinern oder zu einem Element geicher Ebene nach vorne oder nach hinten springen.

Einfacher gehts mit dem shortcut STRG-Richtungstasten. Damit können Sie die Auswahl beliebig erweitern oder verkleinern.

Elemente einfügen

Elemente über Zwischenablage einfügen

Die schnellste Art, Elemente einzufügen erfolgt über die Zwischenablage. Kopieren Sie ein Element oder eine Struktur, die Sie bereits bearbeitet haben indem Sie diese wie unter Navigation beschrieben markieren und anschließend kopieren.

Platzieren Sie den Cursor an die Stelle, wo Sie die gleich Information einfügen wollen und klicken Sie die rechte Maustaste.

Je nachdem ob das Element danach, davor oder an Stelle des Elementes eingefügt werden kann, wählen Sie die gewünschte Position aus. Es wird übrigens immer nur die Position angezeigt, die an dieser Stelle möglich ist. Alle anderen Positionen werden ausgegraut. Sollte keine Option ausgewählt werden können so ist das Einfügen an dieser Stelle nicht möglich.

Den Inhalt der Zwischenablage können Sie übrigens durch das Symbol unter dem rechten Arbeitsbereich sehen . Klicken Sie auf das clipboard Symbol, wird der Inhalt im Sourcecode angezeigt.

Die Einfügeoperationen können Sie außer mit dem Kontextmenü der rechten Maustaste auch mit den Symbolen in der Menüleiste durchführen: auch hier wir nur das Symbol angezeigt, was an dieser Stelle möglich ist.

Noch einfacher gehts über die shortcuts: STRG+U, STRG+V, STRG+W, für Elemente davor, an die Stelle, oder danach einzufügen.

Elemente über den rechten Arbeitsbereich einfügen

Positionieren Sie den Cursor an die Stelle, an der Sie ein Element einfügen wollen. Wählen Sie nun im Elementefenster des rechten Arbeitsbereiches das Kommando Einfügen aus.

Es werden Ihnen alle Elemente angezeigt, die an dieser Stelle eingefügt werden können. Klicken Sie das gewünschte Element an. Wenn Sie bereits wissen, welches Element Sie einfügen wollen können Sie im unteren Bereich in das Fenster Name, einen Teil oder den vollständigen Namen des gewünschten Elementes eingeben.

Durch Betätigen der Leertaste wird die Auswahl im Elementefenster auf die passenden Elemente beschränkt.

Elemente über frühere Kommandos einfügen

Rufen Sie mit der Tastenkombination STRG+Umschalt+A das Fenster frühere Kommandos auf

Diese Fenster ist sehr hilfreich und beschleunigt das Eingeben um Einiges. In diesem Menü werden alle früheren Kommandos Ihrer (leider nur dieser) Arbeitssitzung angezeigt und gleichzeitig die passenden für die aufrufende Stelle ausgewählt.

Wählen Sie mit der Maus das entsprechende Kommando aus.

Validieren der Dokumente

Sie können Ihren Dokumentationsfortschritt jederzeit während des Arbeitens mit der unscheinbaren Validiertaste ganz links unten überprüfen. XXE überprüft das Dokument auch bei jeder Speicherung. Sollten Fehler auftreten werden diese im rechten Arbeitsbereich angezeigt.

Text und Inline Elemente

Absätze

Das wichtigste und häufigste Element ist das para Element, also ein normaler Absatz ohne Formatierungen. Ein para Element erzeugen Sie, indem Sie:

  1. Währen des Schreibens die Return Taste drücken

  2. Über das Symbol in der Menüleiste den para einfügen

  3. Mit der rechten Maustaste Einfügen und para auswählen

  4. Im rechten Arbeitsbereich aus der Menüleiste auswählen und aus der Auswahl der angebotenen Elemente para auswählen

AttributeVerwendung
idGeben Sie Ihrem Abschnitt einen eindeutigen Bezeichner, wenn Sie darauf verweisen wollen.
conditionFür profiling, wenn Sie diesen Abschnitt für bestimmte Publikationen verwenden wollen
revisionflagIdentifikation des Überarbeitungsstandes

Inline Formatierungen

Wenn Sie innerhalb eines Absatzes (para) bestimmte Wörter auszeichnen wollen haben Sie in XXE folgende Möglichkeiten. Markieren Sie zuerst das Wort oder den Bereich, den Sie aus:

  1. Die einfachste Möglichkeit besteht darin, die häufigsten Elemente über das Symbol in der Menüleiste auszuwählen. Es stehen dort die folgenden Auszeichnungen zur Verfügung:

  2. Mit der rechten Maustaste Einfügen und die gewünschten Elemente auswählen

  3. Im rechten Arbeitsbereich aus der Menüleiste auswählen und aus der Auswahl der angebotenen Elemente die gewünschte Auszeichnung auswählen

Element über Menüleiste Verwendung
emphasisHervorhebung, wird standardmäßig kursiv ausgezeichnet
emphasis (bold)Hervorhebung, fett ausgezeichnet
filenameAuszeichnung von Dateinamen und Dateien
commandBildschirmbezeichnung von Kommandos aus einer Anwendung
guibuttonBezeichnung einer Schaltfläche einer Anwendung
guimenuBezeichnung eines Menüs oder eines Menüeintrages in einer Anwendung
keysymBezeichnung einer Taste durch die eine Aktion ausgelöst wird

Element über KontextmenüVerwendung
emailemailadressen, werden in der PDF Ausgabe in Klammern d.h mit ausgezeichnet. In der HTML- Ausgabe wird der HTML Code mailto: vorangestellt um bei Anklicken die Mailapplikation zu starten.
computeroutputAusgabe eines Programms
userinputEingabe eines Benutzers in einem Programm
trademarkHandelsmarke, wird bei der Ausgabe mit einem hochgestellten TM gekennzeichnet . Trademark
subscriptTiefergestellte Ausgabe
superscriptHochgestellte Ausgabe
productnameBezeichnung eines geschützten Produktes

Verweise (Links)

ulink

Ein ulink Element dient dazu, einen Verweis außerhalb des Dokumentes beispielsweise auf eine externe Datei oder ins Internet zu platzieren. Um einen ulink zu erzeugen müssen Sie das Wort oder die Passage, die auf den Verweis zeigen soll mit der Maus markieren.

Wenn Sie die enstprechende Stelle markiert haben, wählen Sie das Symbol für Verweise aus der Menüleiste und wählen das Element ulink aus.

Ihre Markierung wird nun blau ausgezeichnet und unterstrichen. Im rechten Arbeitsbereich öffnet sich das Attributefenster in dem das Attribut url fett markiert ist und als Wert ??? enthält.

Klicken Sie in das Attributefeld und geben Sie Ihren Verweis ein.

AttributeVerwendung
urlIst ein Mussattribut zum Verweisziel. Verweise ins Internet müssen komplett mit Protokoll (http://www.seite.com) eingegeben werden, www.seite.com reicht nicht aus.
revisionflagIdentifikation des Überarbeitungsstandes. Kannattribut

link

Ein link Element dient dazu, einen Verweis innerhalb des Dokumentes zu setzen.

Um einen link zu erzeugen müssen Sie das Wort oder die Passage, die auf den Verweis zeigen soll mit der Maus markieren.

Wenn Sie die entsprechende Stelle markiert haben, wählen Sie das Symbol für Verweise aus der Menüleiste und wählen das Element link aus.

Ihre Markierung wird nun blau ausgezeichnet und unterstrichen. Im rechten Arbeitsbereich öffnet sich das Attributefenster in dem das Attribut linkend fett markiert ist und als Wert ??? enthält.

Klicken Sie in das Attributefeld und geben Sie die ID der Passage ein, auf die Sie verweisen. Wenn Sie die ID nicht mehr wissen, können Sie sich eine Liste der vergebenen IDs anzeigen lassen und daraus die gewünschte ID aussuchen. Gehen Sie dazu folgendermaßen vor:

  1. Dazu klicken Sie mit der linken Maus in das Attributefeld linkend, so dass im unteren Bereich des Attributefenster der Wert linkend im Feld Wert angezeigt wird. Sie können den Wert linkend auch direkt in das Feld eingeben.

    Klicken Sie nun den Schalter neben dem Feld Wert an. Es öffnet sich ein Fenster mit allen bereits vergebenen IDs.

  2. Wählen Sie die ID Ihrer Zielpassage aus.

AttributeVerwendung
linkendIst ein Mussattribut zum Verweisziel. Nur für interne Links innerhalb des Dokumentes.
revisionflagIdentifikation des Überarbeitungsstandes. Kannattribut

xref

Wie das Element link ist auch das Element xref ein Verweis innerhalb eines Dokumentes auf eine vorher vergebene ID. Allerdings wird beim xref die Bezeichnung des Verweiszieles übernommen und an Stelle des Elementes gesetzt.

Sie können also keine Wörter oder Passagen markieren und verlinken, üblicherweise steht ein xref am Ende eines Satzes oder Abschnittes mit dem entsprechenden Hinweis auf einen anderen Abschnitt oder ein anderes Kapitel. Kapitel 2, Zweck

Um einen xref zu erzeugen klicken Sie mit der rechten Maustaste an das Ende eines Abschnittes oder Satzes und fügen über das Kontextmenü Einfügen.. oder Danach Einfügen.. das Element xref ein.

An die Stelle des Cursors erscheint nun folgendes Symbol:

Klicken Sie das Symbol mit der rechten Maustaste an, so dass es einen roten Rahmen erhält.

Im rechten Arbeitsbereich öffnet sich das Attributefenster in dem das Attribut linkend fett markiert ist und als Wert ??? enthält.

  1. Klicken Sie mit der linken Maus in das Attributefeld linkend, so dass im unteren Bereich des Attributefenster der Wert linkend im Feld Wert angezeigt wird. Sie können den Wert linkend auch direkt in das Feld eingeben.

    Klicken Sie nun den Schalter neben dem Feld Wert an. Es öffnet sich ein Fenster mit allen bereits vergebenen IDs.

  2. Wählen Sie die ID Ihrer Zielpassage aus.

  3. Das xref Symbol wir jetzt umgewandelt indem es um Ihr Attribut für linkend erweitert wird.

    In der Ausgabe wird je nach Ihrer Parametereinstellung das Kapitel, Nummerierung desselben etc. angegeben.

AttributeVerwendung
linkendIst ein Mussattribut zum Verweisziel. Nur für interne Links innerhalb des Dokumentes oder für eingebundene Dokumente (wir noch beschrieben)
revisionflagIdentifikation des Überarbeitungsstandes. Kannattribut

olink

Verwenden Sie olinks, wenn Sie zwischen DocBook Modulen verknüpfen wollen und eine modulare Dokumentation planen. Die Vorgehensweise zum Setzen von olinks ist oben beschrieben.

Grafiken

Hauptsächlich werden zwei verschiedene Grafikarten verwendet

  • Blockgrafiken: Grafiken mit oder ohne Abbildungstitel als Blockelement : Verwendete Elemente: figure, informalfigure, mediaobject, bevorzugt: figure und mediaobject

  • inlinegrafiken: Grafiken ohne Abbildungstitel als Blockelement. Verwendete Elemente: inlinemediaobject, inlinegraphic. Bevorzugt: inlinemediaobject.

mediaobject

Wird bevorzugt für Grafiken verwendet. Da es sich um ein Blockelement handelt, fügen Sie es am Ende eines Absatzes oder eines anderen Blockelementes ein.

  1. Mit der rechten Maustaste Einfügen und die mediaobject auswählen. Es erscheint ein Symbol für das Einfügen eines Bildes durch einen roten Rahmen umrahmt.

    Danach gibt es zwei Möglichkeiten:

    1. Klicken Sie mit der linken Maustaste auf das Grafiksymbol und geben im rechten Arbeitsbereich im Attributefenster im Attribut fileref ( wird durch drei Fragezeichen und Hervorhebung gekennzeichnet) den Dateinamen ein:

    2. Klicken Sie mit der rechten Maustaste auf das Grafiksymbol. Geben Sie in das sich öffnende Menü im unteren Bereich den Dateinamen ein oder wählen Sie die Grafik aus, indem Sie das Dateiordnersymbol anklicken und die Grafik auswählen.

    Attribute (imagedata)Verwendung
    filrefDateiname und Speicherort der verknüpften Grafik. Kann relativ oder absolut zum Dokument angegeben werde. Empfohlen: relative Verknüpfung
    aligncenter, left right, Ausrichtung des mediaobject Elementes im Satzfluss.
    valignVertikale Ausrichtung insbesondere beim inlinemediaobject
    witdhBreite des Objectes. Bezieht sich bei DU1 Dokumenten nur auf die PDF-Version. Bei der HTML- Ausgabe wird die Originalgröße der Grafik verwendet. Wollen Sie in HTML und PDF-Ausgabe die gleiche Größe, müssen Sie den Parameter ignore.image.scaling auf 0 setzen. Wenn Sie unterschiedliche Größen in beiden Ausgaben festlegen wollen, müssen Sie zwei imageobjekte in das mediaobject eingeben und diese bei der Ausgabe mit Parametern steuern.
    revisionflagIdentifikation des Überarbeitungsstandes. Kannattribut

figure

Wenn Sie eine Grafik mit einem Titel erzeugen wollen, wählen Sie das Element figure. Der Titel der Grafik erscheint auch in der Abbildungsansicht am Anfang des Dokumentes. Da es sich um ein Blockelement handelt, fügen Sie es am Ende eines Absatzes oder eines anderen Blockelementes ein. Die Vorgehensweise ist weitgehend analog zum Einfügen eines mediaobjectes. Die Abbildungen werden automatisch nummeriert.

  1. Mit der rechten Maustaste Einfügen und figure(Abbildung) auswählen. Geben Sie den Titel des Bildes ein:

    Markieren Sie danach in der Baumansicht im linken Arbeitsbereich das Unterelement mediaobject

    und öffnen Sie mit der rechten Maustaste das Kontextmenü Einfügen. Wählen Sie aus der Auswahl das Element imageobject.

    Öffnen Sie mit der rechten Maustaste das Kontextmenü Einfügen. Wählen Sie aus der Auswahl das Element imagedata. Es erscheint das Symbol zum Einfügen einer Grafik.

    Danach gibt es zwei Möglichkeiten:

    1. Klicken Sie mit der linken Maustaste auf das Grafiksymbol und geben im rechten Arbeitsbereich im Attributefenster im Attribut fileref ( wird durch drei Fragezeichen und Hervorhebung gekennzeichnet) den Dateinamen ein:

    2. Klicken Sie mit der rechten Maustaste auf das Grafiksymbol. Geben Sie in das sich öffnende Menü im unteren Bereich den Dateinamen ein oder wählen Sie die Grafik aus, indem Sie das Dateiordnersymbol anklicken und die Grafik auswählen.

    Attribute (figure)Verwendung
    idGeben Sie Ihrer Grafik einen eindeutigen Namen um darauf verweisen zu können.
    floatDer vorgegebene Wert 0 bedeutet, dass die Grafik bei Ausgabe exakt an dieser Stelle im Textfluss erscheinen muss. Setzen Sie den wert auf 1, wenn das Ausgabesystem die Position des figure Elementes an einen geeigneten Ort verschieben soll (kann dann durch stylesheet vorgegeben sein)
    pgwideEin Wert von 1 lässt die das figure Element über die gesamte Seite ausgeben. Bei einem Wert von 1 können auch andere Element auf der Seite erscheinen.

inlinemediaobject

Zum Einfügen einer Grafik im Textfluss z.B. für Tasten oder ähnliches abzubilden. Das inlinemediaobject wird direkt am Cursor eingefügt.

  1. Mit der rechten Maustaste Einfügen und inlinemediaobject

    auswählen

  2. Im rechten Arbeitsbereich aus der Menüleiste auswählen und aus der Auswahl der angebotenen Elemente die gewünschte Auszeichnung auswählen

    Es wird ein grauer Bereich eingeblendet.

    Wählen Sie in der Strukturansicht im linken Arbeitsbereich das Element textobjekt aus

    Wählen Sie mit der rechten Maustaste im Kontextmenü Ersetzen.. aus und ersetzen das textobjekt durch ein imageobjekt.

    Es erscheint das Symbol zu Einfügen einer Grafik. Die weitere Vorgehensweise ist analog zu den Blockgrafiken.

    Attribute siehe imagedata

Tabellen

Es gibt zwei Tabellenarten in verschiedenen Ausprägungen, die verwendet werden können: table und informaltable.

Sie können Tabellen innerhalb eines Absatzes oder als eigenen Absatz einfügen.

table (mit Titel)

Sie können eine Tabelle mit oder ohne Kopfzeile einfügen. Wenn Sie das Element table verwenden wird eine Tabelle mit einem Tabellentitel eingefügt, der in der Tabellenübersicht am Anfang Ihres Dokumentes angezeigt wird. Die Nummerierung erfolgt automatisch. Gehen Sie zum Einfügen einer Tabelle folgendermaßen vor:

table mit Kopfzeile

Tabelle B.2. table (Kopf_Zeile)

Kopfzeile linksKopfzeile rechts
erste Spaltezweite Spalte
  

  1. Fügen Sie mit der rechten Maustaste und dem Kontextmenü Einfügen das Element table(Kopf_Zeile) ein.

    Dies ist ein von XXE vorkonfiguriertes Element, das Ihnen eine zweispaltige Tabelle mit einer Kopfzeile und zwei Zeilen erzeugt.

  2. Geben Sie den Titel der Tabelle ein

  3. Passen Sie Ihre Tabelle wie unten beschrieben an.

[Tipp]Tipp

Sie können in der Tabelle mit der tab- Taste zwischen den Zellen navigieren.

table ohne Kopfzeile

[Anmerkung]Anmerkung

Diese Tabelle wird auch eingefügt, wenn Sie eine Tabelle über das Menüsymbol aus der Kopfzeile einfügen.

Tabelle B.3. table

erste Spalte 
  

  1. Fügen Sie mit der rechten Maustaste und dem Kontextmenü Einfügen das Element table ein.

    Dies ist ein von XXE vorkonfiguriertes Element, das Ihnen eine zweispaltige Tabelle mit zwei Zeilen erzeugt.

  2. Geben Sie den Titel der Tabelle ein

  3. Passen Sie Ihre Tabelle wie unten beschrieben an.

Sie können in der Tabelle mit der tab- Taste zwischen den Zellen navigieren.

informaltable (ohne Titel)

Sie können eine Tabelle mit oder ohne Kopfzeile einfügen. Wenn Sie das Element informaltable verwenden wird eine Tabelle ohne Tabellentitel eingefügt, die Tabelle erscheint auch nicht in der Tabellenübersicht am Anfang Ihres Dokumentes

informaltable mit Kopfzeile

Kopfzeile linksKopfzeile rechts
erste Spalte 
  

  1. Fügen Sie mit der rechten Maustaste und dem Kontextmenü Einfügen das Element informaltable(Kopf_Zeile) ein.

    Dies ist ein von XXE vorkonfiguriertes Element, dass Ihnen eine zweispaltige Tabelle mit einer Kopfzeile und zwei Zeilen erzeugt.

  2. Passen Sie Ihre Tabelle wie unten beschrieben an.

Sie können in der Tabelle mit der tab- Taste zwischen den Zellen navigieren.

informaltable ohne Kopfzeile

erste Spalte 
  

  1. Fügen Sie mit der rechten Maustaste und dem Kontextmenü Einfügen das Element informaltable ein.

    Dies ist ein von XXE vorkonfiguriertes Element, dass Ihnen eine zweispaltige Tabelle mit zwei Zeilen erzeugt.

  2. Passen Sie Ihre Tabelle wie unten beschrieben an.

Sie können in der Tabelle mit der tab- Taste zwischen den Zellen navigieren.

Tabellen anpassen

Spalten oder Zeilen hinzufügen/löschen

Wenn Sie Spalten oder Zeilen hinzufügen oder löschen wollen, verwenden Sie die Funktionen aus dem Menü Docbook.

Setzen Sie dazu den Cursor in eine Spalte oder Zelle, die Sie manipulieren wollen.

Zeilen, Spalten ausrichten

Positionieren Sie den Cursor in die Zelle, die Sie ausrichten wollen. Wählen Sie im rechten Arbeitsbereich im Attributefenster das Attribut align aus. Es klappt eine Liste mit den möglichen Ausrichtungen auf. Wählen Sie die passende aus.

Größe von Tabellenspalten definieren

Manchmal ist es notwendig, den Spalten eine gewisse Größe zuzuweisen. Standardmäßig werden die Tabellen immer auf eine Größe von 100% der Seitenbreite mit gleichem Verhältnis der Spalten ausgerichtet. Um diese Ausrichtung zu ändern gehen Sie folgendermaßen vor:

  1. Markieren Sie die Elemente tbody im linken Arbeitsbereich im Strukturbaum.

  2. Wählen Sie aus dem Kontextmenü mit der rechten Maustaste Einfügen aus und wählen Sie das Element colspec. aus. Dies ist eine Spezifizierung einer bestimmten Spalte.

  3. Markieren Sie das Element mit der linken Maustaste und geben Sie die Attribute für das Element colspec im rechten Arbeitsbereich ein. Sie definieren hiermit die Spezifikation für die erste Spalte

    Die Attribute, die Sie hier eingeben gelten für die gesamte Spalte.

  4. Fügen Sie nun ein weiteres colspec Element für die nächsten Spalten ein, indem Sie das Element mit der rechten Maustaste kopieren und im selben Dialog -> Danach aus Ablage einfügen auswählen. Sie können immer nur so viele colspec Elemente anlegen wie Spalten vorhanden sind.

  5. Geben Sie die Attribute für die zweite Spalte ein. :

    [Wichtig]Wichtig

    Achten Sie darauf, dass die Summe der Spaltenbreite nicht breiter als Ihre Seitenbreite bei der PDF-Ausgabe ist.

    In XXE wird über die Tabelle nun die Spezifikation in folgender Form dargestellt:

Attribute (table)Verwendung
idGeben Sie Ihrer Tabelle einen eindeutigen Identifikator, um darauf verweisen zu können.
frameBestimmt den Rahmen der Gesamttabelle, wenn er unterschiedlich der vorgegebenen Umrahmung aller Tabellen sein soll.
orientport hat die gleiche Orientierung wie der Rest des Textes, bei land 90° gegen den Uhrzeigersinn verschoben.
pgwideEin Wert von 1 lässt die das figure Element über die gesamte Seite ausgeben. Bei einem Wert von 1 können auch andere Element auf der Seite erscheinen.

Listen

itemizedlist

Fügen Sie die ungeordnete Liste über das Symbol in der Menüleiste ein.

  • Es wird eine Liste mit dem ersten Unterpunkt erzeugt.

  • Wollen Sie den nächsten Unterpunkt erzeugen, drücken Sie den Knopf in der Menüleiste.

    Mit der Returntaste kommen Sie nur in einen neuen para innerhalb desselben Listenelementes. MS-Word™ Benutzer müssen sich also umstellen...

    • genauso können Sie einen weiteren Unterpunkt oder

      1. eine nummerierte Liste innerhalb eines Unterpunktes erzeugen, indem Sie die oder die Taste in der Menüleiste innerhalb eines Listeneintrages aktiviert.

AttributeVerwendung
idGeben Sie Ihrer Liste einen eindeutigen Identifikator, um darauf verweisen zu können.
markWas für ein Symbol soll für die Liste verwendet werden. Ist abhängig vom Ausgabemedium, wird von DocBook nicht vorgegeben
spacingSoll der vertikale Abstand zwischen den Listenelementen minimiert werden, muss der Wert auf compact gesetzt werden.

orderedlist

Eine orderedlist ist eine nummerierte Liste. Wenn Sie möchten, dass die Nummerierung der Liste bei einer vorhergehenden Nummerierung weiterzählt müssen Sie das Attribut continuation auf continue umschalten. Dies geschieht im rechten Arbeitsbereich von XXE im Menüfenster.

Fügen Sie die nummerierte Liste über das Symbol in der Menüleiste ein.

  1. Es wird eine Liste mit dem ersten Unterpunkt und der Ordnungszahl 1 erzeugt.

  2. Wollen Sie den nächsten Unterpunkt erzeugen, drücken Sie den Knopf in der Menüleiste.

    Mit der Returntaste kommen Sie nur in einen neuen para innerhalb des selben Listenelementes. MS-Word Benutzer müssen sich also umstellen...

    • genauso können Sie einen weiteren Unterpunkt oder

      1. eine nummerierte Liste innerhalb eines Unterpunktes erzeugen, indem Sie die oder die Taste in der Menüleiste innerhalb eines Listeneintrages aktiviert.

Sie können der nummerierten Liste verschiedene Ordnungscharacteristika zuweisen, indem Sie das Attribut numeration der Liste entsprechend in alphanummerische oder andere Aufzählung umwandeln.

AttributeVerwendung
idGeben Sie Ihrer Liste einen eindeutigen Identifikator, um darauf verweisen zu können.
continuationWird der Wert auf continue gesetzt, zählt die Liste in Bezug auf die letze verwendete Liste weiter.
inheritnumBezieht sich auf untergeordnete nummerierte Listen. Soll die Nummerierung von übergeordneten Listen in die untergeordnete Liste mitaufgenommen werden? Ist das Attribut auf inherit gesetzt, wird die Nummerierung des übergeordneten Listenelementes mitgenommen, z.B. 2.2
NumerationArt der Nummerierung: Arabic (arabische Zahlen), Loweralpha (kleine Buchstaben) , upperalpha ( Großbuchstaben), upperroman (römisch Groß). lowerroman (römisch klein)
spacingSoll der vertikale Abstand zwischen den Listenelementen minimiert werden, muss der Wert auf compact gesetzt werden.

variablelist

Eine variable Liste ist eine Liste mit variablen Listenelementen, die Sie selbst bestimmen wie im folgenden Beispiel. Sie können diese Liste natürlich auch beliebig mit anderen Listenarten kombinieren.

Anfang

Aller Anfang ist schwer

Mitte

Die Mitte ist der Weg

Ende

Am Ende war das Ende

Fügen Sie die ungeordnete Liste über das Symbol in der Menüleiste ein.

  • Es wird eine Liste mit dem ersten Unterpunkt erzeugt. Füllen Sie das Element term, das ist das variable Listenelement und das Element listitem mit Inhalt.

  • Wollen Sie den nächsten Unterpunkt erzeugen, drücken Sie den Knopf in der Menüleiste.

    Mit der Returntaste kommen Sie nur in einen neuen para innerhalb des selben Listenelementes. MS-Word Benutzer müssen sich also umstellen...

    • genauso können Sie einen weiteren Unterpunkt oder

      1. eine nummerierte Liste innerhalb eines Unterpunktes erzeugen, indem Sie die oder die Taste in der Menüleiste innerhalb eines Listeneintrages aktiviert.

AttributeVerwendung
idGeben Sie Ihrer Liste einen eindeutigen Identifikator, um darauf verweisen zu können.
termlengthDefinieren Sie eine Länge für die term Elemente. Sind die Elemente länger als die deklarierte Länge wird eine alternative Darstellung der Elemente gewählt.

simplelist

Ist eine einfache Aufzählung ohne besondere Ordnungszeichen.

Diese Listenart ist nicht in der Menüleiste implementiert

Wählen Sie mit dem Kontextmenü der rechten Maustaste oder aus dem rechten Arbeitsbereich von XXE den Befehl Einfügen oder je nach Position Einfügen danach und fügen das Element simplelist ein.

Geben Sie In das Element member Ihren Inhalt ein.

Ich bin das erste Mitglied in der simplelist. weitere Mitglieder können Sie mit der Return- Taste erzeugen.
Ich bin das zweite Mitglied
Ich bin das dritte Mitglied

AttributeVerwendung
idGeben Sie Ihrer Liste einen eindeutigen Identifikator, um darauf verweisen zu können.
columnsAnzahl der Spalten, die für das Attribut type herangezogen werden (standardmäßig=1)
typeInline: member-Elemente der Liste werden kommasepariert hintereinander dargestellt, horiz: tabellendarstellung (nach Zeilen), vert: Tabellendarstellung nach Spalten (Standard)

Hervorgehobene Absätze

warning, note, caution, important, tip

Hinweise werden alle nach dem gleichen Prinzip erzeugt:

Wählen Sie mit dem Kontextmenü der rechten Maustaste oder aus dem rechten Arbeitsbereich von XXE den Befehl Einfügen oder je nach Position Einfügen danach und fügen das entsprechende Element ein. Gehen Sie sparsam mit diesen Hinweisen um, damit die Wirkung beim Leser nicht verpufft.

[Anmerkung]Anmerkung

Dies ist ein Hinweis für Zusatzinformationen, die nicht zur unmittelbaren Bedienung des Gerätes/SW gehören. In der deutschen Ausgabe steht dort Anmerkung (note)

[Wichtig]Wichtig

Sollten Sie dann verwenden wenn etwas besondere Wichtigkeit hat . In der deutschen Ausgabe steht dort Wichtig. (important)

[Achtung]Achtung

Kann für den Benutzer und für ein System einen Schaden bedeuten. Im Deutschen mit Achtung übersetzt. (caution)

[Warnung]Warnung

Kann für den Benutzer eine Gefahr für Leib und Leben bedeuten oder für ein SW System einen Totalabsturz bzw. irreparablen Zustand, deshalb nur dort einsetzen, wo dies auch gerechtfertigt ist. Im Deutschen steht dort Warnung. (warning)

[Tipp]Tipp

Einen Tipp, der nicht unmittelbar zur Bedienung des Gerätes notwendig ist. Im Deutschen Tipp (tip)

Example

Wählen Sie mit dem Kontextmenü der rechten Maustaste oder aus dem rechten Arbeitsbereich von XXE den Befehl Einfügen oder je nach Position Einfügen danach und fügen das Element example ein. Beispiele können in einer Übersicht über alle vorhandenen Beispiele am Anfang des Dokumentes aufgenommen werden.

Geben Sie im vorgesehenen Feld den Titel für Ihr Beispiel ein. Die Nummerierung wird automatisch vergeben.

Beispiel B.1. Beispiel 1

Geben Sie hier Ihren Inhalt für das Beispiel ein. Dies ist nur ein Beispiel

programlisting

Die Besonderheit am Element programlisting ist, dass der Inhalt in jeder Ausgabe so dargestellt wird, wie Sie ihn im vorgesehenen Bereich eingeben. Es werden also alle Zeilenumbrüche, Einrückungen oder ähnliche Formatierungen beibehalten. Außerdem können Sie mit sog. Callouts, d.h. nummerierte grafische Verweise, ähnlich Fußnoten auf bestimmte Passagen erklärend zugreifen.

Um ein Programmlisting einzugeben, gehen Sie folgendermaßen vor:

Wählen Sie mit dem Kontextmenü der rechten Maustaste oder aus dem rechten Arbeitsbereich von XXE den Befehl Einfügen oder je nach Position Einfügen danach und fügen das Element programlisting ein.

Fügen Sie hier im grau umrandeten Bereich Ihr

    Programmlisting ein, indem Sie es einkopieren:
<?dbhh topicname="ID_zweck" topicid="1000"?>
 <title id="titel_zweck">Zweck</title> 1
   <para>Die vorliegende Dokumentation gibt Anleitung zur Installation und
    Einrichtung zur Bedienung von DocBook Umgebung. Aktuelle Version können
    Sie im Downloadbereich auf der <ulink url="http://axitd.goshaky.com">AXitd
    Homepage </ulink>erhalten. 
....
 </para>
</chapter>

Achten Sie darauf,2 dass der Inhalt des programlisting Elementes
genauso in der Ausgabe erscheint,
 d.h. verkürzen Sie evtl. Zeilen, die über den Seitenspiegel
hinausgehen

Um Callouts(Verweise) einzufügen gehen Sie folgendermaßen vor:

  1. Positionieren Sie den Cursor an der Stelle im Programmcode, an der Sie den Verweis setzen wollen

  2. Wählen Sie mit dem Kontextmenü der rechten Maustaste oder aus dem rechten Arbeitsbereich von XXE den Befehl Einfügen oder je nach Position Einfügen danach und fügen das Element co ein. co steht für callout.

  3. Klicken Sie mit der linken Maustaste auf das Zahlenelement, so dass dies einen roten Rahmen bekommt.

  4. Geben Sie nun im rechten Arbeitsbereich ins Attributefenster für das Attribut id einen beliebigen Wert ein.

  5. Fügen Sie nach Bedarf noch gleiche Verweisziele nach derselben Methode ein

  6. Fügen Sie nun eine Liste mit den Verweisen an eine beliebige Stelle in Ihrem weiteren Text ein:

    1

    dies ist der Verweis auf das programmlisting-Beispiel

    2

    dies ist der zweite Verweis

    Wählen Sie mit dem Kontextmenü der rechten Maustaste oder aus dem rechten Arbeitsbereich von XXE den Befehl Einfügen oder je nach Position Einfügen danach und fügen das Element calloutlist ein. Es wird eine Liste mit dem ersten Element eingefügt.

  7. Klicken Sie mit der linken Maustaste auf das erste Element und wählen im rechten Arbeitsbereich im Attributefenster das Attribut arearefs aus. arearefs stellt den Bezug zu einem Bereich in einem Programmlisting her. In diesem Fall ist dies das vorher definierte co Element.

  8. Wenn Sie die vorher benannte id des Elementes co noch kennen, können Sie diese direkt in das Feld arearefs eingeben, wenn nicht können Sie sich alle id anzeigen lassen, indem Sie die Liste bereits vergebener IDs aufrufen.

    Dazu klicken Sie mit der linken Maus in das Attributefeld arearefs, so dass im unteren Bereich des Attributefenster der Wert arearefs im Feld Wert angezeigt wird. Sie können den Wert arearefs auch direkt in das Feld eingeben.

    Klicken Sie nun den Schalter neben dem Feld Wert an. Es öffnet sich ein Fenster mit allen bereits vergebenen IDs.

    Wählen Sie die ID im linken Bereich des Fensters aus indem Sie mit den Pfeiltasten navigieren.

  9. Geben Sie nun den beschreibenden Text für den ersten callout ein.

  10. Das nächste Element erzeugen Sie wie bei jeder Liste mit dem Menüschalter aus der Menüleiste

Anhang C. DocBook XML

Nachfolgend wird das Konzept von DocBook, der Aufbau eines DocBook Dokumentes und die notwendigen tools zur Erzeugung von DocBook Dokumenten beschrieben

Ein neues DocBook beginnen

set, book oder article?

Stichwortverzeichnis

A

Absatz, Absätze

B

Batch Datei, Konfigurationsdateien
Befehle
Referenz, Referenz Befehle in DU1

E

Erstübersetzung, Erstübersetzung

F

FAQ, FAQs
figure
einfügen, figure
Filenames, Text-align
freemind_export, Mindmap: freemind export

I

imagelist, Übersicht über verwendete Grafiken
inlineformatierung, Inline Formatierungen
inlinemediaobject
einfügen, inlinemediaobject
Installation, Installation
Struktur, Entpacken /Struktur

M

make_datafile_html.bat, make_datafile_html.bat
make_datafile_pdf.bat, make_datafile_pdf.bat
make_freemind, make_freemind.bat
make_html, make_html.bat
make_html.bat, make_htmlhelp.bat
make_htmlhelp_config.bat, make_htmlhelp_config.bat
make_pdf, make_pdf.bat
make_pdf_module, make_pdf_module.bat
Masterdokument
anlegen, Masterdokument anlegen
mediaobject
einfügen, mediaobject
Modul
erstellen, Module anlegen
HTML, Gesamtdatei nach HTML publizieren
PDF, Gesamtdatei nach PDF publizieren
modulare Dokumente, Modulare Dokumente
Module
Grafiken, Grafiken und Pfadangaben
Linkziele, Linkziele
publizieren, Publikation Gesamtdokumentation

Q

Quickstart, Quickstart

R

remap, Remap Tool
resolve_modules.bat, resolve_modules.bat
RTF
Publikation, Publikation in RTF o. WML

S

Schriftart, Schriftart wechseln
Seitenumbruch, Seitenumbrüche in AXitd DU1
Systemumgebung
einrichten, Systemumgebung einrichten

T

Tabelle
anpassen, Tabellen anpassen
einfügen, Tabellen
target database, Data file erzeugen, Target Database
Titelseiten, Titelseiten
Titelseiten_template.bat, Titelseiten_template_erzeugen.bat
tools, Tools
XSL Configurator, DOCBook XSL Configurator
Tools
remap, Remap Tool
Translation Memory
Vorbereitung, Vorbereitung TM System

V

Verzeichnis
Struktur, Entpacken /Struktur

X

XInclude
Konzept, Konzept von XInclude
XIncludes
auflösen, XIncludes auflösen
XSL Configurator, DOCBook XSL Configurator