KNOW HOW. Aufbau der Dokumentationsvorlage (.dot/.dotx)

Transkript

1 KNOW HOW Aufbau der Dokumentationsvorlage (.dot/.dotx)

3 Inhaltsverzeichnis 1 Einleitung Welche Dateien müssen gepflegt werden? single.dotx single.xml single_cover.docx single_shortinstructions.docx ttn.teamtrainer.doc.customtexts.xml Die Dateien im Detail Der Aufbau der Dot Der Aufbau der XML-Datei Der Aufbau der Coverpage Der Aufbau der Shortinstructions Der Aufbau der Customtexts.xml Aufbau der Dokumentationsvorlage (.dot/.dotx) Page I of I

4 1 Einleitung Das vorliegende Dokument enthält Informationen zum Aufbau der Dot (im Word-Format.dot/.dotx), die vom DotConverter in eine Dokumentationsvorlage konvertiert werden kann. Zudem werden die weiteren noch zur Konvertierung benötigten Dateien erläutert. 1.1 Welche Dateien müssen gepflegt werden? Im vorliegenden Beispiel gibt es in der Konfiguration bereits die Vorlage "Single" für einseitige Dokumente. Sie können diese nach Ihren Wünschen modifizieren oder als Grundlage für neue Vorlagen verwenden, etwa für eine "Duplex"-Vorlage für Dokumente, die beidseitig ausgedruckt vorliegen sollen. Die Dateien der Vorlage liegen im Profil der tt knowledge force, und zwar unter..\%profilpfad%\ttn.kf\config\%konfigname%\resources\dot. Es empfiehlt sich, vom Auslieferungszustand dieses Ordners eine Sicherungskopie zu machen, bevor die Dateien hierin bearbeitet werden. Beim Zurückgeben der Konfiguration an den Server oder beim Exportieren der Konfiguration werden die Dateien im Resources -Ordner einbezogen, so dass die DOT-Dateien auch an andere Workstations weitergegeben werden. 1.2 single.dotx In dieser Word-Vorlage (im Beispiel mit dem Namen Single und im Format Word 2007) wird das gesamte Layout für die ttkf-dokumentationsvorlage definiert. Ihr Aufbau wird nachfolgend noch umfassend beschrieben. Greifen Sie auf die Dot immer über das Kontextmenü (Rechtsklick) und den Befehl Öffnen zu. Wenn Sie doppelt auf die Dot klicken, wird standardmäßig ein neues Word- Dokument erstellt, das erst wieder mittels Speichern unter im Dot-Format zu speichern wäre. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 1 of 15

5 Die tt knowledge force unterstützte bis zur Version 2012 ausschließlich das Word- Format.dot (Standard bis einschließlich Word 2003). Wenn Sie dieses Format verwenden möchten, müssen Sie darauf achten, dass die Dot-Dateien nicht mit Word 2007 (oder neuer) gespeichert wurden, da neuere Word-Versionen beim Abspeichern im alten Format nicht korrigierbare Kompatibilitätsänderungen einfügen. Um eine im alten.dot-format vorliegende Dot in das neuere Format zu bringen, speichern Sie die Dot mit dem Befehl "Speichern unter" von Word (ab 2007) und wählen Sie das Dateiformat.dotx. Achten Sie darauf, dass die Option "Kompatibilität mit Word beibehalten" nicht aktiviert ist. 1.3 single.xml In dieser Datei wird die Zuordnung von Formaten vorgenommen. Details werden nachfolgend erläutert. Beachten Sie, dass diese Datei sinnvollerweise den gleichen Dateinamen tragen sollte, wie die zugehörige.dot(x)-datei. 1.4 single_cover.docx Diese Datei ist ein normales Word-Dokument im Format.doc oder.docx. Es enthält die sogenannte Coverpage, also das Deckblatt der Dokumentationsvorlage (dieses wird beim Export nur verwendet, wenn es in den Benutzervorgaben der TTKF unter Inhalte > Export > Dokumentationsexport > Einzeldokument oder > Handbuch aktiviert wurde). 1.5 single_shortinstructions.docx Diese Datei ist ebenfalls ein normales Word-Dokument. Darin ist definiert, wie die Kurzanweisungen formatiert werden. 1.6 ttn.teamtrainer.doc.customtexts.xml In dieser Datei im XML-Format können eigene Textbausteine, die in der Dokumentsprache lokalisiert vorliegen sollen, definiert werden. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 2 of 15

6 2 Die Dateien im Detail 2.1 Der Aufbau der Dot Nachfolgend sehen Sie den exemplarischen Aufbau der Word-Dokumentvorlage. Im Beispiel ist das die Datei single.dotx. Die erste Seite der Dot enthält eine Referenz zur Coverpage. Diese ist komplett in die separate Word-Datei ausgelagert und kann unabhängig von der DOT bearbeitet werden. Der Aufbau ist zwingend wie hier gezeigt: <#CoverPage#> <#CoverAbs#> jeweils abgeschlossen mit einer Absatzmarke, gefolgt von einem Abschnittswechsel. Blättern Sie weiter zur nächsten Seite. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 3 of 15

