Ditalog - DITA-Praxisbeispiele für Redakteure

Ditalog 1.0Praxisbeispiele für Redakteurezum Dokumentationsstandard DITA

Andreas Petersellwww.ditalog.com

XML to PDF by RenderX XEP XSL-FO Formatter, visit us at http://www.renderx.com/

http://www.renderx.com/

http://www.renderx.com/reference.html

http://www.renderx.com/tools/







Inhalt

Einleitung: Praxisbeispiele für Redakteure...................................................v

Kapitel 1: Ideen für Software-Dokumentationen.........................................7E-Mail-Link für Feedback........................................................................................................................8

Schriftart für Zahlen.................................................................................................................................9

Kapitel 2: Ideen für Software-Online-Hilfen..............................................13Kontextsensitive Hilfe per Ditamap.......................................................................................................14

Seiteninhaltsverzeichnis am rechten Rand.............................................................................................15

Zugang zum Bildschirm voranstellen.....................................................................................................17

Kapitel 3: HTML als Ausgabeformat...........................................................21Navigationsbaum mit Plugin TOCJS.....................................................................................................22

DITA to Wordpress Import Tool.............................................................................................................26

Kapitel 4: CHM als Ausgabeformat.............................................................31Umlaute im Inhaltsverzeichnis...............................................................................................................32

Symbolschaltflächen hinzufügen...........................................................................................................32

Kapitel 5: AIR-Help als Ausgabeformat......................................................35AIR-Help-Plugin installieren.................................................................................................................36

Auto-Update einrichten..........................................................................................................................39

Umlaute im Inhaltsverzeichnis und Index..............................................................................................41

Kapitel 6: PDF als Ausgabeformat...............................................................43Inhaltsverzeichnis Print vs. Online.........................................................................................................44

Texteinrückung mit hängender erster Zeile............................................................................................45

xref-Direktlinks in Onlinehilfe vs. Print................................................................................................46

Zugang zum Bildschirm voranstellen.....................................................................................................47

Leere Seiten aus der PDF-Datei entfernen.............................................................................................49

Paragraphensymbol § im indexterm.......................................................................................................50

Kapitel 7: Tools...............................................................................................51DITA OT-Installation..............................................................................................................................52

PDF Split and Merge..............................................................................................................................53

Ditalog 1.0 | Inhaltsverzeichnis | 3






4 | Ditalog 1.0 | Inhaltsverzeichnis






Praxisbeispiele für Redakteure

Was ist das Ditalog?

Das Ditalog ist eine Erfahrungsschatzsammlung eines Redakteurs zum Dokumentationsstandard DITA (DarwinInformation Typing Architecture). Besonderheit: Sprache deutsch.

Zielgruppe

Diese Beispielsammlung ist für Solo-Redakteure gedacht. Dies hat 2 Gründe:

1. Technische Redakteure in größeren Firmen nutzen leistungsstarke Software-Tools im Redaktionsteam und habenProgrammierkollegen zur Unterstützung.

2. Die programmiertechnische Umsetzung ist die eines Redakteurs und somit für Programmierer manchmal befremdlich.Doch nur so ist eine Dokumentation der Dokumentation zu haben.

Dank

Einen leichten und trotzdem umfassenden Zugang zu DITA ermöglichte mir DITA for Solo Writers von Louise Kasemeier.

Download

• ditalog.pdf• Plugin tocofsections

IMPRESSUM

Andreas PetersellAutor:

[email protected]

www.ditalog.com

Ditalog 1.0Ausgabe:

11.06.2010Redaktionsschluß:


http://www.ditausers.org/tutorials/lone-dita/ditaguide.pdf

http://www.ditalog.com/download/ditalog.pdf

http://www.ditalog.com/download/tocofsections.zip










Kapitel

1Ideen für Software-Dokumentationen

Themen:

• E-Mail-Link für Feedback• Schriftart für Zahlen






E-Mail-Link für FeedbackEinen E-Mail-Link für jede Seite als Rückmeldungselement setzen .

Feedback des Nutzers

Durch einen E-Mail-Link auf jeder Seite der Dokumentation wird der Nutzer der Hilfe animiert, eher ein Feedback zurDokumentation zu geben bzw. speziell Hilfe zur Seite anzufordern.

Abb. 1: Feedback-Element zur Seite

Ein Klick auf den Link öffnet das E-Mailprogramm, in dem der Dateiname der Doku-Seite in der Betreffseite bereitsvorgetragen ist.

Abb. 2: Adresse und Betreff schon voreingetragen

Abb. 3: Link funktioniert auch im PDF-Output

Attribute des xref-Elements

Die Attribute des xref-Elements sind besonders wichtig: format="txt" und scope="external" müssen gesetztsein.

8 | Ditalog 1.0 | Ideen für Software-Dokumentationen






Abb. 4: Abstract-Element

Beschränkung auf Content-Seiten

Dieser Mail-Link sollte sich möglichst auf Content-Seiten beschränken. Auf Seiten, die nur der Navigation dienen, sorgtdies für Unübersichtlichkeit und ist somit überflüssig. Besonders prekär zeigt sich dies im PDF-Output.

Abb. 5: Metaangaben der Navigationsdatei HTML-Format sind überflüssig

Spam

Sollte die Hilfe tatsächlich online - also im Internet veröffentlicht werden, ist die Veröffentlichung der E-Mailadressenatürlich eine Überlegung wert.

Schriftart für ZahlenDie Schriftart CombiNumerals hilft, Zahlen auf einem Kreis darzustellen.

Ditalog 1.0 | Ideen für Software-Dokumentationen | 9






Wozu diese Schriftart?

Abb. 6: CombiNumerals in Photoshop

Die Schriftart hilft, schnell Nummerierungen auf Screenshots anzulegen. Wählt man wie im Bespiel die Art Solid,werden die Zahlen invers dargestellt. Die Zahl 2 wird erzeugt durch den Buchstaben c.

Hinweise vom Autor zum Gebrauch

Den beiden TTF-Dateien ist eine Readme-Datei zum Gebrauch sowie der Installation beigelegt. Hier die Hinweis zumGebrauch der Schrift:

CombiNumerals(tm) is a typeface for creating circled numbers, popular for use in Web graphics, documentation andinstructional material, maps, signs and guide books, for example. With CombiNumerals, you can create any numberbetween 0 and 99. Here's how:

SINGLE-DIGIT NUMBERS - The numbers 0 through 9 are created by pressing the A, B, C, D, E, F, G, H, I, and J keysrespectively (you can type either lower- or uppercase).

DOUBLE-DIGIT NUMBERS - The numbers 00 through 99 are created by first pressing one of the number keys (0-9),followed by Shift-number. For example, to create the number 67, press the 6 key followed by Shift-7. You can alsocreate two-digit circled numbers with a leading zero, 07 (0, Sh-7), for example.

MULTIPLE WEIGHTS - CombiNumerals is available in two weights -- Open and Solid. The Open weight displaysnumbers inside hollow circles. The Solid weight displays white numbers inside filled circles. The Solid weight is theBold version of the Open weight.

ADDITIONAL CHARACTERS - Several other characters besides numerals are available in this font. For instance,arrows, hands, pointers, and the Mac OS and Windows logos (including circled M and W characters) can be created.

10 | Ditalog 1.0 | Ideen für Software-Dokumentationen






These characters are commonly used by people writing documentation, but are also used for things like maps, signs,posters, guide books, etc.

Der Autor

CombiNumerals was designed and created by Sean Cavanaugh, the author of Digital Type Design Guide, The PageDesigner's Guide to Working with Type, published by Hayden Books (ISBN 1-56830-190-1). You can contact the authorvia e-mail <[email protected]>.

Ditalog 1.0 | Ideen für Software-Dokumentationen | 11











Kapitel

2Ideen für Software-Online-Hilfen

Themen:

• Kontextsensitive Hilfe perDitamap

• Seiteninhaltsverzeichnis amrechten Rand

• Zugang zum Bildschirmvoranstellen

• Zugangsweg in Online-Hilfedarstellen






Kontextsensitive Hilfe per DitamapEine Ditamap hilft, Hilfeseiten für die kontextsensitive Hilfe relativ einfach zu erstellen.

Vorteile des Map-Processings nutzen

Die Elemente <title> und <shortdesc> von eingebetteten Seiten werden immer dann als Vorankündigungangezeigt, wenn ein <topicref> andere <topicrefs> umschließt. Dieses normale ditamap processing kann sehrgut für die einfache und schnelle Erstellung von kontextsensitiven Hilfeseiten genutzt werden.

Beispiel einer Hilfeseite

