07 Mrz 13 Every Page Is Page One
Behandeln Sie jede Seite einer Onlinehilfe oder eines eBooks wie eine Einstiegsseite: bieten Sie Orientierung für die nächsten Schritte und Vertiefung in weitere Themen in Form von Links an.
Dieser Artikel verdankt sein Entstehen dem glücklichen Eintreten zweier Ereignisse:
- Ich hatte über die Metadaten den Dateinamen eines Artikels im sichtbaren Text ausgeben können. Beschrieben ist die Vorgehensweise im Artikel Metadaten im Text – Name des Topics, im eBook enthalten.
Dateiname metadata-output_con sichtbar oben rechts
- Mark Baker veröffentlicht seinen Blogpost A New Approach to Organizing Help. Er bloggt unter der selbsterklärenden Domain Everypageispageone.com mit dem Motto Readers can enter anywhere. Is your content ready to receive them?
Jede Seite hat ein Thema und viele Aspekte – verlinken Sie!
Mark Bakers Blogname Every Page Is Page One ist programmatisch. Die Frage, ob ich eine komplexe Sache in eine große Online-Hilfe mit einem großen Inhaltsverzeichnis bündele oder die vielen Themen in mehrere Online-Hilfen splitte und somit ein aussagekräftigeres Inhaltsverzeichnis erhalte, beschäftigt viele Technische Redakteure. Doch das ist gar nicht nötig, meint Baker.
Every piece of content is rich in subject affinities. That is, the people, places, objects, actions, and ideas mentioned in the piece are connected to those people, places, objects, actions, and ideas, and thus have a connection (an “affinity”) to content that describes those people, places, objects, actions, and ideas.
Yet it is those affinities that actually define the place of a topic in its broader subject area. A traditional book index is an ordered list of the subject affinities in the book. A hypertext link in a Web page is the expression of an affinity between the content in which it occurs and content it links to. Subject affinities anchor a piece of content in time, culture and the reader’s experience.
When the user has landed in your help by way of a Google search, in search of information on a particular problem they are trying to solve, what kinds of additional information are they likely to need if the current topic does not entirely satisfy their needs? It is not information from other general categories of the help system, which is what the TOC provides. It is information related to the subject affinities of the current topic. [1]
In den Zeiten des Standards DITA 1.1 hieß es oftmals: Setzen Sie innerhalb des Textes keine Links zu anderen Topics! Dies lenkt den Leser ab und bringt Sie in Teufels Küche, so bald eine Topic-Datei mal verschoben oder gelöscht wird. Doch nun haben wir im Standard DITA 1.2 die Technologie des relatvien Verlinkens via keys und keyref[2]. Ein Link innerhalb des Textes ist nun kein Teufelszeug mehr. Ändert sich der Speicherort einer Datei, braucht dieser nur noch an einer Stelle geändert werden. Die Hyperlinks, die sich mit keyref auf diese Datei beziehen, aktualisieren die URL ganz von allein.
Dateiname gleich keys
Nun habe ich also den Mut, aus jeder Seite eine EPPO-Seite zu machen (Sie werden die Abk. dechiffrieren). D.h. ich werde nicht scheuen, zu anderen Seiten der Onlinehilfe oder des eBooks auch innerhalb des Textes zu verlinken. So können Sie vorgehen:
1. keys vergeben
Geben Sie in der ditamap in jedem topicref auch einen Begriff für keys ein.
<topicref href="../onlinehilfe/metadata-mailto_con.xml" keys="metadata-mailto_con" scope="local" toc="yes" type="concept" xml:lang="de-de"/>
Achten Sie darauf, dass Sie für keys einfach den Dateinamen eintragen. Hier im Beispiel metadata-mailto_con. Die Dateierweiterung xml ist nicht vonnöten.
2. Mit keyref auf keys referenzieren
Sie finden in einer anderen Datei ein Schlüsselwort (z.B. Feedback), zu welchem Details vorliegen und Sie verlinken könnten? Dann machen Sie das mithilfe der Elemente keyword oder xref und dem dazugehörigen Attributs keyref.
<keyword keyref="metadata-mailto_con">Feedback</keyword>
Während keyword standardmäßig nicht im PDF-Output ausgegeben wird, können Sie bei xref sicher sein, dass der Link im Online- als auch PDF-Output funktioniert.
<xref keyref="metadata-mailto_con">Feedback</xref>
Sie bearbeiten also die Quelldatei in Ihrem Editor und können parallel im vorher generierten Output schauen, zu welchen Seiten sie verlinken möchten. Der Seitenname wird ja jetzt oben rechts ausgegeben. Kopieren Sie ihn einfach und fügen Sie ihn bei keyref als Wert ein. Im obigen Beispielbild ist der Dateiname metadata-mailto_con auch der Wert, den Sie in der ditamap-Datei auch bei keys hinterlegt haben.
Der Dateiname wird also als Identifikation für die E-Mail-Rückmeldung des Nutzers benutzt, aber auch als schnelle Linkmöglichkeit für den keys-keyref-Mechanismus.
Links zum Artikel
[1] A New Approach to Organizing Help, Mark Baker, 2013, zum Link
[2] DITA 1.2 feature article: Keyref overview, Sowmya Kannan, 2009, zum Link
| Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar. |
21 Feb 13 Metadaten im Text ausgeben
So geben Sie z.B. das Datum der letzten Änderung unterhalb des Seitentitels aus.
| Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar. |
Seit Jahren war ich auf der Suche nach einem Weg, die Metadaten, speziell das Erstellungs- und Aktualisierungsdatum eines Topics, im Text auszugeben. Da ich keine Lösung dafür hatte, habe ich das Aktualisierungsdatum immer im abstract hart kodiert. Bis ich im XMetal-Forum auf ein Skript stieß, das die beiden Datumsangaben im PDF-Output mit ausgibt. Dies habe ich selbst noch nicht ausprobiert. Da ich die Datumsangaben für den XHTML-Output benötige, habe ich das Skript für meine Online-Publikationen folgendermaßen angepaßt.
So soll es aussehen
Aktualisierungsdatum in der CHM-Hilfe
In den Formaten CHM, XHTML und EPUB soll oben rechts immer das Datum der Erstellung und der letzten Änderung in grauer Schrift kursiv ausgegeben werden. Und zwar rechtsbündig unterhalb des Titels und vor der Kurzbeschreibung shortdesc.
Metaangaben im Topic
Vorraussetzung ist, dass in jedem Topic, egal ob Task oder Concept etc, folgende Metadaten innerhalb des Tags prolog gefüllt sind.
<critdates> <created date="08.06.2012"/> <revised modified="01.07.2012"/> </critdates>
Hat das Topic noch kein Änderungsdatum, lassen Sie den Tag für revised weg.
gen-user-header-Template anpassen
Suchen Sie innerhalb Ihres DITA-Open Toolkits im Ordner xsl/xslhtml nach der Datei dita2htmlImpl.xsl. Innerhalb dieser Datei muss das Template gen-user-header angepasst werden. Es ist das zweite Template im Bereich, der extra für Ihre Modifikationen für den Header, Footer etc angelegt wurde.
<!-- ========== STUBS FOR USER PROVIDED OVERRIDE EXTENSIONS ========== -->
Im vorhandenen Template gen-user-header fügen Sie, wie unterhalb des Kommentars folgende Zeile ist neu aufgeführt, eine neue Zeile ein.
<xsl:template name="gen-user-header"> <xsl:apply-templates select="." mode="gen-user-header"/> </xsl:template> <xsl:template match="/|node()|@*" mode="gen-user-header"> <!-- to customize: copy this to your override transform, add the content you want. --> <!-- it will be placed in the running heading section of the XHTML. --> <!-- folgende Zeile ist neu! --> <xsl:apply-templates select="*[contains(@class, ' topic/prolog ')]" mode="gen-user-header"/> </xsl:template>
Unterhalb dieses angepaßten Templates gen-user-header fügen Sie ein zweites Template hinzu.
<xsl:template match="*[contains(@class, ' topic/prolog ')]">
<p align="right">
<xsl:if test="*[contains(@class,' topic/critdates ')]/
*[contains(@class,' topic/created ')]/@date">
<span>Erstellt am <xsl:value-of select="*[contains(@class,' topic/critdates ')]/
*[contains(@class,' topic/created ')]/@date"/>. </span></xsl:if>
<xsl:if test="*[contains(@class,' topic/critdates ')]/
*[contains(@class,' topic/revised ')]/@modified">
<xsl:for-each select="child::*[contains(@class,' topic/critdates ')]/
*[contains(@class,' topic/revised ')]">
<span>Letzte Änderung: <xsl:value-of select="@modified"/></span>
</xsl:for-each>
</xsl:if>
</p>
</xsl:template>
Formatierung in der CSS-Datei
Der Absatzp hat eine class="header-metadata" erhalten. Diese Klasse müssen Sie noch Ihrer CSS-Datei hinzufügen.
.header-metadata
{
text-align: right;
font-style: italic;
color: #C2C2C2;
margin-right:10px;
}
Plugin
Da ich die Metadaten nur für Onlinehilfen und eBooks benöte, die des Öfteren aktualisiert werden, habe ich das Template in ein Plugin ausgelagert.
Links
Skript für Metadaten im Text für PDF-Dateien im XMetal-Forum
| Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar. |
17 Jan 12 FAQ-Plugin in das DITA-OT einbinden
Zum zweiten Mal habe ich den Versuch unternommen, das FAQ-Plugin, das standardmäßig im DITA-OT mit ausgeliefert wird, in mein Toolkit einzubinden. Mit Erfolg. In der DITA-Users-Group gab Eliot Kimber den Hinweis, nach welcher Anleitung man dabei vorgehen kann. Da sich bei mir jedoch einige Abweichungen ergaben, hier in folgender Anleitung meine Erfahrungen beim Einbinden der FAQ-DTD.
Weiterlesen als PDF
Lesen Sie den ganzen Artikel als PDF-Datei weiter »
Angaben zum Artikel
 | |