7 Die zweite Seite, die durch den Abschnittswechsel entsteht, enthält das Inhaltsverzeichnis (dessen Erzeugung für den Dokumentationsexport ebenso wie die Coverpage in den Benutzervorgaben deaktiviert werden kann). Der Text <#TableOfContent#> erzeugt hierbei die Überschrift "Inhaltsverzeichnis" in der jeweiligen Dokumentsprache. Formatierung des Platzhalters wirkt sich exakt auf die Formatierung des später an dieser Position stehenden Texts aus. Der Platzhalter <#TOCAbs#> steht für das eigentliche Inhaltsverzeichnis. Dieses ist das Word-Feld { TOC \o "1-n" }, wobei die Zahl n der Verzeichnisebenen direkt im DotConverter festgelegt wird. Blättern Sie weiter zur nächsten Seite. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 4 of 15

8 Der letzte Abschnitt enthält zwei Referenzen: <#Documentation#> <#ShortInstruction#> Je nach erzeugter Dokumentationsart wird an dieser Stelle die eigentliche Dokumentation oder die Kurzanweisung eingebunden. Beim Export können das Deckblatt (Coverpage) und/oder das Inhaltsverzeichnis unterdrückt werden. Die Kurzanweisung verhält sich dabei so, wie in den Exporteinstellungen für Einzeldokumente eingestellt. Für Handbücher (Dokumentationsexport über ganze Kurse oder Kurskategorien) kann separat eingestellt werden, ob Cover und / oder TOC gewünscht sind. Die Dot enthält neben dem Grundgerüst aus Titelseitenreferenz, Inhaltsverzeichnisreferenz und einer Referenz auf den eigentlichen Inhalt vor allem die Definition des gesamten Layouts. Somit wird über die DOT festgelegt: welches Seitenformat (Größe, Ränder, Seitenausrichtung) verwendet wird welche Formatvorlagen es gibt und welche Formate für sie gelten (Text- und Absatzformate, Aufzählungen...) wie die Kopf- und Fußzeilen aussehen und ob hier Felder oder Grafiken eingebunden sein sollen. Sie können in der Dot auch eigene Word-Formatvorlagen definieren und mit Formaten der ttkf verknüpfen (die Zuordnung nehmen Sie in der XML-Datei vor). Achten Sie dabei darauf, die korrekten technischen Namen der ttkf zu verwenden und die Formatvorlagen exakt so zu schreiben wie in Word. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 5 of 15

9 Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 6 of 15

10 Etwas komplexer ist der Aufbau der Formate mit Icon, etwa "Hinweis" oder "Hotspot". Da ältere Word-Versionen keine Bilddateien als Aufzählungszeichen unterstützen, werden die Icons in der Dot/Dotx aus Kompatibilitätsgründen als Word-AutoText gepflegt. Die vorhandenen AutoTexte können Sie unter Schnellbausteine über den Organizer für Bausteine... einsehen, einfügen und bei Bedarf löschen. Den markierten Bereich im Beispiel (Icon als "Mit Text in Zeile" plus Tabulatorzeichen) können Sie über den Befehl Auswahl im Schnellbaustein-Katalog speichern... sichern und das Icon so auch in das Textformat in der TTKF bringen. Beachten Sie dabei, dass der Baustein exakt so heißen muss, wie die korrespondierende Formatvorlage. Zudem muss unter Speichern in die richtige DOT ausgewählt werden - Word schlägt hier als Standarddatei seine Normal.dot vor. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 7 of 15

11 2.2 Der Aufbau der XML-Datei In der XML-Datei wird die Zuordnung zwischen den in der tt knowledge force vorhandenen Absatzformaten (genauer: deren technischen Namen) und den in der Dot definierten Formatvorlagen vorgenommen. Für jedes Absatzformat muss dabei eine Formatvorlage angegeben werden. Es darf jedoch auch eine Formatvorlage für mehrere Absatzformate verwendet werden, falls gewünscht. Beachten Sie, dass in dieser Datei die Zuordnungen sowohl für die Dokumentation, als auch für die Short Instructions (Kurzanweisungen) gemacht werden. Für die Kurzanweisungen werden in der Regel Absatzformate mit dem Suffix "SI" im technischen Namen verwendet. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 8 of 15