Diese Seite wird extra zum Aufruf aus dem Programm über F1 bzw. der Hilfe-Schaltfläche geschrieben. Es ist eine leereSeite. Nur Titel und scortdesc sowie die gebräuchlisten Links zu den Neuigkeiten in den related links wurdengefüllt. Die 4 Links in der Mitte entstehen automatisch durch das map processing.

Abb. 7: Kontextsensitive Hilfe per ditamap

Ditamap für die Links

Hier das Beispiel der ditamap für die Link-Generierung. Hier werden die Seiten im Navigationsbaum (TOC) mit angezeigt.Ändern Sie toc="no", kann man nur aus dem Programm auf diese Seite gelangen. Obiges Beispiel ist hier die Dateicsh_ebgmain_con.xml. Sie umschließt in der Ditamap die 4 Dateien, die als Link oben zur Anzeige kommen. Aufdie csh_ebgmain_con.xml wird wird von der Software per F1-Druck verlinkt. Die Datei csh_start_con.xmldient lediglich als Anzeige im TOC.

14 | Ditalog 1.0 | Ideen für Software-Online-Hilfen






Abb. 8: Sichtbarmachen in der Navigation?

ditamap einbinden in Haupt-Map

Da eine einzelne Map für ein Projekt doch sehr unübersichtlich werden würde, wurde sie im obigen Beispiel in eineExtra-ditamap geschrieben. Diese ditamap muss nun in die Haupt-Map eingebunden werden. Hier ist ebenfalls zuentscheiden, ob die Map für die kontextsensitive Hilfe in der Navigation erscheinen soll.

Abb. 9: Einbinden in die Haupt-ditamap

Seiteninhaltsverzeichnis am rechten RandBei Concepts sollen die Überschriften jeder section am rechten Rand als kleines Inhaltsverzeichnis dieser Konzept-Seiteerscheinen.

Auf der Suche nach FAQ-Template

Bisher hatte ich für jede Frage der FAQ-Liste eine eigene Concept-Datei erstellt. Dies war jedoch zu viel Arbeit. Essollte eine Ein-Datei-Lösung her. Oben die Fragen als Link, weiter unten dann die Frage/Antwort-Einträge. Was lagnäher, als die Demo-FAQ-Spezialsierung im DITA-OT\demo-Ordner anzuschauen? Jedoch nach einem Tag gab iches auf. Die Pfade in der build_demo.xml und der faq2html_shell.xsl zum DTD-Verzeichnis stimmten nicht,da die Verzeichnisse im DITA OT 1.5 neu geordnet wurden. Auch glaube ich, dass mit jeder neuen FAQ-Datei, die manerstellen möchten, man diese im build-Script erwähnen muss.

Nun weiß ich, warum ich keine Beispiele zu dieser FAQ-Spezialisierung gefunden habe: sie ist nicht dokumentiert undin der Handhabung etwas umständlich.

Ditalog 1.0 | Ideen für Software-Online-Hilfen | 15






XSL-Stylesheet in der Dokumentation

Natürlich habe ich versucht, selbst XSL-Stylesheet-Anpassungen zu kreieren. Das Ergebnis: keine Fehlermeldung undkein Inhaltsverzeichnis. Bis ich in der Datei DITA-OT\xsl\xslhtml\dita2htmlImpl.xsl auf den Eintrag

<xsl:template name="gen-user-sidetoc">

stieß. Schnell danach gegoogelt und hier die Rettung in der neuen Toolkit-Dokumentation und einem XSL-Tutorialgefunden. Hier das Beispielskript vom DITA-OT:

<xsl:template name="gen-user-sidetoc"> <xsl:if test="descendant::*[contains(@class,' topic/topic ')]"><p><table width="150" align="right" border="1" frame="box" rules="none"><tr><td height="5" bgcolor="#0033CC" align="center"> <b><font color="#FFFFFF">Contents:</font></b></td></tr><xsl:for-each select="descendant::*[contains(@class,' topic/topic ')]"><xsl:variable name="ttext"><xsl:value-of select="*[contains(@class,' topic/title ')]"/></xsl:variable> <tr><td class="toc">- <a href="#{generate-id()}"><xsl:value-of select="$ttext"/></a> </td></tr></xsl:for-each></table></p></xsl:if></xsl:template>

XSL-Stylesheet individuell anpassen

Durch trial and error habe ich das Template derart angepaßt, dass immer nur in Concepts rechts oben einSeiteninhaltsverzeichnis erscheint, welches die section titles - sprich die Überschriften zu jeder Sektion - auflistet.

Abb. 10: Die Sektionsüberschriften am rechten Rand des Concepts

<xsl:template name="gen-user-sidetoc"><xsl:if test="descendant::*[contains(@class,' topic/section ')]/*[contains(@class,' topic/title ')]"><p><table class="table" width="200" align="right" border="0"><tr><td class="tablehead" align="center">Seitenübersicht</td></tr><xsl:for-each select="descendant::*[contains(@class,' topic/section ')]/*[contains(@class,' topic/title ')]"><xsl:value-of select="*[contains(@class,' topic/title ')]"/><tr><td><a href="#{generate-id()}"><xsl:value-of select="text()"/></a></td></tr></xsl:for-each></table></p>







</xsl:if></xsl:template>

Anker generieren

Es mußte noch ein Template her, um Namensanker zu erstellen.

<xsl:template name="id"><a name="{generate-id()}"/></xsl:template>

Dieses Anker-Template muss nun innerhalb des Template für die section-titles aufgerufen werden, damit in jeder sectionein Namensanker generiert wird:

<xsl:call-template name="id"/>

Stylesheet auslagern in ein Plugin

Damit die geänderte Datei dita2htmlImpl.xsl nicht beim nächsten DITA-OT-Update verloren geht, ist es ratsam,das gen-user-sidetoc-Template in ein Plugin auszulagern. Sie können das Plugin tocofsections auf der Startseitewww.ditalog.com downloaden.

Sections und ePub

Bei der Generation von ePUB-Dateien wirkt jedoch die Section-Übersicht am rechten Rand als störend. Dann ist esbesser, einfach den Plugin-Ordner herauszunehmen bzw. umzubenennten.

Zugang zum Bildschirm voranstellenEs soll der Zugang zum jeweiligen Bildschirm der eigentlichen Handlungsanweisung vorangestellt und somit extra aufgeführtwerden.

Handbuch vs. kontextsensitiver Hilfe

Es gibt zweierlei Arten des Lesens einer Online-Hilfe: linear als Buch oder per Verknüpfung aus der Anwendung. Undimmer dann, wenn letzteres geschieht, also eine Handlungsanleitung gezielt durch die kontextsensitive Hilfe geöffnetwird, bedarf es keiner Beschreibung mehr, wie man zum jeweiligen Bildschirm gelangt ist.

Dies ist nur bei Online-Hilfen relevant, jedoch kann man dies getrost auch in Handbüchern übernehmen. Der Aufwand,beim PDF-Output den Zugang zum Bildschirm in die normale Handlungsanleitung als Step zu integrieren, wäre zu hoch.Denn meistens wird man diese immerwiederkehrende Arbeitsschritte per conref-Mechanismus zentral pflegen undeinfügen.







Vorschlag einer Zugangsauszeichnung

Abb. 11: Zugangsbeschreibung zum beschriebenen Bildschirm auskoppeln

Nutzer, die durch die kontextsensitive Hilfe zum Hilfetopic geleitet wurden, können gleich mit Schritt 1 anfangen.

Zugangsweg in Online-Hilfe darstellenAnleitung: So koppeln Sie den Zugangspfad zu einem Fenster aus den Handlungsschritten aus und kennzeichnen den Zugangper ditaval-Datei.

1. Der Hinweis auf den Zugangsweg zum Fenster soll durch Flagging in der ditaval-Datei mit einem Cursor-Icongekennzeichnet werden.

Abb. 12: Cursor-Icon vorm Zugangspfad

2. Schreiben Sie dazu folgenden Eintrag in die ditaval-Datei:

<prop att="otherprops" val="zugang" action="flag"> <startflag imageref="images/icon_cursor.gif"><alt-text>So kommen Sie hin.</alt-text></startflag></prop>

Bitte achten Sie auf die Pfadangabe bei imageref. Sie muss genaus übernommen werden. Im Beispiel liegt dieditaval-Datei und das Bild in eigenen Verzeichnissen unterhalb des Output-Hauptverzeichnisses:

\filters\zugang.ditaval\images\icon_cursor.gif







3. Erstellen Sie eine Topic-Datei, in der Sie das Bild icon_cursor.gif einbinden.