| Aufrufe bzw. Downloads: | 555 |
| Aktualisiert am: | 27.01.2012 |
| Autor: | Andreas Petersell |
| In Gesamtausgabe: | In Gesamtausgabe enthalten |
| Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar. |
27 Sep 10 Neue Publikation für HTML, CHM und ePUB
Nun ist es mir schon wieder passiert: weil ich mir keine Notizen gemacht hatte, durfte ich von neuem herausfinden, warum mein HTML-Output mit dem Plugin TOCJS wieder die Umlaute nicht richtig darstellt.
Falsche Darstellung der Umlaute im Navigationsframe des TOCJS-Plugins
Es gilt, die Datei \demo\tocjs\xsl\tocjs.xml zu editieren. Ändern Sie den Wert für encoding von utf-8 auf ISO-8859-1. So muß es am Ende aussehen:
<xsl:output method="text" encoding="ISO-8859-1"/>
Diese Aktualisierung des TOCJS-Plugins ist auch in die neue PDF-Publikation mit eingeflossen. In ihr sind sämtliche Kapitel mit den Ausgabeformaten HTML, CHM und ePUB mit eingebunden. Wenn Ihnen die Ditalog-Artikel eine Hilfe waren, schreiben Sie darüber in Ihrem Blog! Wenn Sie Ihnen keine Hilfe waren, schreiben Sie die Gründe ebenfalls in Ihrem Blog.
 |
