Ditalog
msgbartop
DITA für Redakteure – von Single Source Publishing bis Self-Publishing
msgbarbottom

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:

  1. 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.
    Datei- bzw. Seitenname im Output ausgeben

    Dateiname metadata-output_con sichtbar oben rechts

  2. 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 im Text ausgeben

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

Artikel als PDF anzeigen
Aufrufe bzw. Downloads: 865
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.

01 Mrz 11 Icon Teil 1: Grundform des Icons in Inkscape erstellen

Wenn man nicht gerade Webseiten und Online-Hilfen am Fließband erstellt, kommt man als Technischer Redakteur nicht so oft in die Verlegenheit, ein Favicon erstellen zu müssen. Als ich zum zweiten Mal vor der Aufgabe stand, hatte ich alles bisherige zur Iconerstellung vergessen. Für mich und für manch weiteren Redakteur nun die Anleitung fixiert.

  1. Erstellen Sie im Open Source Graphikprogramm Inkscape eine Grundform Ihres Icons. Bestimmt hilft Ihnen wie mir ein Graphiker weiter.
  2. Es gilt, Icons für die Größen 16, 32, 48 und 128 px zu erstellen. Erstellen Sie ein Quadrat mit 32px Breite und Höhe.

    Breite und Höhe des Quadrats einstellen

  3. Bestimmen Sie Farbe der Füllung und der Kontur des Quadrats. Soll das Icon transparent sein, wählen Sie links die Kreuzfarbfläche für “keine Farbe”.
  4. Soll das Icon und somit diese Hintergrundquadrat abgerundetet Ecken haben, markieren Sie das Rechteckt. Anschließend klicken Sie auf das Rechteck-/Quadrat-Tool in der Werkzeugleiste und ziehen den Anfasser in Kreisform in der rechten oberen Ecke in die diagonale, linke untere Ecke.

    Mit Rechtecktool die Ecken abrunden

    Mit Rechtecktool die Ecken abrunden

  5. Falls Ihnen das Icon nicht plastisch genug erscheint, fügen Sie der Icon-Grundform einen Farbverlauf hinzu.

    Mit dem Farbverlauf-Tool arbeiten

  6. Positionieren Sie das Objekt der Grundform in die Mitte des Quadrats.
  7. Markieren Sie beide Objekte und klicken Sie auf Objekte > Gruppieren.
  8. Klicken Sie auf Datei > Bitmap exportieren.

    Bitmap exportieren aus Inkscape

  9. Klicken Sie im Fenster Bitmap exportieren auf Auswahl.
  10. Optional: Hinterlegen Sie im Feld Dateiname einen Dateipfad.
  11. Klicken Sie auf Exportieren. Es wird im ausgewählten Pfad eine PNG-Datei erzeugt.
  12. Wiederholen Sie die Schritte für die Größen 16, 48, 128 und 256 px.

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

Links zum Thema

  1. Download Inkscape von heise.de

19 Mrz 10 Umzug

Das Ditalog zieht um in ein Blog! Der XHTML-Output des Ditalogs ist weiterhin erreichbar unter www.tocjs.ditalog.com