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

[François Suter]

Hi,

> This would shorten our IDs a little, and make them better readable; with
> no downsides I think (as we'll use olinks)... And I think it is OK for
> an author to distinguish between external and internal links.

I've been thinking about this these last few days and re-reading what 
Tom had already written about olinks (and read from he just wrote 
again). I would kind of split this:

I still think that all official documentation (including books like the 
Extbase book and manuals from system extensions) should be in a single 
structure. This makes it possible to use simple cross-references within 
this "space".

We could still provide an olink table, but that would be used mostly for 
documentation that sits outside of the "space", i.e. extension manuals.

There's yet another possibility (raised by Tom a good while earlier): 
the current issue with linking to a particular point in the 
documentation is that the parts are number with a scheme that changes 
more or less all the time. With the documentation coming from DocBook 
this would not happen as long as the IDs don't change. This means that 
manual writers could safely use simple links to the HTML documentation.

For references we can be pretty sure that the IDs won't change, unless 
they were misspelled or some property was wrongly catalogued, which 
should be a rare event.

For manuals, it's a bit more complicated as a section could be move 
around for increasing the manual's consistency or ease of reading, or 
due to some reorganization after an inflow of new content, so those IDs 
could change more often. Maybe that's where we should rethink the IDs, 
so that they are not so strictly related to the manual's hierarchy.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch