Inhalt
Topic=.XmlDocuGen.href.
.
Topic=.XmlDocuGen.href.overview.
Die Möglichkeiten von Hyperlinks innerhalb der generierten Dokumentation und zu Nachbardokumenten stellen sich als eigenes Problem dar, einfach deshalb weil in einem Quelldatenbestand nicht bestimmt werden kann, ob ein bestimmtes Hyperlink-Ziel (Anker) in der generiertem Dokumentation oder in einem Nachbardokument vorhanden ist. In den Quelldaten kann letzlich nur ein Identstring als Ziel angegeben werden.
Topic=.XmlDocuGen.href.CrossReferences.
Nicht erfüllbare Hyperlinks werden gelöscht. Damit entsteht beim Leser keine Unruhe, wenn Hyperlinks nicht funktionieren. Es gibt aber den Fall, dass kein Ziel für ein Hyperlink vorhanden ist, aber dennoch ein Hyperlink erscheinen soll, beispielsweise um auf eine Literaturliste zu zeigen. Die Literaturliste enthält dann den manuellen Hinweis, wie die entsprechende Dokumentation bezeichnet ist bzw. wo diese aufzufinden ist.
Für Literaturangaben kann es beispielsweise einen umfangreichen XML-File geben, der alle notwendigen Angaben für alle möglichen Literaturstellen enthält. In der Anwenderdokumentation soll aber nur dienigen Angaben erscheinen, auf die auch wirklich referenziert wird. Die Auswahl welche dies sind, kann aber erst nach Zusammenstellung des fertigen Dokumentes erfolgen da erst dann dessen Inhalt bestimmt ist.
Dem End-Anwender soll nun nicht eine zusätzlich programmierte Auswahl aufgebürdet werden, etwa ein spezielles XSL-Script, sondern die Dokumentengenerierung erledigt das selbst. Jedoch soll die Form dieser Angaben einschließlich der Entscheidung, welche Zusatzinformationen verwendet werden, in der freien Gestaltung der Anwender-Aufbereitung liegen.
Nachfolgend ist von Querverweislisten (en: cross reference lists) im allgemeinerem Sinn die Rede, da das Prinzip sich nicht nur auf Literaturangaben beziehen kann. Ein anderes Beispiel wäre eine Bauteilbezeichnung, die in gleichartiger Weise zu einer Liste mit kurztextueller Beschreibung von Bauteilen führen kann, auf die im Dokument referenziert wird.
Topic=.XmlDocuGen.href.CrossReferences..
Diese Bestimmung führt der End-Anwender in gleicher Weise aus wie die Bestimmung aller Labelzuordnungen innerhalb der Dokumentengenerierung. Und zwar im Abschnitt
HyperlinkAssociation
{ xyz* ="xxx*";
Lit* ="#Lit*":Literaturangaben;
Bauteil* ="#Comp_*":ComponentList;
}
|
Entscheidend ist hier die Angabe eines Bezeichners nach dem Doppelpunkt, auf das Ziel-Label folgend. Beim Ziel-Label ist ein führendes Doppelkreuz anzugeben, weil es sich um ein internes Label handelt. Gibt es keine einheitliche Festlegung von Präfixes oder Postfixes für solche Dinge, dann kann die Angabe an dieser Stelle auch sehr umfangreich werden weil womöglich für jedes einzelne Label anzugeben. Das stört die Dokumentengenerierung aber nicht, problemlos verarbeitbar.
Topic=.XmlDocuGen.href.CrossReferences..
Häufig ist das ein bestimmter Abschnitt in der Dokumentation. Es kann aber auch innerhalb eines mit XSL anwenderaufbereiteten Blockes liegen. Im Vor-vor-generierten Dokument (name.pre1.xml) kann an beliebiger Stelle ein XML-Element mit dem Attribut
<Tag crossRefContent="IDENT"> |
gekennzeichnet sein. IDENT sollte der Bezeichner sein, der auch nach dem Doppelpunkt bei den HyperlinkAssociation angebeben ist. (Das muss nicht unbedingt sein, im XSL kann auch etwas anderes berücksichtigt werden.) Über diese Bezeichnung erfolgt die Auswahl der Kovertierung erfolgt, wie im weiter unten dargestellten XSL-Script gezeigt. Dieses Attribut kann entweder über ein XSL-Script generiert werden, oder es wird im textuellem Dokumentengenerierscript DocuGenCtrl angegeben. Dort in folgender Form:
crossRef(IDENT); |
Damit wird im name.pre1.xml ein leeres <xhtml:body crossRefContent="IDENT" /> erzeugt.
Topic=.XmlDocuGen.href.CrossReferences..
Die Steuerung, was zu tun ist für das Füllen, obliegt der Anwenderaufbereitung.
Das Generieren von Inhalt für Querverweislisten erfolgt nach Abschluß der Vor-vor-Generierung (name.pre1.xml) mit dem Schritt der Labelzuweisung (CorrectHref). Dabei wird ein XSL-Script angegeben, dass ein Block mit beispielhaft folgendem Inhalt haben soll:
<xsl:template match="/">
<xsl:variable name="content" select="/root/@crossRefContent" />
<xsl:choose><xsl:when test="starts-with($content,'Literaturangaben')" >
<pre:CrossRefContent><!-- the root element of this transformation. -->
<xhtml:dt><xsl:value-of select="$content" />
</xhtml:dt>
<xhtml:dd>
<xhtml:p><xsl:value-of select="/root/Literaturlisten/item[xxx] />
</xhtml:dd>
</pre:CrossRefContent>
</xsl:when><xsl:otherwise>
<pre:noCrossRefContent />
</xsl:otherwise></xsl:choose>
</xsl:template>
|
Es wird im Wurzel-Template entsprechend eines Attributes @crossRefContent verzweigt, was zu tun ist. Dieses Attribut wurde im Java-Programm javadoc:_vishia/xml/CorrectHref zuvor gesetzt aus der Information im Attribut crossrefContent im name.pre1.xml-Dokument. Das Attribut ist wichtig, um in den entsprechenden Zweig zu verzweigen. Dort wird entweder ein Element <pre:CrossRefContent> mit Inhalt oder <pre:noCrossRefContent /> als Wurzelelement im Ausgabebaum erzeugt. Der Inhalt innerhalb des Elementes wird dann als Inhalt in das entsprechende Element in der generierten Dokumentation eingefügt.
Topic=.XmlDocuGen.href.BackHref.
Eine Übersicht, von welchen Stellen im eigenen Dokument auf ein bestimmtes Ziel verlinkt wurde, kann eine wünschenswerte Ergänzung sein. Eine Dokumentengenerierung kann hier automatisch diese Arbeit erledigen, manuell wäre es aufwändig. Aber die Art der Gestaltung der Rückwärtsreferenz muss anwendersteuerbar sein, also in einem XSL-Script enthalten sein.
Es stellen sich zwei folgende Fragen, die der Anwender für seine Dokumentenart / sein Dokument individuell beantworten können muss:
An welcher Stelle sollen Rückwärtsreferenzen gesammelt werden?
Wie sollen die Rückwärtsreferenzen dargestellt werden?
Die zweite Frage ist in etwa beantwortbar mit folgenden Überlegungen:
Rückwärtsreferenzen sollen jeweils als Listenpunkt dargestellt werden.
Im Listenpunkt soll mindestens das Kapitel genannt werden, in dem der Hyperlink auftritt. Genaueres anzugeben ist meistenteils nicht möglich. Gut wäre es aber, bei seitenorientierten Dokumenten die Seitenzahl anzugeben.
Die Rückwärtsreferenz muss ein Hyperlink zur referenzierenden Stelle enthalten.
Mit dieser Festlegung bekommt der Leser den Überblick, an welcher Stelle wozu etwas gesagt wurde. Der Leser kann das am Inhaltsverzeichnis spiegeln.
Das entspricht dem Verfahren, wie in gedruckten Dokumenten Stichwortverzeichnisse angegeben werden.
Die erste Frage ist nicht allgemein beantwortbar. Es liegt frei in der Hand des Anwenders, wo er Rückwärtsreferenzen plazieren möchte. Das kann sein an derjenigen Stelle, an der die Referenz definiert ist. Das kann aber auch eine extra Übersichtsliste sein, im Anhang oder dergleichen. Damit ergibt sich die Notwendigkeit, für jede Referenz eine eigene Position im Dokument für Rückwärtsreferenzen anzugeben. Das kann einfach in einem speziellen Xsl-Script etwa für UML-Softwaredokumentation erfolgen, oder mit dem Schlüsselwort
BackRef(<$?label>); |
innerhalb eines Kapitels angegeben werden.
Topic=.XmlDocuGen.href.DerEntwickler0702.
Die Möglichkeiten von Hyperlinks innerhalb der generierten Dokumentation und zu Nachbardokumenten stellen sich als eigenes Problem dar, einfach deshalb weil in einem Quelldatenbestand nicht bestimmt werden kann, ob ein bestimmtes Hyperlink-Ziel (Anker) in der generiertem Dokumentation oder in welchem Nachbardokument vorhanden sein wird. In den Quelldaten kann nur ein Identstring als Ziel angegeben werden. Aber nicht einmal dieser ist eindeutig. Mischt man Eingangsdaten aus verschiedenen Bereichen, dann sind gegebenenfalls keine Regeln für eindeutige Vergabe von Ident-Bezeichnern vorhanden. Die richtige Zuordnung der Hyperlinks kann daher nur auf der Ebene der Dokumentationsgenerierung selbst vorgenommen werden, gesteuert von Angaben in der Steuerdatei zur Generierung.
Es ist sinnvoll, Ident-Bezeichnern für Hyperlink-Anker aus verschiedenen Bereichen einen Präfix voranzustellen. Das kann geregelt werden mit entsprechender Gestaltung der XSL-Scripts für die Eingangsdatenkonvertierung. Idents für Hyperlink-Anker können auch erst bei der Generierung vergeben werden, insbesondere für ganze Kapitel. Im obigen Beispiel für die Steuerung der Dokumentationsgenerierung ist in einer chapter-Zeile id=name zu diesem Zweck angegeben. Bei den Hyperlink-Zielangaben kann die Steuerdatei entsprechende Angaben für eine Zuordnung enthalten:
HyperlinkAssociation
{ *MOD=modulDoc.html#*MOD;
Type_A_*X2=../DocuTypeA/X2Docu.html#*XY;
}
|
Diese Angaben bedeuten Folgendes: Alle Idents, die auf MOD enden, sind im Dokument modulDoc.html mit diesem Ident als Anker aufzufinden. Alle Idents, die mit Type_A_ beginnen und mit X2 enden, sind im angegebenen Dokument zu finden, mit einem Anker-Ident ohne den Präfix und mit Suffix XY. Bei allen nicht auf diese Weise zuordenbaren Idents wird getestet, ob diese im eigenem Dokument definiert sind. Ist das nicht der Fall, dann wird der Verweis weggelassen, und zwar entweder nur der Hyperlink selbst, oder auch der zugehörige Verweistext. Diese Nachbearbeitung erfolgt nicht mit dem XSL-Script, sondern in einem danach aufgerufenen Java-Programm zugehörig zur Erstellung des XhtmlPre.
TODO
siehe vishia/xml/CorrectHref.java