vishia - Querverweise in generierter Dokumentation

Topic:.orgVishiaXmlDocu.href.

pStyle=std tableStyle=stdTable

.

Topic:.orgVishiaXmlDocu.href.overview.

pStyle=std tableStyle=stdTable

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.

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.

(Quelle: Artikel SBNF - vom freien Textformat nach XML in Der Entwickler 2007-02)

Topic:.orgVishiaXmlDocu.href..

pStyle=std tableStyle=stdTable

Hyperlinks (Querverweise), die während der Dokumentengenerierung variabel zugeordnet werden sollen, werden in den Input-XML-Files als lokaler Hyperlink mit einem # vornweg angegeben, also in der Form <a href="#label>text</a>.

Wird eine Konvertierung laut WikiFormat verwendet, typisch in Flachtexten entweder in den TextTopics oder beispielsweise in textuellen Descriptionfeldern von Softwarequellen, dann schreibt man dort [[label]]. Das ist die selbe Schreibweise wie bei Wikipedia für Verweise auf andere Schlagworte. Damit wird ein lokaler Hyperlink erzeugt, der dann weiterverarbeitet wird. Die Schreibweise mit dem lokalem Label ist insoweit logisch, als dass ein Verweis auf etwas erfolgen soll, was lokal im Verantwortungsbereich der Dokumentengenerierung liegt, also nicht außerhalb im Internet.

Ein nicht als lokales Label notiertes Label wird nicht variabel umgesetzt. Nicht lokale Labels dürften typisch Internet-Links sein, aber auch Links absolut oder relativ im Filesystem. Bei der Konvertierung laut WikiFormat kann mann für ein festes Label entweder [[!Label]] schreiben, oder auch [[http....]]. Letzteres ist mit der Schreibweise in Wikipedia identisch, die erste Form nicht. Wikipedia kennt entweder nur Labels im eigenem Bereich oder Labels zu fremden Internetseiten, aber keine relativen Labels auf dem Wiki-Internetspace.

Topic:.orgVishiaXmlDocu.href.CrossReferences.

pStyle=std tableStyle=stdTable