|
| Titel des Downloads: | Ausgabeformate HTML und CHM |
| Art der Publikation: | Kapitel |
| Beschreibung: | Sämtliche Artikel zu den Ausgabeformaten HTML, HTML mit dem Plugin TOCJS (Javascript-Navigationsframe) sowie CHM (Windowshilfe). Ohne Leerseiten. |
| Aktualisiert am: | 18.04.2011. Die EPUB-Generierung ist in der Kapitelausgabe "Dita4Publishers" zu finden. |
| Anzahl der Downloads: | 453 |
12 Mai 10 Symbolschaltflächen hinzufügen
Standard-Schaltflächen
Eine Standard-Schaltflächenleiste im CHM-Standard-Output sieht folgendermaßen aus:
Neue Schaltflächen hinzufügen
Es sollen einige Schaltflächen hinzukommen:
- 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 den Eintrag
Binary TOC=Yes
. Dieser Eintrag steht in der HTML-Workshop-Projekt-Datei Dateiname.hhp. Entweder Sie 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 erweiterten Icons 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 verlinkt werden kann. Im Beispiel verlinkt die Schaltfläche Was ist neu zu einer Seite, die die Neuerungen in der Software als auch 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=Yes Default Window=main
Zwischen OPTIONS und FILES wurde ein weiterer Bereich eingefügt:
[WINDOWS]
. Dem folgt eine lange Zeile. Wie diese Zeile zustande kommt, ist in vielen HTML-Workshop-Internetseiten gut dokumentiert. Ein guter Weg wäre es auch, die Schaltflächen in der Oberfläche des HTML-Workshops hinzufügen und das Ergebnis in der Datei .hhp anschließend zu betrachten und als Grundlage für das DITA-xsl-Stylesheet zu nehmen. Hier der Windows-Bereich zum obigen 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üssen die Neuerungen der Projektdatei in das für die Projektdatei verantwortliche XSL-Stylesheet geschrieben werden. Dies ist 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.
Nachteil der Hartkodierung
Sobald man obige Windows-Einträge in die DITA-XSL-Datei hartkodiert, provoziert man bei anderen Projekten anderen Namens unweigerlich eine Fehlermeldung. Vielleicht wäre eine Plugin-Lösung besser?
