[TYPO3-doc] About DocBook 5 Customization

[Thomas Schraitle]

Hi François,

Thursday 16 December 2010
> 
> This is all very interesting. Your answers raise yet more questions ;-)

Uups. :-)

 
> [...]
> > Your problems remind me of the current structure of our manuals. We use a
> > 
> > structure like this (simplified for the sake of simplicity):
> >    set
> >    
> >      book xml:id=book.quick  # Quick Starts
> >        article
> >        article
> >      
> >      book xml:id=book.user   # User Guide
> >        preface
> >        chapter
> >        ...
> >      
> >      book xml:id=book.admin  # Admin Guide
> >        preface
> >        chapter
> > 
> > In the above structure, we can create a<xref/>  from deep inside
> > book.user to some chapter or section in book.admin. As this is a
> > _complete_ document, the <xref/>s are checked and correctly resolved.
> > Numbers are preserved.
> 
> This is really interesting. However does it mean that all the books have
> to be "in the same place"? [...] For TYPO3 v5/FLOW3 the manuals are 
> - for the time being - inside each Package (the whole thing structured
> purely in packages).
> Would all these manuals have to be brought under the same file hierarchy
> in order to group them into a single set?

Well, from a technical point of view, it would be indeed very convenient. 
Usually you incorporate your chapters etc. with an xi:include element like the 
following (namespace omitted for readability):

  <xi:include href="foo.xml"/>

Nothing prevents you to insert relative path names:

 <xi:include href="../userguide/foo.xml"/>

It would be also possible to make it even more abstract and use an URI:

 <xi:include href="urn:x-typov5:userguide:foo"/>

However, the latter example needs a resolving mechanism, usually done with XML 
catalogs.

Which method you use is a matter of personal taste and technical feasibility. 
If your tool chain doesn't support XML catalogs the last example is futile.

 
> BTW can any tag be included using xi:include? I'm thinking here of
> books, in particular, which could then be made to belong to several sets.

Generally yes. 

Of course, technically it is not a problem to include a para or a filename. If 
this is a good idea depends on your situation. I usually include only 
hierarchy elements like books, chapters, and sections and the like.

By the way: The XInclude specification allows also to include text only 
content. For example, if you want to include source code from some PHP 
scripts.


> Since xi:include can use absolute URLs, it should be possible to include
> books from many different "places", right (hmm, I seem to be answering
> my own question, but I've googled in the meantime ;-) )?

Hehe, yes. See my answer above about XML catalogs.


> As long as we
> have a consistent rule for IDs, we shouldn't run into problems. Is that
> right?

Unfortunately, consistent rules has nothing to do with ID conflicts. :)

Possible ID problems depends on how you structure your documents, how deep 
your "modules" are, and how you group them. If you have to change it very 
often and use it in different places it's very likely that you will run into 
problems.

However, the DocBook people know about this problem for a long time. I've 
followed some of the discussions and it's seems there is a promising solution 
available in the (near?) future.

Be aware: What I will show you is totally new and untested! It's a _proposal_ 
and the DocBook TC can approve it or not.  However, I think, it maybe worth.

Some time ago Jirka Kosek invented a very nifty method of how to "transclude" 
documents. Funnily, yesterday he wrote his proposal[1] to the DocBook 
mailinglist to discuss it. :)

Shortly speaking: You can reference to an external file which is incorporated 
into your main file. This is done with the <ref/> element and pretty similar 
like the XInclude approach. However, the DocBook transclusion goes way beyond 
simple XIncludes: You can define what you want to do with your IDs! This can 
not be done with XIncludes!

The <ref/> elements are resolved through a XSLT step where the ID fixup is 
implemented. For further details read the proposal on the DocBook homepage[2], 
especially section "Special ID/IDREF processing" is probably of your interest.

Futhermore, maybe it's a good time to make some testing of this new approach 
if this is something you need. I'm sure, Jirka would be very happy of your 
feedback. NOW is the time to influence it! :-) Usually DocBook people are 
gentle and friendly. ;-)
 

> [...]
> Indeed it can introduce some overhead in managing IDs, but it's just as
> well if we have a well-defined convention for all manuals. It will make
> cross-linking easier, so it's worth the effort.

I fully agree. Good IDs makes live easier. Especially when you validate your 
document, it's easier to spot the location of a "cha.introduction" than 
"bk740lgidf" ID.


 
> [...]
> More questions to come, but maybe I'll open a new thread then.

Sure, whatever you have speak up. :-)


Cheers,
  Tom

---- References
[1] http://lists.oasis-open.org/archives/docbook/201012/msg00005.html
[2] http://docbook.org/docs/transclusion/