4. Binden Sie diese Topic-Datei (kann auch ein Concept u.a. sein) in die ditamap-Datei ein und stellen das Attributtoc=no ein. Dieses Einbinden garantiert, dass das icon_cursor.gif rechtzeitig! in den Output-Bilderordnerkopiert wird.

5. Versehen Sie den Absatz, der den Zugangsweg beinhalten soll, mit dem Attribut otherprops="zugang". Derobige Screenshot wurde über einen Absatz im prereq-Tag realisiert:

<prereq><p id="konfigbzr" otherprops="zugang" outputclass="zugang">Klicken Sieim <wintitle>Hauptmenü</wintitle> auf<menucascade><uicontrol>Systemarbeiten</uicontrol><uicontrol>Konfiguration Module</uicontrol><uicontrol>BZR.</uicontrol></menucascade></p></prereq>

6. Weitere Überlegung sollte sein, diesen Zugangsweg nur einmal zu editieren und dann per conref-Mechanismus indie jeweilige Handlungsanleitung zu ziehen. Falls sich doch mal ein Bildschirm oder Menü ändert, brauchen Sie nurin der Originaldatei den Pfad oder ähnliches ändern und durch Content Referenzierung wird die Änderung insämtlichen Handlungsanleitungen übernommern.

7. Falls Sie wie im Beispiel um den Zugangsweg einen Rahmen ziehen möchten, vergeben Sie neben demotherprops-Attribut noch ein outputclass-Attribut und erstellen in der CSS-Datei eine Deklaration gleichenNames.












Kapitel

3HTML-Format

-Textanzeige- Es empfiehlt sich, immer ein Standard-Werk ausfallsicher nebendem Rechner zu haben: "DITA - Der neue Standard für Technische

Themen:

• Navigationsbaum mit PluginTOCJS

Dokumentation" von Johannes Hentrich mit 336 Seiten für 39,90 EUR. Vielleichtgibt es auch ein Gebrauchtexemplar. Wenn Ihnen das Ditalog gefällt, kaufenSie das Buch über Amazon hier.• DITA to Wordpress Import Tool


http://www.amazon.de/exec/obidos/ASIN/3981143000/ref=nosim/berlinpropert-21





Navigationsbaum mit Plugin TOCJSSo installieren Sie das Plugin tocjs und binden es in Ihr HTML-Projekt ein.

Über das Plugin TOCJS

Das Plugin erzeugt eine aus- und einklappbare Navigationsleiste mittels Javascript, die in den HTML-Output desDITA-OT eingebunden wird. Die Navigation wird durch den Verzeichnisbaum übersichtlicher.

Das Ditalog als HTML-Output mit ausklappbarer Navigationsleiste gibt es unter www.tocjs.ditalog.com

Installation und TestAnleitung: Original-Anleitung von Shawn McKenzie zur Installation und Integration des Plugins.

Once you have obtained the latest tocjs plugin, you need to install and integrate it into the DITA Open Toolkit

1. Obtain the latest version of the tocjs plugin. Ab DITA OT 1.5 ist dieses Plug bereits in der Auslieferung enthalten.

2. Unzip the plugin in your demo directory.This should give you a tocjs directory.

3. From your base DITA directory, type:ant -f integrator.xml.You should see output similar to the following message:

Buildfile: integrator.xml

BUILD SUCCESSFULTotal time: 1 seconds

The tocjs transtype should be registered with the Open Toolkit.

4. Type: ant -f demo/tocjs/buildsample.xml sample2tocjs.The end of the message output should say:

dita2tocjs:

BUILD SUCCESSFULTotal time: 6 seconds

5. Open demo/tocjs/out/sample/frameset.html in a browser.This documentation should be displayed in a frameset that includes a JavaScript TOC in the left pane.

DateiübersichtKonzept: Die HTML-Frameset-Dateien und Javascript-Dateien im Outputverzeichnis des Plugins TOCJS.

Output-Dateien

Nach einem erfolgreichem Build befinden sich folgende Dateien im Output-Verzeichnis:

22 | Ditalog 1.0 | HTML-Format


http://www.tocjs.ditalog.com





Abb. 13: Dateiübersicht des Outputs

toctree.js

Diese Datei ist das eigentliche Hauptprodukt des Plugins. Ist diese nicht generiert worden, ist der build fehlgeschlagen.Sie verwandelt die bisher starre HTML-Navigation in eine ausklappbare Javascript-Verzeichnisbaum-Struktur. Sie wirdim Output in die tocnav.html eingebunden und bildet mit dieser dann den linken Navigationsframe in Form einesVerzeichnisbaums.

Basefiles

Die Ordner css und img sowie die Dateien event.js, treeview.js, yahoo.js und tocnav.html sind diesogenannten Basefiles des PlugIns. Sie werden durch die build-Datei vom Plugin-Verzeichnis\demo\tocjs\basefiles in das HTML-Outputverzeichnis kopiert.

Die Datei tocnav.html im Ordner \demo\tocjs\basefiles könnten Sie eindeutschen, so dass nicht mehrExpand all und Collapse all im Navigationsbaum steht. Eine nicht sehr elegante Übersetzung wäre Ausklappen undEinklappen. Diese Datei stellt durch die Einbindung der individualisierten toctree.js den linken Navigationsframe.

frameset.html

Hinweis: Datei muss angepaßt werden!

Diese Datei ist im Output die Startdatei. Doppelklickt man diese, öffnet sich der HTML-Output korrekt mit dertocnav.html als Navigationsdatei und der entsprechend festgelegten Startdatei des Contentframes rechts. Sie wirdinnerhalb der XML-Quelldateien abgelegt und in das HTML-Outputverzeichnis kopiert (siehe dazu den Kopierbefehlin der Build-Datei). Folgende grün unterstrichenen Anpassungen bezüglich der Frames wurden vorgenommen:

Abb. 14: Frames in der frameset.html

Ditalog 1.0 | HTML-Format | 23






index.html

Diese Datei ist das konventionelle Ergebnis der XHTML-Output-Generierung - und ein Zwischenschritt auf dem Wegzum Javascript-Verzeichnisbaum. Sie ist die alte starre HTML-Navigationsdatei, wie sie ohne das Plugin tocjs generiertwurde.

Verzeichnisse des HTML-Contents

Die Ordner topics und images sind hier im Beispiel die normalen Ergebnis-Dateien des XHTML-Outputs, wie erweiterhin im rechten Content-Frame zur Anzeige kommt.

Build-Datei anpassenKonzept: Beispiel einer Build-Datei für das Plugin TOCJS.

DITA-Verzeichnisstruktur

Zum Verstehen der Build-Datei ist es nützlich, die DITA-Verzeichnisstruktur, wie sie im Beispiel genutzt wurde, zukennen.

Abb. 15: Quelldateien parallel zu DITA-OT

Es wurden (08/2009) noch beide DITA-OT-Versionen genutzt, da das 1.5er noch keine Stichwörter (Index) imPDF2-Output generierte. Die Quelldateien wurden in einem Extraverzeichnis ausgelagert, damit sie schneller gesichertwerden können. Diese Struktur ist nicht zwingend, soll aber das Beispiel der build-Datei illustrieren.

Die build-Datei

Für den tocjs-Output wurde die bereits vorhandene XHTML-Build-Datei angepaßt. Das alte HTML-Output-Verzeichnisblieb dasselbe. Die grauen Zeilen kennzeichnen die neu hinzugekommenen TOCJS-Anpassungen. Der Übersicht wegenwurde auf die Notation ${file.separator} verzichtet.

<?xml version="1.0" encoding="iso-8859-1"?><project basedir="..\.." default="all" name="Administrator Dokumentation"><property name="dita.dir" value="C:\DITA-OT1.5"/><import file="${dita.dir}\integrator.xml"/>







<import file="${dita.dir}\build.xml" />

<target name="all" depends="integrate" ><ant antfile="${dita.dir}\build.xml" target="init"><property name="args.logdir" value="C:\DITA-SRC\log" /><property name="args.input" value="C:\DITA-SRC\ditalog.ditamap" /><property name="output.dir" value="C:\DITA-SRC\out\html-admin" /><property name="transtype" value="xhtml" /><property name="args.css" value="C:\DITA-SRC\css\ditalog.css" /><property name="args.csspath" value="css" /><property name="args.dita.locale" value="de-de" /><property name="args.copycss" value="yes" /><property name="args.hdr" value="C:\DITA-SRC\includes\header.xml" /><property name="args.ftr" value="C:\DITA-SRC\includes\footer.xml" /><property name="args.xsl" value="${dita.dir}\xsl\dita2xhtml.xsl" /><property name="dita.input.valfile" value="C:\DITA-SRC\filters\ditalog.ditaval" /><property name="validate" value="true" /></ant>

