Magnus G?fvert wrote: > > I am working on a docbook 5 modular users guide (each chapter in > separate file) with html, and I am now sort of stuck on the > cross-referencing matter. For a single-file document the xref elements > are very convenient to use, with xxm keeping track of available > linkends. A quite extensive web research on how to work with > cross-referencing in modular documents has pointed me to the conclusion > that one should use olinks (or links with xml:href attributes) with > target database(s) to get things right. The whole olink machinery seems > quite complex, and perhaps a bit overkill for modular document > cross-referencing (is seems more designed for cross referencing within > collections of books). > > Before spending a lot more time on this I would like to get some input > from other users. > > * What are best practices for cross referencing within a modular document? >
Do *not* use olinks. olinks should be reserved to linking deliverables which are part of the same set of documents. This is very different from a modular document. Use xref and link elements and type the linkend attribute as if the document module was part of the master document. XXE currently provides no assistance in doing that. You are currently forced to know the link targets ``by heart''. (This is what we do for our own documents.) > * Are there any good tutorial style web resources on modular documents > and cross-referencing (using xxe)? No. > * Is olinking with target databases supported by xxe, and if so, to what > extent? Yes and no. Yes. XXE is an XML editor and as such, supports olinks as any other element. Our own document set makes use of olinks. You can download the sources to our own document set from here: http://www.xmlmind.net/xmleditor/_download/xxe-docsrc-4_5_1.zip No. XXE will not help you in quickly creating olinks. The target database stuff is purely a DocBook XSL stylesheets artifact and thus, is not related to XXE. An olink is basically the identifier of a document + optionally an ID found in this document. --> Now, the good news. XXE v4.6 will have a "Link tool". This new tool should solve the following problem: quickly and easily create links in modular documents. This new tool will use ``master documents'' as ``link contexts''. A master document is: * Any XML document making use of XIncludes. * OR A DITA map or bookmap. * OR A synthetic map, mapping unique identifiers to DocBook documents. This should allow to quickly insert olinks. (Of course you'll have to use the same identifiers in the target database.)
