Hans A. wrote: > > I've searched the tutorial for this topic but I couldn't find much > except the 'Easily create DocBook olinks' section > > I understand that there are basically two types of cross-references: > 1) link with attributes linkend for document internal links) and > xml:href for external links > 2) olink to reference to a different document within a document set. > Please correct me if I'm wrong.
Do you author a modular document? If this is the case, please note that a modular document counts as a *single* *document*, even if this modular document comprises multiple XML files (some files containing chapters, other files containing appendices, other files containing glossaries, etc). olinks do *not* apply to a single document, even when this document is a modular one. > > Both use the id attribute of the target, meaning the target must have an > id attribute. Yes. > > I've the following questions about XXE support for cross-references: > > - Is there a possibility to automatically create ids at least for > sections or has this always to be done manually? No, this is currently not possible. > - I've used the Docbook->Setup olinks menu to define the documents to > contain olinks and inserting olinks with tagetdoc and targetptr works > fine. However, the current document is not shown, so I assume olinks > will only work with other documents, not inside a document.Correct? In theory, you can create olinks pointing inside the document containing them. However, our olink authoring facility does not allow this kind of use (because we don't see the point of using olinks in this case). > On the other hand it is said that olinks will be automatically adapted when > the document structure changes. Is that so? Sorry but I don't understand: "olinks will be automatically adapted when the document structure changes". My only guess is that this sentence means: the text automatically generated by the DocBook XSL stylesheets for an olink adapts to the structure of the target document. Which is true for olink elements (but also for xref elements). > - What is the recommended way to set cross references in a book? * Use link and xref elements having a linkend attribute in order to point inside the document you are authoring. If the document you are authoring is modular, this does not change anything at all. Example: --- <section xml:id="s1"> <title>First section</title> <para>See also <xref linkend="s2"/>.</para> </section> --- --- <section xml:id="s2"> <title>Second section</title> <para>See also <xref linkend="s1"/>.</para> </section> --- The two xref elements above are OK whether section s1 and section s2 are in the same file (monolithic document) or not (modular document). * Use a link element with attribute href in order to point outside the document you are authoring. * Forget about olinks if you are authoring a single, possibly modular, document as, in this case, olinks are not useful at all. * More generally, forget about olinks as these are quite difficult to process. More information in http://www.sagehill.net/docbookxsl/Olinking.html > - What if I define links with linkend attribute inside a document and a > target section is moved into a different document? This never happens. What may happen is: you are authoring a modular document and the target section is moved to a different *file* included in the same modular document. When this is the case, the link with the linkend attribute is OK, as long as you do not change the id of the target section. > > Can you point me to some place where I possibly can find out what's best > practice for cross-referencing when writing Docbooks? > Sorry but I don't know such place. --- PS: If like many users of XXE, you are using XXE to author a *single*, albeit *modular*, DocBook document, then you should: * Forget about olinks. * Unlearn the tutorial "Easily create DocBook olinks". * Exclusively use link and xref elements. * Read the tutorials in the "Modular documents" section. See http://www.xmlmind.com/xmleditor/tutorial.html The XXE facility called "Document Set" allows, among other features, to easily create link and xref in the context of a single modular document. See "Working with a document set" -- http://www.xmlmind.com/xmleditor/_tutorial/document_set/index.html -- XMLmind XML Editor Support List [email protected] http://www.xmlmind.com/mailman/listinfo/xmleditor-support