Alle internen Labels (mit # am Anfang) werden bei der Dokumentengenerierung im Schritt CorrectHref (siehe Topic:.XmlDocuGenCtrl.DataFlow. getestet gegen die Angaben im Generier-Steuerfile. Entweder der Generier-Steuerfile oder ein zusätzlich angegebener Referenz-File muss folgende Angaben enthalten (Beispiel):

 HyperlinkAssociation
 { Ident_A_* = "../DocuA/X2Docu.html#*XY";
   Ident_B_*X2 = "../DocuB/X2Docu.html#*XY";
   method:_pkgZ.*:* = "../javadoc/pkgxy/pkgZ/*.html#*";
   *MOD = "modulDoc.html#*MOD";
 }

Wie auch einleitend im Zitat aus dem Zeitschriftenartikel erwähnt sind links vom Zuweisungszeichen = Labels mit Wildcards dargestellt. Hierbei sind zwei Wildcards zulässig. Die internen Labels werden auf Zuordenbarkeit getestet. Dabei erfolgt zunächst eine Aufsuche des linken Teils des Labels bis zum ersten '*', die intern alphabetisch sortiert vorliegen. Ist ein mittlerer oder rechter Teil vorhanden, wird dann in einer Schleife über alle mittleren oder rechten Teile iteriert und die Richtigkeit geprüft. Dabei werden die Bereiche, die durch das Wildcard (*) abgedeckt sind, erkannt und gemerkt. Der Ersatz erfolgt dann mit der Angabe im rechten Teil innnerhalb der "...". Dabei werden anstelle der Wildcards dort die gemerkte Zeichenfolge eingesetzt.

Also ein Label als Hyperlinksziel

 #method:_pkgZ.MyClass.innerClass:doit()

wird ersetzt durch

 ../javadoc/pkgxy/pkgZ/MyClass.innerClass.html#doit()

Das Beispiel passt auf ein Verweis in eine Javadoc hinein. Es erfolgt eine Angabe des Files und des Anchor innerhalb des Files.

Das rechts angegebene Ziel-Label (Anchor für Hyperlink) ist für diese Dokumentengenerierung gültig. Die Hyperlinks in den Ergebnissen der Generierung werden damit gesteuert, ohne in den Quellen der Generierung in dieser Form bekannt sein zu müssen.

Die Hyperlink-Anchors (Anker der Querverweise) können ...

• können im Dokument selbst liegen, dann beginnt der Anchor mit einem #. Das ist daher zweckmäßig, weil ein Dokument sehr umfangreich sein kann und aus verschiedenen Quellen bestehen kann. In den Quellen sind es übergreifende Hyperlinks, die sich dann letzlich im selben Dokument finden.

• können mit einem relativem Path beginnen und daher in einem Dokumentenverbund liegen. Wie bei Hyperlinks üblich beziehen sich die relativen Pfade immer auf das aktuelle Dokument und funktionieren auch bei Übertragung auf einen Webspace.

• können mit einem absoluten Path beginnen, beispielsweise bei Ablage in einem Firmennetz mit bekanntem Filesystem.

• können mit http:// beginnen und verweisen damit auf eine Internetadresse oder sonstige URL bzw. genauer auf einen Zugriff, der über das HTTP-Protokoll ausgeführt wird.

• Es gibt eine weitere Funktionalität, die Austauschbarkeit des Anfangs des Hyperlink-Anchors über einen zusätzlichen Parameter beim Generieren, siehe Kapitel 5 Austausch des Anfangs einen Hyperlink-Anchors. Damit ergibt sich die Möglichkeit, mit den selben Angaben ein Dokument beispielsweise entweder für den Zugriff im Internetspace zu generieren oder für den Zugriff auf ein lokales Filesystem.

Topic:.orgVishiaXmlDocu.href.hrefCtrl.

pStyle=std tableStyle=stdTable

Der Block der

HyperlinkAssociation
{ ...
}

kann relativ umfangreich werden, die Einträge in diesem Block können für eine Vielzahl von Dokumenten an sich identisch sein. Andererseits gibt es pro Dokument wenige Hyperlinkzuordnungen, die für dieses Dokument anders gelten sollen als sonst. Insbesondere sind das die Hyperlinks, die in das eigene Dokument hineingehen.

Daher gibt es eine insgesamt 3-stufige Hyperlinkorganisation:

• Im Generier-Steuerfile ist es möglich, am Anfang die Zeile

 hrefCtrl: ../../path/file.href;

• anzugeben. Damit wird ein zusäztlicher File mit Hyperlinkangaben benannt, der beispielsweise zentral für mehrere Dokumente gelten kann. Es kann mehrere solcher Files geben für bestimmte Varianten der Hyperlinkgestaltung, beispielsweise Links für englische oder deutsche Verweisquellen. Dieser File braucht nur den oben gezeigten Hyperlink-Block enthalten. Eine adäquate Möglichkeit ist die Angabe dieses Pfades als Umgebungsvariable HREFCTRL beim Aufruf der Dokumentengenerierung. In diesem Fall bedarf es keiner unterschiedlichen Generier-Steuerfiles für verschiedene Ausführungen der Hyperlinks. Umgebungsvariable können lokal in einem Batchfile gesetzt werden.

  Die Angaben aus diesem File werden zuerst eingelesen.

• Angaben in einem Hyperlink-Block des eigenen Files der Dokumentengeneriersteuerung werden danach eingelesen. Gleiche Angaben des primären Labels für die Hyperlink-Zuordnungen überschreiben dann die Angaben aus einem vorher eingelesenen zusätzlichen Files, sind also prior.

• Als letztes werden Hyperlink-Assoziationen aus dem Block der Dokumentengenerierung eingelesen und gelten prior:

Document "vishia - Querverweise in generierter Dokumentation" ident=Hyperlink
html="../html/Hyperlink.html"
{ input: ../tmp/Href.topic.xml;
  topictree(orgVishiaXmlDocu/href/*);
  HyperlinkAssociation  //the hyperlinks in the own document:
  { HrefInDocuGenCtrl = "#Topic.orgVishiaXmlDocu.";
    CorrectHref = "#CorrectHref";
    Hyperlink-Korrektur = "#CorrectHref";
    Topic:.orgVishiaXmlDocu.href.* = "#Topic.orgVishiaXmlDocu.href.*";
  }
}

• Das Beispiel ist der Control-Block dieses Dokumentes. Insbesondere die Hyperlink-Anker, die sich im eigenem Dokument befinden, werden hier dann mit direkt lokalen Labels besetzt.

Topic:.orgVishiaXmlDocu.href.hrefExchg.

pStyle=std tableStyle=stdTable

Im Block HyperlinkAssociation kann angegeben werden (Beispiel):

HyperlinkAssociation

Ident_A_* = "$DOCUPATH_A/DocuA/X2Docu.html#*XY";

 Ident_B_*X2 = "$DOCUPATH_A/DocuB/X2Docu.html#*XY";
 method:_pkgZ.*:* = "$JAVADOC/javadoc/pkgxy/pkgZ/*.html#*";
 *MOD = "modulDoc.html#*MOD";

}

Das Kriterium ist der Start der Anchor-Angabe mit einem $. Die darauf folgende Zeichenkette bis zum ersten Slash / wird als Name einer Umgebungsvariable benutzt. Üblicherweise werden Umgebungsvariable groß geschrieben und enthalten nur Buchstaben, Ziffern und _, was denn auch hier zutrifft. Der Wert der Umgebungsvariable wird benutzt und damit der Anfang des Hyperlink-Anchors bestimmt.

Die Umgebungsvariable kann beispielsweise eine Internetadresse enthalten, wenn die Files, auf die verwiesen werden, innerhalb dieses Webspaces auffindbar sind. Die Umgebungsvariable kann beim Aufruf der Dokumentengenerierung unmittelbar zuvor gesetzt werden, im Batchfile:

 set DOCUPATH_A=http://www.organisation.org/subdir

Hinweis: Es ist darauf zu achten, dass die Zeile keine nachfolgenden Leerzeichen enthält. Das ist immer wichtig wenn Umgebungsvariablen in Batchfiles setzt. Ein Setzen der Umgebungsvariable im System geht zwar auch, ist aber meist nicht zweckdienlich, da dann keine Flexibilität vorhanden ist. Umgebungsvariable sind inbesondere für das Setzen in Command-Scripts geschaffen worden. Sie werden nur bei Windows meist nicht in dieser Art verwendet.

Wird ein adäquater Satz der Dokumente dann beispielsweise für ein internes Filesystem generiert, dann wird die Umgebungsvariable entsprechend anders gesetzt:

 set DOCUPATH_A=file://D:/Documents/dir

Hierbei ist auch ein relativer Pfad sinnvoll. Das ist dann zweckmäßig, wenn andere Dokumente entweder in einem relativen Verband vorhanden sind oder im anderen Fall einzelne Dokumente wie ein readme.html zu einem Download dort herausgelöst wird und daher alle Querverweise nur noch über eine Internet-URL funktionieren können.

Topic:.orgVishiaXmlDocu.href.AdjustRelPath.

pStyle=std tableStyle=stdTable

Wenn bei einem Hyperlink ein relativer Pfad angegeben wird, dann bezieht dieser sich auf die Position im Filesystem, in der das Dokument steht, dass diesen Hyperlink enthält. Wenn man relative Pfade in einer HyperlinkAssociation angibt, dann gilt diese aber gegebenenfalls für mehrere Dokumente oder sogar für sehr viele Dokumente. Letzteres ist der Fall, wenn eine allgemeiner Referenzfile (siehe 4 Verwendung eines zentralen Hyperlink-Zuordnungsfiles und/oder Hyperlink-Zuordnungen pro Dokument) angegeben wird. Sind alle relativen Positionen der Dokumente im Filesystem auf der gleichen Ebene, stimmt also die Anzahl der ../ zu einer gemeinsamen Wurzel überall überein, dann ist das kein Problem. Werden die Files jedoch auf verschiedenen Ebenen erzeugt (verteilt in einem Baum), dann ist die Korrektur der Anzahl ../ notwendig, damit der relative Pfad stimmt.

Die Korrektur erfolgt auf der Kenntnis der Lage des Output-Html-Dokumentes, dass ebenfalls mit einem relativen Pfad angegeben werden muss:

Document "vishia - Querverweise in generierter Dokumentation" ident=Hyperlink
html="../html/Hyperlink.html"
{ ....

In diesem Fall steht das Dokument auf der selben Ebene wie der Generierfile.

Document "readme - ZBNF" ident=readme_ZBNF
html="../../../readme_ZBNF.html"
{

Dieses Dokument steht 3 Verzeichnisebenen weiter links, ein relativer Pfad, der sich auf das Generierverzeichnis bezieht, muss also um ../../../ gekürzt werden.

Der relative Pfad von Hyperlink-Anchors im HyperlinkAssociation{...}-Block muss vom Generierverzeichnis aus angegeben werden. Wenn die Möglichkeit des Kapitel 5 Austausch des Anfangs einen Hyperlink-Anchors benutzt wird, dann erfolgt dies in einer Umgebungsvariable. Die allgemein angegbenen Pfade zu verschiedenen Dokumenten einer Filegruppe sollten sich auf das am weitestens links (unten, zur root) bezogene Verzeichnis beziehen.

Das Java-Programm javadoc:_org/vishia/xml/docuGen/CorrectHref übernimmt die notwendigen Parameter mit der -o:-Option: Angabe des Ausgabefile-Pathes, wobei von dieser nur die Position im Filesystem benötigt wird.

Topic:.orgVishiaXmlDocu.href.exampl.

pStyle=std tableStyle=stdTable

Folgende Beispiele aus dem eigenem Bereich dieses Dokumentes erläutern die Anwendung. Dargestellt ist immer

Topic:.orgVishiaXmlDocu.href.exampl.catchword.

pStyle=std tableStyle=stdTable

 ZBNF_on_Sourceforge = "http://www.sf.net/projects/ZBNF";
 Zmake = "../../Zmake/index.html";
 Xslt-WhiteSpaces = "../../Xml/XmlDocuGenerated/XmlDocuVishia.html#chapter_2.4";
 Hyperlink-Korrektur = "#CorrectHref";

Solche Labels sind eigene Begriffe in Dokumenten, mit denen in der Form [[ ZBNF_on_Sourceforge]] oder [[ Zmake]] in TextTopics hingewiesen werden kann. Dabei kann ein Link wie gezeigt auf eine URL im Internet geleitet werden, auf ein anderes HTML-Dokument oder auch auf einen Link innerhalb eines anderen Dokumentes oder einen Link im eigenen Dokument, wie die 4 Beispiele zeigen. Von der Möglichkeit der Änderung nur in den HyperlinkAssociation gegebenenfalls nur in wenigen Files wird man dann profitieren, wenn andere Dokumente überarbeitet worden sind und daher an anderer Stelle stehen. Wesentlich schwieriger in solchen Fällen sind verteilte Links in vielen HTML-Dokumenten. Wird beispielsweise ein abgeschlossenes Word- bzw. pdf-Dokument erstellt, dass keine Querverweise nach außen haben soll (gedruckte Form), dann können die Hyperlinks auch ersetzt werden durch Hyperlinks innerhalb des Dokumentes zu einer Liste mit Literaturangaben, wie es weiter unten erläutert ist.

Topic:.orgVishiaXmlDocu.href.exampl.topic.

pStyle=std tableStyle=stdTable

Topic:.orgVishiaXmlDocu.href.* = "../../XmlDocu/html/Hyperlink.html#Topic.orgVishiaXmlDocu.href.*";
Topic:.orgVishiaSwEng.SourceCodeGen.* = "../../SwEng/html/SourceCodeGen.html#Topic.SourceCodeGen.*";
Topic:.orgVishiaXml.Xslt.* = "#lit.vishia-Xslt"

Wie in TextTopics beschrieben sollen Topics jeweils eindeutig in einem Gesamtprojekt identifiziert sein oder besser über Projektgrenzen eindeutig, in dem man das Toplevel-Topic der zuständigen URL folgend benennt. Text-Topics können in mehreren Dokumenten Eingang finden. In einem Text-Topic kann daher eigentlich nur mittels direkter Angabe des Topic-Pfades verlinkt werden, in dem dort beispielsweise angegeben wird: [[ Chapter: 7.1 Links zu Schlagworten (Begriffen mit eigenständiger Bedeutung)]] oder [[ Topic:.orgVishiaSwEng.SourceCodeGen.]]. Wo dieses Topic präsent ist, soll aus dem Kontext des generierten Dokumentes bestimmbar sein. Nur für ein generiertes und in einem Kontext abgespeichertes Dokument ist definiert, wo fremde Topics auffindbar sind. Ein Dokument ohne Kontext (frei kopierbares pdf-File) sollte anstatt eines Links nach außen eine Querverweistabelle enthalten, an denen Literaturstellen aufgeführt sind.

In der oben beschriebenen Form sind die Topics mit ihren Anfangs-Pathes einzelnen Dokumenten oder wie im dritten File auf eine Querverweisliste innerhalb des eigenen Dokumentes zugewiesen. Der Pfad muss tief genug angegeben werden, wenn Topics eines Baumes in verschiedenen Dokumenten verstreut aufgefunden werden sollen.

Link zur Kapitelüberschrift der Text-Topics:

Mit einer Schreibweise [[Topic:.orgVishiaXmlDocu.href.exampl.catchword.|$chapter]] in einem WikiFormat-Flachtext oder einer Schreibweise <xhtml:a ref="#Topic:.orgVishiaXmlDocu.href.exampl.catchword.">$chapter</xhtml:a> in einem XML-Text wird angegeben, dass einerseits der Hyperlink auf die Kapitelüberschrift zeigen soll, in der das Topic steht, andererseits dass diese Kapitelüberschrift auch als Link-Text benutzt werden soll. Das ist oft angenehm, der Leser möchte eher nicht die Bezeichnung eines Topic-Pfades als Link sehen sondern einen lesbaren Text dessen, was dort beschrieben ist.

Die Realisierung dessen geht aber (derzeit) nur für Topics im eigenem Dokument. Die Zuordnung wird von javadoc:_org/vishia/xml/docuGen/CorrectHref ausgeführt. Wenn dieser Mechanismus auch für andere Dokumente gelten soll, dann muss bei der CorrectHref das andere Dokument vorliegen, mindestens als eine ältere Version, die aber das Topic an der selben Stelle enthält wie eine ggf. eben noch nicht generierte neue Version. Dann ist es möglich, innerhalb von CorrectHref dieses Dokument aufzuschlagen, das Topic dort drin zu suchen und die entsprechende Kapitelüberschrift zu ermitteln. Dann muss auch der Name des Dokumentes mit aufgeführt werden. Diese Vorgehensweise ist noch nicht relalisiert (TODO).

Topic:.orgVishiaXmlDocu.href.nonresolved.

pStyle=std tableStyle=stdTable

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:.orgVishiaXmlDocu.href.nonresolved..

pStyle=std tableStyle=stdTable

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:.orgVishiaXmlDocu.href.nonresolved..

pStyle=std tableStyle=stdTable

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:.orgVishiaXmlDocu.href.nonresolved..

pStyle=std tableStyle=stdTable

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:.orgVishiaXmlDocu.href.BackHref.

pStyle=std tableStyle=stdTable

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.