12 Zusätzlich zu den Formaten können noch weitere Zuordnungen für die Dokumentation vorgenommen werden: <PicScale/> <TableIndent/> Darüber können die Skalierung der Bilder und die Einzüge von Tabellen definiert werden. Hierbei bezieht sich PicScale auf die Skalierung von Bildern innerhalb der Dokumentation, wobei ein Wert von 100 eine Skalierung auf 100% der zur Verfügung stehenden Seitenbreite (abzüglich der Ränder) bezieht. TableIndent gibt an, um wie viele Pixel eine Tabelle vom linken Textrand aus eingerückt werden soll. Um z. B. nur eine Skalierung der Bilder auf 80% vorzunehmen, geben Sie hier folgendes ein: <PicScale>80</PicScale> <TableIndent/> Neue Formate in der ttkf GUI können in folgender Datei definiert werden:..\%profilpfad%\ttn.kf\config\%konfigname%\content\all\ttn.teamtrainer.core.xml Die Absatzformate werden in folgendem Block gelistet: <Item Name="$CUSTOMLIST:MODEL-EXTENSION,Sequence.listParagraphStyle"> Die Formate können auch mehrsprachig definiert werden. Ein Beispiel: <Item Name="MyStyle1" Value="de-de=Mein Format 1 default=my style 1"/> Das neue Format "MyStyle1" muss dann in der XML zur DOT (hier: single.xml) wie beschrieben mit einem Word-Absatzformat verknüpft werden. Sollten in Ihrer Konfiguration ausgeblendete Formate vorhanden sein, die Sie verwenden möchten (etwa "Box1"): Diese lassen sich nicht wieder anzeigen, indem "Disabled=0" gesetzt wird, sondern durch Löschen / Auskommentieren des gesamten entsprechenden Items (für "Box1" etwa die gesamte Zeile 349) in der Datei ttn.teamtrainer.core.xml. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 9 of 15

13 2.3 Der Aufbau der Coverpage Die Coverpage (Deckblatt) liegt als Word-Dokument (.doc oder.docx) vor. Hier können Sie das Erscheinungsbild der ersten Seite mit den üblichen Gestaltungsmöglichkeiten von Word anpassen. Der Platzhalter <#CourseTitle#> wird mit dem Metadatum "Title" des exportierten Kurses oder Dokuments gefüllt. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 10 of 15

14 Die Coverpage unterstützt folgende Elemente nicht: - Kopf- und Fußzeilen (diese können ausschließlich in der DOT definiert werden) - Hintergründe mit Farbverläufen 2.4 Der Aufbau der Shortinstructions Die Shortinstructions können ein komplett eigenes Layout aufweisen - z. B. ein Querformat mit dreispaltiger Aufteilung. Wenn Sie in der Kopf- und/oder Fußzeile Tabulatoren einsetzen, werden die Tabstopps um die Tabstopps aus der eigentlichen DOT ergänzt. Beispiel: Ist in der Fußzeile der Shortinstructions ein Tabstopp bei 28cm definiert und in der Dot ein Tabstopp bei 12 cm, wird die Fußzeile im fertig exportierten Kurzanweisungs-Dokument Stopps bei 12 cm und bei 28 cm aufweisen. Dementsprechend müssen Sie gegebenenfalls den Text mit zusätzlichen Tabstopps an die gewünschte Position bringen (damit z.b. die Seitenzahl nicht bei 12 cm, sondern bei 28 cm rechtsbündig eingefügt wird). Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 11 of 15

15 2.5 Der Aufbau der Customtexts.xml Die Datei ttn.teamtrainer.doc.customtexts.xml enthält Definitionen von Textbausteinen, die in alle benötigten Sprachen übersetzt sind. Beispiel: Sie möchten vor dem (von Word über die Feldfunktion "SaveDate" generierten) Datum das Wort "Stand" sowohl in der deutschen, als auch der englischen Dokumentation auf der Titelseite einfügen. Dazu definieren Sie den gewünschten Textbaustein zunächst im Bereich Default. Dann fügen Sie ein Item mit exakt dem gleichen Namen für deutsche Exporte unter German ein. Das Wort "Status" ist der Value dieses neuen Items. Für die weiteren Sprachen, hier English (US), fügen Sie auch jeweils ein Item mit dem gleichen Namen und einem Value mit der Übersetzung ein. Sie können dann den neuen Textbaustein in Word verwenden, so z. B. in der Coverpage oder in der Kopf- oder Fußzeile. Referenziert wird der Baustein über seinen in der customtext.xml definierten Namen, hier also <#State#>. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 12 of 15

17 Um bestehende Kurs- oder Dokumentmetadaten in der DOT zu referenzieren, müssen Sie deren technische Namen kennen. Für Kurseigenschaften verwenden Sie <#Course- DataMETADATA#>, für Dokument eigenschaften <#StoryDataMETADATA#>. Beispiel: Sie möchten die Beschreibung eines Kurses mit in die Dokumentation übernehmen. Der technische Name lautet description. Um eine Referenz herzustellen, verwenden Sie <#CourseDatadescription#>. Aufbau der Dokumentationsvorlage (.dot/.dotx) Page 14 of 15