Hier wird die angepaßte frameset.html, die im Quellordner \includes liegt, in das HTML-Output-Verzeichniskopiert:

<copy todir="C:\DITA-SRC\out\html-admin"><fileset dir="C:\DITA-SRC\includes"><include name="frameset.html" /></fileset></copy>

Hier werden sämtliche Bilddateien in das HTML-Output-Verzeichnis kopiert:

<copy todir="C:\DITA-SRC\out\html-admin\images"><fileset dir="C:\DITA-SRC\images"><include name="**/*.gif" /></fileset></copy>

</target>

Es folgt die eigentliche Anpassung für das Javascript-Menü. Die Datei toctree.js wird nach der Generierung insHTML-Output-Hauptverzeichnis abgelegt. Innerhalb des Copy-Befehls werden sämtliche Basefiles des Plugins aus demOrdner \demo\tocjs\basesfiles in das HTML-Output-Hauptverzeichnis kopiert.

<target name="sample2tocjs" description="Generate tocjs javascript file" depends="all"><property name="content.frame" value="contentwin"/><antcall target="dita2tocjs"><param name="transtype" value="tocjs"/><param name="args.input" value="C:\DITA-SRC\ditalog.ditamap"/><param name="output.file" value="C:\DITA-SRC\out\html-admin\toctree.js"/></antcall><copy todir="C:\DITA-SRC\out\html-admin"><fileset dir="${dita.dir}\demo\tocjs\basefiles"><include name="**/*"/></fileset></target>

</project>

Javascript-Navigation generierenAnleitung: So generieren Sie HTML-Output mit Javascript-Navigation.

Das Plugin wurde ins DITA-OT integriert, die frameset.html und die build-Datei wurden angepaßt!

1. Doppelklicken Sie im Toolkit-Verzeichnis auf die Datei startcmd.bat.







2. Im Beispiel heißt die build-Datei admin-html.xml. Der Ant-Befehl mit dem tocjs-Target lautet dementsprechend:

ant -f C:\DITA-SRC\build\admin-html.xml sample2tocjs

3. Die Meldung über einen erfolgreichen Build kommt mit vielen Rauten daher. Nur diese Meldung gibt Ihnen Gewißheit,dass der Build geklappt hat.

Abb. 16: Build succesful

4. Diese Dateien wurden im HTML-Output-Verzeichnis generiert. Öffnen Sie die frameset.html im Browser.

Abb. 17: toctree.js innerhalb der tocnav.html

5. Sollten im Navigationsbaum die deutschen Umlaute falsch dargestellt werden, muß die DateiC:\DITA-OT1.5\demo\tocjs\xsl\tocjs.xsl angepaßt werden. Bei Output Method muss stehen:<xsl:output method="text" encoding="ISO-8859-1"/>.

DITA to Wordpress Import ToolXHTML-Output per DITA zu Wordpress Importer importieren.

DITA to Wordpress Import Tool installieren und anwendenAnleitung: So installlieren Sie das Importtool in Ihrer Wordpress-Installation.







Hinweis: Es empfiehlt sich, zumindestens die HTML-Dateien, die das Ergebnis eines DITA-Builds sind, zuvoranzupassen.

1. Downloaden Sie die Datei dita-help-importer.zip unterhttp://zed1.com/journalized/wordpress-plugins/dita-to-wordpress-import-tool/.

2. Editieren Sie die entpackte Datei ditahelp.php in einem Texteditor in Zeile 493: $img->setAttribute('src', '/'.$src); In der Originalversion fehlt ein Slash zur korrekten Angabe desBildpfades: $img-> setAttribute('src', $src)

3. Laden Sie die entpackte Datei ditahelp.php per FTP in den Wordpress-Ordner \wp-admin\import hoch.

4. Laden Sie Ihren DITA-XHTML-Output per FTP in den Wordpress-Ordner hoch. Bspw. nach\wp-conten\dita-html-output.

5. Melden Sie sich im Wordpress-Dashboard an und aktivieren Sie das Seiten-Widget, so dass statische Seiten angezeigtwerden können.

6. Klicken Sie im Dashboard auf Werkzeuge ➤ Daten importen ➤ DITA Help.

7. Tragen Sie im Feld DITA Help Directory den genauen Pfad zum Verzeichnis des DITA-XHTML-Outputs ein undklicken Sie auf Import Files.

Abb. 18: XHTML-Verzeichnis festlegen

8. Klicken Sie auf Stage 2.


10. Klicken Sie auf Next 75.



http://zed1.com/journalized/wordpress-plugins/dita-to-wordpress-import-tool/





Abb. 19: Dateiimport



13. Das wars. Ein Klick auf Viel Spass führt Sie zum gefüllten Blog.

Abb. 20: Import beendet

Anpassungen vornehmenAnleitung: So nehmen Sie nötige Mindestanpassungen im Layout vor.

1. Das Importer-Tool nutzt zwar den XHTML-Output, jedoch ist es ratsam, sich eine eigene build-Datei für denWordpress-Gebrauch zu erstellen. So war es mir lieber, nicht die header- und footer.xml im XHTM:-Outputzu haben. Die beiden Dateien habe ich in der neuen build-Datei weggelassen. Auch ein Extra-Output-Verzeichnishabe angelegt, da ich auch ein normales XHTML-Verzeichnis mit Footer etc benötige.

2. Da dass Tool externe Links abschneidet, habe ich mit einer Ditaval-Datei die related-links herausgefiltert. Aber auchandere Elemente waren für Wordpress ungeeignet. Der Tag sah mit Attribut dann so aus: <related-linksproduct="wordpress">. Die entsprechende Ditaval-Datei, die auch in der obigen neuen Wordpress-build-Dateihinterlegt wurde, bekam folgenden Eintrag:<prop action="exclude" att="product" val="wordpress" />

3. Es fehlen dem Wordpress-Layout einige CSS-Deklarationen. Diese müssen von der Dateidita\resource\commonltr.css in eine Wordpress-CSS-Datei übertragen werden. In meinem Fall war istes die style.css meines aktuellen Wordpress-Templates. Hier im einzelnen: pre.screen undspan.filepath.

4. Es fehlen ebenso Deklarationen aus der Datei dita\css\domains.css, so dass meine style.css zum Endefolgendermaßen aussieht:

