[TYPO3-doc] DocBook: XML IDs // Linking between documents

[Thomas Schraitle]

Hi Sebastian,

Wednesday 27 April 2011
> 
> thanks very much for your input :-)
> 
> > I would better try to avoid olinks for the time being and try to
> > establish the DocBook conversion first. From there you can always
> > introduce olinks in the documents if it' really needed. :)
> 
> Right now I'd feel that it should be definitely possible to hide the
> complexity of using olinks (more complicated setup) in the build
> process. Don't you think so?

Well, if you feel confident I'm the last one who want to stop you. :) 

My concerns are summarized the following list:

1. Is it really needed?
Before we enthusastically embrace olinks, lets first try to work with the 
existing linking mechanisms (xref, link). If we think this is _really_ needed, 
_then_ (and only then) olinks are an opportunity. 

2. Delayed "Validation"
Validation in DocBook without olinks is one step: Call your validator and see 
what happens. This also includes the ID/IDREF connection. You make it or break 
it. This is a good thing as you know immediately where you've introduced a 
typo into your IDs.

Validation with olinks is ambigious: you never know if your document is really 
valid from a ID/IDREF point of view. They give you a false sense of certainty.
Olinks don't operate with ID/IDREF connection, they are just CDATA, plain text 
(they have to!). As such a typo cannot be detected during validation. You can 
only see a problem _after_ you've transformed your document into FO, XHTML, or 
any other format.

3. Unintuitive Writing
How many know how to write correct olinks? Bob Stayton describes 6 steps(!) 
for working with olinks: http://www.sagehill.net/docbookxsl/Olinking.html

Although 6 steps are not a really high number, I consider it as too much. You 
need some knowledge about the rendering process and some "target databases". 
These information has to hand-wired into your olink attributes.

Although I understand that some of these obscure olink attributes are needed, 
I don't think it's really intuitive. If others have the same impression, I 
fear it won't be used that much.


4. Dependency Nightmare
The olink mechanism needs a so called "target database". Actually it's only a 
XML file which contains all IDs from your target book. This file is created in 
a separate step (see the link above from Bob's book.)
Olinks are only reliable, if the target database is stable. However, if your 
"other" book constantly change, so it will your target database.

This is not a problem "per se". However, consider now you have not two books 
which are inter-connected, but much more. You create dependencies between 
these books and the needed target databases. If some of a book content 
changes, you have to make sure every target database is "in sync" which I 
consider a dependency nightmare. :)


 
> I think we have about 60-70 "official" manuals right now, not counting
> the community-extensions (which are a few thousand)... When we want to
> use xref to link between these, I understand that we always have to load
> the *full set* of manuals to the XSLT processor, and then using "rootid"
> to determine what part should be actually rendered. To me, this just
> does not sound feasible for this amount of documentation :-)

Actually we do this exactly as you've described with our openSUSE manuals. We 
have a set which contain XIncludes to all the other books. Inside the books 
you have also XIncludes to other chapters etc. 

Of course, that's perfect if your book is part of the whole set. This works 
for _us_ pretty good as we deliver usually some sort of a User Guide, an 
Administration Guide, and Quick Starts. There it makes sense to cross 
reference from, lets say, the Quick Start to the Admin Guide. We've discussed 
olinks, but never implemented them. We use <xref/>s which works pretty well, 
although you have to be careful.

For your amount of documentation, this is not possible. But maybe it's a good 
opportunity to do some consolidation. And, as I'm on a heretical path today: 
Is this huge amount of documentation really needed? :) To me it's a bit... 
overwhelming.


Thanks for reading,
 Tom