pre.screen { padding: 5px 5px 5px 5px; border: outset; background-color: #CCCCCC;}span.filepath { font-family:monospace; font-size:1.2em;}.msgph { display: inline; font-family:monospace; font-size:1.2em;}.userinput { display: inline; font-family:monospace; font-size:1.2em;}.systemoutput { display: inline; font-family:monospace; font-size:1.2em;}.wintitle { display: inline; font-weight: normal; font-style: italic;}







.menucascade { display: inline; font-style: italic;}

.uicontrol { display: inline; font-style: italic;}

.stepexpand { margin-bottom : 10px; }

5. Nachbereitung im Wordpress-Dashboard: ich habe die Unterseiten der 3. Ebene ausgeblendet. Dazu müssen Sie imSeiten-Widget einfach die ID-Nummern jener Seiten getrennt mit Komma eingeben, die Sie ausgeblendet habenmöchten.

6. Der Tag <menucascade> muss nachbereitet werden: es werden immer <br>-Tags eingefügt. Diese gilt es zulöschen.












Kapitel

4CHM-Format

-Textanzeige- Es empfiehlt sich, immer ein Standard-Werk ausfallsicher nebendem Rechner zu haben: "DITA - Der neue Standard für Technische

Themen:

• Umlaute im Inhaltsverzeichnis Dokumentation" von Johannes Hentrich mit 336 Seiten für 39,90 EUR. Vielleicht• Symbolschaltflächen hinzufügen gibt es auch ein Gebrauchtexemplar. Wenn Ihnen das Ditalog gefällt, kaufen

Sie das Buch über Amazon hier.


http://www.amazon.de/exec/obidos/ASIN/3981143000/ref=nosim/berlinpropert-21





Umlaute im InhaltsverzeichnisAnleitung: So stellen Sie deutsche Umlaute im Inhaltsverzeichnis der CHM-Datei richtig dar.

Hinweis: Dies tritt insbesondere beim DITA-OT 1.5 auf!

1. Editieren Sie die Datei C:\DITA-OT1.5\xsl\map2hhc.xsl folgendermaßen:

Abb. 21: encoding-Attribut hinzufügen

2. Fügen Sie wie im Bild angeben beim xsl:output das Attribut encoding="ISO-8859-1" hinzu.

Symbolschaltflächen hinzufügenEs sollen neue Schaltflächen in der CHM-Hilfe hinzukommen.

Standard-Schaltflächen

Eine Standard-Schaltflächenleiste im CHM-Standard-Output sieht folgendermaßen aus:

Abb. 22: Nur 4 Schaltflächen im CHM-Output

Neue Schaltflächen hinzufügen

Es sollen einige Schaltflächen hinzukommen:

32 | Ditalog 1.0 | CHM-Format






Abb. 23: Weitere Schaltflächen hinzufügen

Besonders wichtig erscheinen mir hier die Navigationsschaltflächen.

• Vorherige - Vorheriges Topic im Inhaltsverzeichnis. Im Beispiel also nach oben auf Nachrichtentelegramm.• Nächstes - Nächstes Topic nach unten im Inhaltsverzeichnis.• Zurück - Zum zuvor geöffneten Topic in der Historie.• Vorwärts - Zum danach geöffneten Topic in der Historie.

Die beiden Schaltflächen, die stur das Inhaltsverzeichnis rauf und runter navigieren, benötigen als Vorraussetzung denEintrag Binary TOC=Yes. Dieser Eintrag steht in der HTML-Workshop-Projekt-Datei Dateiname.hhp. EntwederSie editieren dies direkt im Editor oder nutzen dafür die Oberfläche des HTML-Workshops.

Einen kleinen Nachteil hat jedoch der Einsatz der Inhaltsnavigation. Es sind nun keine individuellen oder erweitertenIcons für das Inhaltsverzeichnis mehr möglich. Es können nur noch die Standard-Icons Buch und Seite eingesetzt werden.

HTML-Workshop erlaubt den Einsatz von 2 individuellen Schaltflächen, die zur einer Inhaltsseite Ihrer Wahl verlinktwerden kann. Im Beispiel verlinkt die Schaltfläche Was ist neu zu einer Seite, die die Neuerungen in der Software alsauch in der Online-Hilfe aufzeigt.

Die Projektdatei .hhp

Es mussten einige Einträge in die Projektdatei geschrieben werden. Im Bereich [OPTIONS] kamen hinzu:

Binary TOC=YesDefault Window=main

Zwischen OPTIONS und FILES wurde ein weiterer Bereich eingefügt: [WINDOWS]. Dem folgt eine lange Zeile. Wiediese Zeile zustande kommt, ist in vielen HTML-Workshop-Internetseiten gut dokumentiert. Ein guter Weg wäre esauch, die Schaltflächen in der Oberfläche des HTML-Workshops hinzufügen und das Ergebnis in der Datei .hhpanschließend zu betrachten und als Grundlage für das DITA-xsl-Stylesheet zu nehmen. Hier der Windows-Bereich zumobigen Screenshot.

[WINDOWS]main=,"Dokupedia.hhc","Dokupedia.hhk","topics/common/a0_start_NAV_startseite.html","topics\common\a0_start_NAV_startseite.html","topics\common\wasistneu\wasistneu_startseite_con.html","Was ist neu?",,,0x3520,,0x64204e,,,,,,,,0

Man beachte jedoch, dass nach dem Wort main alles in einer Zeile geschrieben sein muss!

Das Stylesheet map2hhp.xsl

Damit die Individualisierung der CHM-Datei automatisch bei jedem build aus dem DITA-OT generiert wird, müssendie Neuerungen der Projektdatei in das für die Projektdatei verantwortliche XSL-Stylesheet geschrieben werden. Diesist die Datei map2hhp.xsl im XSL-Ordner der Toolkit-Installation. An 2 Stellen erfolgt die Anpassung im Stylesheet.Diese sind jeweils grün gefärbt.

Ditalog 1.0 | CHM-Format | 33






Abb. 24: Options-Einträge

Abb. 25: Windows-Einträge

Nachteil der Hartkodierung

Sobald man obige Windows-Einträge in die DITA-XSL-Datei hartkodiert, provoziert man bei anderen Projekten anderenNamens unweigerlich eine Fehlermeldung. Vielleicht wäre eine Plugin-Lösung besser?

34 | Ditalog 1.0 | CHM-Format






Kapitel

5AIR Help-Format

Themen:

• AIR-Help-Plugin installieren• Auto-Update einrichten• Umlaute im Inhaltsverzeichnis

und Index






AIR-Help-Plugin installierenInstallation und Konfiguration des Plugins LMI AIR Help 0.06

Leximation AIR Help Plugin installierenAnleitung: So installieren und testen Sie das AIR Help Plugin.

DITA OT 1.5

Hinweis: Da das Plugin noch nicht offiziell veröffentlich wurde, informieren Sie sich bitte unterwww.leximation.com/airhelp über den Erwerb des Plugins.

1. Entpacken Sie die ZIP-Datei lmi-airhelp.VERSION.zip in den Ordner DITA-OT/demo. Als Ergebis entstehtein Ordner lmi-airhelp.

2. Falls Sie schon Flex Builder installiert haben, machen Sie mit dem nächsten Schritt weiter. Falls nicht, laden Siebitte folgende Komponenten herunter und installieren Sie diese:

• Adobe Flex SDK (http://www.adobe.com/cfusion/entitlement/index.cfm?e=flex3sdk)• Adobe AIR SDK (http://www.adobe.com/products/air/tools/sdk/)

3. Editieren Sie die Datei C:\DITA-OT1.5\demo\lmi-airhelp\airhelp.properties. Tätigen Sie diePfadangaben für die soeben entpackten Komponenten. Dies kann bspw. so aussehen:

FLEX.SDK_HOME = C:/Programme/Adobe/flex_sdk_3-4AIR.SDK_HOME = C:/Programme/Adobe/air_sdk

4. Fügen Sie die Datei lmi-airhelp.jar Ihrem Classpath hinzu. Unter Windows unter Startschaltfläche ➤

Systemsteuerung ➤ System ➤ Registerkarte Erweitert ➤ SF Umgebungsvariablen

C:\DITA-OT1.5\demo\lmi-airhelp\lmi-airhelp.jar;

5. Melden Sie sich am Betriebssystem wieder neu an bzw. starten Sie Ihren Rechner neu.

6. Doppelklicken Sie die startcmd.bat und setzen Sie folgenden Befehl ab:

ant -f integrator.xml

7. Kopieren Sie die die Datei sample_airhelp.xml in den Ordner C:\DITA-OT1.5\samples\ant_sample.

8. Starten Sie den Build der Beispieldateien per:

ant -f samples/ant_sample/sample_airhelp.xml

9. Angenommen der Build war erfolgreich, ist unter C:\DITA-OT1.5\samples\ant_sample\out\ ein neuerOrdner airhelp entstanden. Doppelklicken Sie auf die darin liegende Datei airhelp-test.bat, um dieBeispiel-AIR-Help zu generieren. Diese Hilfe kann noch nicht als air-Datei abgespeichert werden.

36 | Ditalog 1.0 | AIR Help-Format






Abb. 26: AIR Help mit Beispiel-Dateien

AIR-Datei erstellenAnleitung: So erstellen Sie eine AIR Help Datei, welche Sie weitergeben können.

1. Um AIR-Dateien zu erstellen, die weitergegeben werden können, bedarf es der Generierung einer Zertifikatsdatei.Einem sogenannten self-signed certificate.

2. Öffnen Sie im bin-Verzeichnis des AIR SDK ein Kommandofenster und setzen den Befehl für die Generierungeiner p12-Zertifikatsdatei ab. Ersetzen Sie die Angaben in Großbuchstaben durch eigene Werte entsprechend.

adt -certificate -cn ZERTIFIKATSNAME 1024-RSA DATEINAME.p12 PASSWORT

3. Im bin-Verzeichnis des AIR SDK wurde eine Zertifikatsdatei DATEINAME.p12 generiert. Kopieren Sie diese inden Ordner C:\DITA-OT1.5\samples\ant_sample\out\airhelp

4. Öffnen Sie die Datei airhelp-packager.bat im Texteditor und ändern die Werte für DATEINAME.p12 undPASSWORT. Vergessen Sie auf keinen Fall den Eintrag -tsa none. Ohne diesen bekommen Sie eine FehlermeldungCould not generate timestamp: Connection refused: connect.

CALL "C:/Programme/Adobe/air_sdk/bin/adt" -package -storetype pkcs12 -keystore "DATEINAME.p12"-tsa none -storepass PASSWORT hierarchy.air airhelp-app.xml airhelp.swf help/*

5. Doppelklicken Sie die Datei airhelp-packager.bat. Im Ergebnis ensteht eine Datei hierarchy.air. Sobald einNutzer die Adobe AIR SDK installiert hat, kann er auf die air-Datei doppelklicken und als AIR-Anwendunginstallieren. Die AIR-Anwendungen sind als Link unter Start ➤ Programme zu finden.

Ditalog 1.0 | AIR Help-Format | 37






Abb. 27: AIR Installer Package doppelklicken

Build-Datei anpassenDie Datei sample_airhelp.xml anpassen.

Ant-Befehl

Da ich Quelldateien außerhalb des DITA-OT-Ordners in einem Ordner C:\DITA-SRC abspeichere, lautet der Ant-Befehlzum Generieren der AIR-Help-Dateien folgendermaßen:

ant -f C:\DITA-SRC\build\ditalog-airhelp.xml -logger org.dita.dost.log.DITAOTBuildLogger

Build-Datei

Da ich meine individuelle CSS-Datei nutzen und eine Log-Datei generiert haben möchte, habe ich dersample_airhelp.xml zwei property-Elemente hinzugefügt und als ditalog-airhelp.xml abgespeichert.

<project name="sample_airhelp" default="sample2lmi-airhelp" basedir="."><property name="dita.dir" value="C:/DITA-OT1.5"/><import file="${dita.dir}/integrator.xml"/>

<target name="sample2lmi-airhelp" depends="integrate"> <ant antfile="${dita.dir}/build.xml" target="init"> <property name="args.logdir" value="C:/DITA-SRC/log" /> <property name="args.css" value="C:/DITA-SRC/css/ditalog.css" /> <property name="args.copycss" value="yes" /> <property name="args.input" value="C:/DITA-SRC/ditalog.ditamap"/> <property name="output.dir" value="C:/DITA-SRC/out/air-ditalog/help"/> <property name="transtype" value="lmi-airhelp"/> </ant>







</target></project>

Version und Copyright festlegenAnleitung - So befüllen Sie automatisch die Datei airhelp.ahp mit Versionsnummer und Copyright-Angaben.

Damit die Angaben der Outputdatei airhelp.ahp automatisch aus den DITA-Quelldateien gefüllt werden, ist eswichtig, innerhalb der Haupt-Ditamap im letzten topicref-Eintrag ein topicmeta-Abschnitt einzufügen. Diesengilt es entsprechend zu füllen.

<topicref href="topics/common/impressum_con.xml" id="impressum_con" scope="local" type="concept" xml:lang="de-de"><topicmeta><copyright><copyryear year="2009"/><copyrholder>ditalog.com</copyrholder></copyright><prodinfo><prodname>ditalog</prodname><vrmlist><vrm version="0.2"/></vrmlist></prodinfo></topicmeta></topicref>

Hinweis: Ohne diese Angaben funktioniert auch der Auto-Update-Mechanismus nicht!

Auto-Update einrichtenAnleitung - So richten Sie die Suche nach einem Update ein.

LMI Airhelp 0.06 als Plugin-Version. Ebenso muss in der Hauptditamap die Prodinfo-Versionsnummer hinterlegt sein.

1. Nachdem Sie alle inhaltlichen Änderungen vorgenommen haben, nehmen Sie im letzten topicref-Element derHaupt-Ditamap den topicmeta-Eintrag für die Versionsnummer vor. Hier speziell vrm version.

<topicref href="topics/common/impressum_con.xml" id="impressum_con" scope="local" type="concept" xml:lang="de-de"><topicmeta><copyright><copyryear year="2009"/><copyrholder>ditalog.com</copyrholder></copyright><prodinfo><prodname>ditalog</prodname><vrmlist><vrm version="0.2"/></vrmlist></prodinfo></topicmeta></topicref>

Im Beispiel ist die 0.2 die neue Versionsnummer. In der derzeitigen AIR-Applikation ist demzufolge noch dieVersionsnummer 0.1 hinterlegt. Erst dieser Unterschied läßt das Adobe Update Framework verkünden, dass eineneue Version zum Download bereitsteht.

2. Erstellen Sie eine Update-Beschreibungsdatei (update descriptor file).

<?xml version="1.0" encoding="utf-8"?><update xmlns="http://ns.adobe.com/air/framework/update/description/1.0"><version>0.2</version><url>http://example.com/updates/ditalog_0.2.air</url>







<description>Hier kommt Ihr kurzer Erläuterungstext.</description></update>

Die Einträge für version und url sind obligatorisch. Speichern Sie diese Datei unter dem Namen update.xmllokal ab.

3. Öffnen Sie die Datei \demo\lmi-airhelp\app\common.as und tragen Sie den Wert für die VariablegAppUpdateUrl ein. Dies ist die URL der Update-Beschreibungsdatei.static public var gAppUpdateUrl:String ="http://example.com/updates/update.xml";

4. Starten Sie das Airhelp-Plugin. Im Output-Ordner generieren Sie anschließend mit Hilfe der Dateiairhelp-packager.bat die Air-Datei.

5. Kopieren Sie die Update-Beschreibungsdatei und die soeben erstellte Air-Datei auf den Download-Server. Diehinterlegte Domain bei beiden Dateien muß funktionieren! Testen Sie dies, in dem Sie die URL derUpdate-Beschreibungsdatei im Browser eingeben.

6. Starten Sie die alte, noch installierte AIR-Applikation und klicken Sie auf die Update-Schaltfläche. Im Plugin 0.06ist diese mit der Versionsnummer versehen. Folgendes Fenster erscheint, wenn ein Update verfügbar ist.

Abb. 28: Update manuell auslösen

Abb. 29: Installation starten







Umlaute im Inhaltsverzeichnis und IndexAnleitung: So stellen Sie deutsche Umlaute im Inhaltsverzeichnis und Stichwortverzeichnis richtig dar.

Hinweis: Für die deutschen Umlaute ist noch manuelle Nacharbeit geboten. Für die Suchergebnisse im Search-Tabkonnte ich noch keine Lösung finden.

1. Editieren Sie die Datei C:\DITA-OT1.5\demo\lmi-airhelp\xsl\map2ahtoc.xsl folgendermaßen:Fügen Sie beim xsl:output das Attribut encoding="ISO-8859-1" hinzu.

2. Editieren Sie die Datei C:\DITA-OT1.5\demo\lmi-airhelp\xsl\map2ahp.xsl in der gleichen Weise:Fügen Sie beim xsl:output das Attribut encoding="ISO-8859-1" hinzu.

3. Setzen Sie den Build-Befehl für die AIR-Help-Generierung ab. Im Outputverzeichnis ändern Sie danach die DateiDATEINAME.ahix in der ersten Zeile von UTF-8 in ISO-8859-1.












Kapitel

6PDF-Format

Themen:

• Inhaltsverzeichnis Print vs. Online• Texteinrückung mit hängender

erster Zeile• xref-Direktlinks in Onlinehilfe vs.

Print• Zugang zum Bildschirm

voranstellen• Zugangsweg im PDF-Output

darstellen• Leere Seiten aus der PDF-Datei

entfernen.• Paragraphensymbol § im

indexterm






Inhaltsverzeichnis Print vs. OnlineUnterschiede zwischen Print- und Online-Inhaltsverzeichnis.

1:1-Übertragung des Online-Verzeichnisses?

Meistens ist immer die Online-Hilfe das erst Output-Ergebnis und man macht sich daran, die Haupt-Ditamap als Grundlagefür eine Bookmap für den PDF-Output zu nehmen. So sah dann mein erstes Ergebnis des PDF-Inhaltsverzeichnisses soaus:

Spätestens jetzt muss man sich Gedanken machen, ob eine 1:1-Kopie des Online-Verzeichnisses für den PDF-Outputgeeignet ist. Hier im Beispiel des ditalogs liegt es nahe, die verschiedenen Ausgabeformate auch unter einem StichwortAusgabeformate zu sammeln. Doch ist dies nicht das, was dem Leser in einem Druckdokument weiterhilft. Hier wärees besser, den einzelnen Ausgabeformaten ein eigenes Kapitel zu widmen. Man erspart sich die dritte Ebene imInhaltsverzeichnis und der Leser erhält einen schnelleren Überblick. Und Überblick steht bei einem Printinhaltsverzeichnisim Vordergrund. Wer wirklich etwas Spezielles sucht, muss über das Stichwortverzeichnis gehen.

Abb. 30: Erster Output im PDF-Format

Besondere Gestaltung der bookmap

Die Bookmap bedarf also meistens eine Überarbeitung und sieht im Ergebnis anders als die Online-ditamap aus.

44 | Ditalog 1.0 | PDF-Format






Abb. 31: Neue Anordnung

Egal, wie man die bookmap neu anordnet - man wird sie immer flexibel den Bedürfnissen des Lesers (nicht Nutzers)anpassen müssen.

Texteinrückung mit hängender erster ZeileAnleitung: So erstellen Sie einen Literaturverzeichniseintrag mit hängender 1. Zeile.

Hinweis: Der PDF-Output wird mit Hilfe des Idiom-FO-Plugins realisiert.

1. Für ein Literaturverzeichnis sollen die Absätze pro Eintrag eingerückt werden mit der ersten Zeile hängend.

Abb. 32: Hängende erste Zeile

2. Fügen Sie in der Datei custom.xsl im Ordner \demo\fo\Customization\fo\xsl folgenden Eintrag fürein Template hinzu:

<xsl:template match="*[contains(@class, ' topic/p ')]"><xsl:choose><xsl:when test="@otherprops='indent'"><fo:block text-indent="-2em" start-indent="4.5em"><xsl:apply-templates/></fo:block></xsl:when><xsl:otherwise><fo:block xsl:use-attribute-sets="p" id="{@id}"><xsl:apply-templates/></fo:block>

Ditalog 1.0 | PDF-Format | 45






</xsl:otherwise></xsl:choose></xsl:template>

Neu ist hier die when-Anweisung. Die otherwise-Anweisung ist das normale Template für einen Absatz. Fürindent können Sie eigene Entsprechungen finden. Es soll hier nur als Beispiel dienen.

3. Versehen Sie sämtliche Absätze, die Quellenangaben enthalten sollen, mit dem Attribut otherprops="indent".

<p otherprops="indent" outputclass="indent">Erich Loest: Es geht seinen Gang oder Mühen in unserer Ebene. München 1994 (dtv 10430)</p>

4. Falls Sie die Texteinrückung auch in XHTML-Output haben möchten, vergeben Sie wie oben ein Attributoutputclass="indent". Erstellen Sie anschließend in der CSS-Datei eine Deklaration gleichen Namens miteinem Eintrag für text-indent.

xref-Direktlinks in Onlinehilfe vs. PrintHilfreiche xref-Links in der Onlinehilfe sollen im PDF-Output ausgeblendet werden.

Direktlinks

Manchmal möchte man auf xref-Links einfach nicht verzichten, denn in der Online-Hilfe erfüllen sie ihren Zweck, derauch durch sogenannte related links am Ende des Artikels nicht ersetzt werden kann. Hier der pure xref-Link und dasErscheinungsbild im Output.

<p>Für eine Entscheidung bedarf es neben den <xref href="stammdaten-pflichtfelder_ref.xml"> generellen Pflichtfeldern</xref> noch folgender drei Vorraussetzungen, damit sie ans EStA gesendet werden können:</p>

Abb. 33: Online ein nützlicher Link zum Term "generelle Pflichtfelder"

Abb. 34: Im PDF erscheint der Link mit Topic-Titel

Während man mit der jeweilige Seiteangabe noch leben könnte, erscheint der Linktext nicht mehr. Statt dessen kommtder Topic-Titel der referenzierten Seite zur Ausgabe, was immer grammatikalische Ungeheuer entstehen läßt.







Direktlinks pro Ausgabeformat differenzen

Es soll der nützliche Online-Link erhalten bleiben, der Link innerhalb der PDF-Datei jedoch verschwinden. In derditaval-Datei müssen - sofern sie nicht schon existieren - zwei Produktattribute geschaffen werden.

<prop action="exclude" att="product" val="print" /><prop action="include" att="product" val="online" />

Nun können in der jeweiligen Topic-XML-Datei zwei Einträge für den Term generellen Pflichtfeldern vorgenommenwerden. Beide bekommen ein anderes Produkt-Attribut.

<p>Für eine Entscheidung bedarf es neben den<xref href="stammdaten-pflichtfelder_ref.xml" product="online">generellen Pflichtfeldern</xref><keyword product="print">generellen Pflichtfeldern</keyword>noch folgender drei Vorraussetzungen, damit sie ans EStA gesendet werden können:</p>

Die Online-Verlinkung bleibt erhalten, wogegen im PDF der Link verschwindet.

Abb. 35: Term ohne Link

Zugang zum Bildschirm voranstellenEs soll der Zugang zum jeweiligen Bildschirm der eigentlichen Handlungsanweisung vorangestellt und somit extra aufgeführtwerden.

Handbuch vs. kontextsensitiver Hilfe

Es gibt zweierlei Arten des Lesens einer Online-Hilfe: linear als Buch oder per Verknüpfung aus der Anwendung. Undimmer dann, wenn letzteres geschieht, also eine Handlungsanleitung gezielt durch die kontextsensitive Hilfe geöffnetwird, bedarf es keiner Beschreibung mehr, wie man zum jeweiligen Bildschirm gelangt ist.

Dies ist nur bei Online-Hilfen relevant, jedoch kann man dies getrost auch in Handbüchern übernehmen. Der Aufwand,beim PDF-Output den Zugang zum Bildschirm in die normale Handlungsanleitung als Step zu integrieren, wäre zu hoch.Denn meistens wird man diese immerwiederkehrende Arbeitsschritte per conref-Mechanismus zentral pflegen undeinfügen.







Vorschlag einer Zugangsauszeichnung

Abb. 36: Zugangsbeschreibung zum beschriebenen Bildschirm auskoppeln

Nutzer, die durch die kontextsensitive Hilfe zum Hilfetopic geleitet wurden, können gleich mit Schritt 1 anfangen.

Zugangsweg im PDF-Output darstellenAnleitung: So koppeln Sie den Zugangspfad zu einem Fenster aus den Handlungsschritten aus und ändern entsprechend dasXSL-Stylesheet.

Hinweis: Der PDF-Output wird mit Hilfe des Idiom-FO-Plugins realisiert.

1. Der Hinweis auf den Zugangsweg zum Bildschirm soll mit einem Cursor-Icon und dem Wort Zugang: gekennzeichnetwerden.

Abb. 37: Cursor-Icon vorm Zugangspfad

2. Kopieren Sie das Bild, mit welchem Sie den Zugangspfad "flaggen" möchten, in den Idiom-FO-Plugin-OrdnerC:\DITA-OT1.4.2.1\demo\fo\Customization\common\artwork

3. Fügen Sie in der Datei custom.xsl im Ordner \demo\fo\Customization\fo\attr\custom.xslfolgendes Attributset hinzu:

<xsl:attribute-set name="p.zugang"><xsl:attribute name="font-weight">bold</xsl:attribute></xsl:attribute-set>







4. Fügen Sie in der Datei custom.xsl im Ordner \demo\fo\Customization\fo\xsl folgenden Eintrag fürein Template hinzu:

<xsl:template match="*[contains(@class, ' topic/p ')]"><xsl:choose><xsl:when test="@otherprops='zugang'"><fo:block space-before="0.5em"><fo:inline><fo:external-graphic src="url({concat($artworkPrefix, '/Customization/OpenTopic/common/artwork/icon_cursor.gif')})"/></fo:inline><fo:inline xsl:use-attribute-sets="p.zugang"><xsl:text> Zugang: </xsl:text></fo:inline><xsl:apply-templates/></fo:block></xsl:when><xsl:otherwise><fo:block xsl:use-attribute-sets="p" id="{@id}"><xsl:apply-templates/></fo:block></xsl:otherwise></xsl:choose></xsl:template>

Neu ist hier die when-Anweisung. Die otherwise-Anweisung ist das normale Template für einen Absatz.

5. Versehen Sie den Absatz, der den Zugangsweg beinhalten soll, mit dem Attribut otherprops="zugang". Derobige Screenshot wurde über einen Absatz im prereq-Tag realisiert:

<prereq><p id="konfigbzr" otherprops="zugang" outputclass="zugang">Klicken Sieim <wintitle>Hauptmenü</wintitle> auf<menucascade><uicontrol>Systemarbeiten</uicontrol><uicontrol>Konfiguration Module</uicontrol><uicontrol>BZR.</uicontrol></menucascade></p></prereq>

6. Weitere Überlegung sollte sein, diesen Zugangsweg nur einmal zu editieren und dann per conref-Mechanismus indie jeweilige Handlungsanleitung zu ziehen. Falls sich doch mal ein Bildschirm oder Menü ändert, brauchen Sie nurin der Originaldatei den Pfad oder ähnliches ändern und durch Content Referenzierung wird die Änderung insämtlichen Handlungsanleitungen übernommern.

7. Falls Sie wie im Beispiel um den Zugangsweg einen Rahmen ziehen möchten, vergeben Sie neben demotherprops-Attribut noch ein outputclass-Attribut und erstellen in der CSS-Datei eine Deklaration gleichenNames.

Leere Seiten aus der PDF-Datei entfernen.Leere oder nicht benötigte Seiten sollen aus der PDF-Datei entfernt werden.

Problem der nicht benötigten Seiten

Als PDF-Ergebnis erhält man, auch ohne eine bookmap zu nutzen, eine PDF-Datei mit Deckblatt und Inhaltsverzeichnis.Möchte man jedoch nur eine A4-Seite für eine kleine Änderungsliste oder ähnliches erstellen, wirkt ein Deckblatt undein Inhaltsverzeichnis mit nur einem Eintrag deplatziert.

Desweiteren enstehen oftmals leere Seiten, die nur im beidseitigem Druck einen Sinn ergeben. Der PDF-Ausdruckgeschieht jedoch meistens für den einseitigen Ausdruck, worin die leeren Seiten als störend empfunden werden.

Es gibt mehrere Gründe, Seiten aus der PDF-Datei zu entfernen.







Links in PDF-Datei

Bisher habe ich mich damit begnügt, die PDF-Datei aufzurufen und nur die Seiten, die ich benötigte, über einenPDF-Druckertreiber auszudrucken. Jedoch verschwand damit die Linkfähigkeit:

Abb. 38: Link funktioniert auch im PDF-Output

Tool PDFsam

Das kleine Tool PDFsam bewältigt zwei Probleme: Seiten entfernen und Linkfähigkeit der PDF-Datei erhalten.

Abb. 39: Teilen und wieder zusammenführen

Das Prinzip des Programm ist es, Dateien zu zerteilen, die leeren und unbrauchbaren Seiten zu löschen und nur diebeschriebenen, wichtigen Seiten wieder zu einer PDF-Datei zusammenzuführen. Im Beispiel wird nach Seite 2 getrennt,weil die ersten beiden Seiten das nicht benötigte Deckblatt und das Inhaltsverzeichnis darstellen. Und es wird nach Seite7 getrennt, weil Seite 8 das Stichtwortvzeichnis ist, welches für eine kurze Installationsanleitung nicht vonnöten ist.

Im obigen Beispiel kommen wir also mit Teilen aus. Sind zwischendurch Leerseiten zu entfernen, müssen die einzelnenwichtigen Zwischenstücke am Ende wieder zu einer PDF-Datei zusammengeführt werden.

Paragraphensymbol § im indextermInnerhalb des indexterm-Tags wird das Paragraphensymbol nicht ausgeben und der Stichworteintrag entfällt als Ergebnis ganz.

Es kann sein, dass Ihre Stichworteinträge, beginnend mit dem Paraphensymbol, nicht geparst und somit nicht imStichwortverzeichnis auftauchen. Behelfen Sie sich mit der Nummer im ISO-8859-1-Character-Set oder dem Namen.Im Falle des Paragraphensymbols (Section Sign) ist dies § bzw. §

Zwei zwingende Vorraussetzungen:

1. Texteingabe nur in der Quellcode-Ansicht des Editors. XML Mind macht aus dem § gnadenlos ein §- mit dem Ergebnis, dass dieses Stichwort falsch dargestellt wird.

2. Das Paraphensymbol darf nicht zu Beginn des Stichworteintrages stehen. Setzen Sie z.B. das Kürzel des Gesetzesdavor: StAG 3 Abs. 2.

Manchmal sind aber auch Quellcode-Editoren störrisch. Da hilft, wir bei mir, nur ein gutes Suchen-Ersetzen-Tool fürdas ändern von &#167 in &#167.







Kapitel

7Tools

Themen:

• DITA OT-Installation• PDF Split and Merge






DITA OT-InstallationAnleitung: So installieren Sie das DITA Open Toolkit lokal auf einen PC.

1. Laden Sie das Toolkit auf Sourceforge herunter und entpacken Sie die Zip-Datei.

Abb. 40: Download der full-easy-install-zip-Datei

2. Doppelklicken Sie im neuen Verzeichnis C:\DITA-OT1.5 auf die Datei startcmd.bat.

3. Geben Sie auf der Kommandoebene folgenden Befehl ab: ant -f build_demo.xml und drücke Sie dieENTER-Taste. Dies testet die DITA-OT-Installation.

52 | Ditalog 1.0 | Tools


http://sourceforge.net/projects/dita-ot/files/





Abb. 41: Test der Installation

4. Bestätigen Sie mehrmals mit ENTER, die läßt das Toolkit die Standardeinstellungen übernehmen. So ist es dasVerzeichnis out, in das der Output abgelegt wird. Beim Output type müssen Sie sich entscheiden, ob Sie einErgebnis in HTML, HTML-Workshop (CHM) oder anderes haben möchten. Im Beispiel wurde sich für HTMLentschieden und web eingeben.

5. Warten Sie den Durchlauf ab, bis als Ausgabe Build successful erscheint. Ist der Build nicht erfolgreich,muss die gesamte Installation wie im Tutorial DITA for Solo Writers beschrieben, durchgeführt werden.

6. Als Output erhalten Sie im Ordner \out der Tookitinstallation eine index.html bzw. eine hierarchy.chm,neben einigen anderen Dateien. Doppelklicken sie auf diese Dateien, um das Ergebnis zu betrachten.

PDF Split and MergeDas Java-Tool PDFsam teilt und führt PDF-Dateien zusammen.

Tool PDFsam

Das kleine Tool PDFsam bewältigt zwei Probleme: Seiten entfernen und Linkfähigkeit der PDF-Datei erhalten.

Ditalog 1.0 | Tools | 53


www.ditausers.org/tutorials/lone-dita/ditaguide.pdf





Abb. 42: Teilen und wieder zusammenführen

Das Prinzip des Programm ist es, Dateien zu zerteilen, die leeren und unbrauchbaren Seiten zu löschen und nur diebeschriebenen, wichtigen Seiten wieder zu einer PDF-Datei zusammenzuführen. Im Beispiel wird nach Seite 2 getrennt,weil die ersten beiden Seiten das nicht benötigte Deckblatt und das Inhaltsverzeichnis darstellen. Und es wird nach Seite7 getrennt, weil Seite 8 das Stichtwortvzeichnis ist, welches für eine kurze Installationsanleitung nicht vonnöten ist.

Im obigen Beispiel kommen wir also mit Teilen aus. Sind zwischendurch Leerseiten zu entfernen, müssen die einzelnenwichtigen Zwischenstücke am Ende wieder zu einer PDF-Datei zusammengeführt werden.

54 | Ditalog 1.0 | Tools






Index

A

Adobe AIR SDK 36Adobe Flex SDK 36Adobe Update Framework 39ahix Indexdatei AIR Help 41AIR Help 36

airhelp-packager.bat 37build-Datei 38self-signed certificate 37Zertifikatsdatei 37

airhelpcopyright-Angaben 39Versionsnummer 39

airhelp project file 39airhelp.ahp 39Anker 17

B

Binary TOC 33bookmap

planen 44build_demo.xml 15

C

CHM-DateiInhaltsverzeichnis 32

CHM-Datei konfigurieren 32CombiNumerals 10

D

DITA for Solo Writers vdita-help-importer 27dita2htmlImpl.xsl

gen-user-sidetoc 16dita2Wordpress Anpassungen 28ditahelp.php 27ditaval-Datei 47

F

FAQ-Demo-Spezialisation 15faq2html_shell.xsl 15Flagging im PDF-Output 48Flagging in Ditaval-Datei 18Font CombiNumerals 10

G

gen-user-side-toc 16

H

hängende erste Zeile 45hhp-Datei 33

I

Image in Ditaval-Datei 18Inhaltsverzeichnis 44

K

Kontextsensitive Hilfeper ditamap 14

L

Leximation AIR Help Plugin 36Linking in PDFs 47Links in PDF 50

M

map2ahp.xsl 41map2ahtoc.xsl 41map2hhc.xsl 32map2hhp.xsl 33

N

Namensanker 17Nummerierung in Screenshots 10

P

Paragraphensymbol im indexterm 50PDF leere Seiten entfernen 49PDF Split and Merge 50, 53Plugin tocjs 22Prodinfo 39Produktattribut 47Projektdatei .hhp 33

S

sample_airhelp.xml 38Schaltflächen in CHM-Datei 32scriptorium.com 17Seiteninhaltsverzeichnis 16shortdesc

für kontextsensitive Hilfe 14

Ditalog 1.0 | Index | 55






T

text-indent 45Texteinrückung 45tocjs

basefiles 23Builddatei anpassen 24frameset.html 23tocnav.html 23

toctree.js 23

U

Umlaute 32AIR Help Index 41

Update-Beschreibungsdatei 39

update.xml 40

V

Versionsnummer 39Verzeichnisbaum als Navigation 22vrm 39

X

xref-Links 46

Z

Zugang zum Bildschirm auskoppeln 17, 47

56 | Ditalog 1.0 | Index

Documents

Ditalog - DITA-Praxisbeispiele für Redakteure