OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Best Practise of Referencing Between Modules in Assemblies?


as I'm currently playing with DocBook assemblies, I'm wondering about the 
"best practise" of referencing from one module into another.

The "classical" (or usual) way is to get the ID of your target resource and 
put it into a linkend attribute of <xref/>. This establish a strong bond of a 
single one-way ID/IDREF which can be checked during validation.

Of course, this method can still be used with assemblies. However, it seems to 
me, as this method creates hard dependencies it makes maintaining all the 
topics/modules a bit too hard.

For example, if you have several modules in your assembly file, referencing 
back and forth, you can't be sure if the target resource is really "used". 
Therefor you can't be sure to have a valid single result DocBook document 
after the assemble process.

Thinking about assemblies and referencing, some issues are still unresolved to 
me and leads me to the following questions:

 (1) How do I reference to a chapter when I do not know if this
     chapter will be included or not? 

 (2) Is there a "preferred" method which is still readable and
     easy to maintain?

 (3) How do I reference to a set of links where I do not know the
     exact IDs?
     For example, if I have a book with several topics and I want
     to link only to topics which deal with the "DocBook5" realm?

I've though about this problem and can think of these solutions:

* An answer to (1) can be profiling. However, that raises another question: 
which profiling attributes should I use? The output[1] element contains a 
format attribute, but there is no equivalent attribute for the other DocBook 
elements (see [2a,b]).

* TDG5.1[3] gives an example with the relationship element. This could be 
another solution, but it is still unclear to me how does it fit into the whole 
picture. Probably a stylesheet process can resolve any references.

* Another method could be extended XLinks, but I'm not sure how to use it in 
this context.

To summarize it: on the one hand we have the strong ID/IDREF mechanism, but on 
the other hand it seems we lack/need a more "soft referencing" mechanism. Or 
in other words: we have one ID and many references to it, but on the contrary 
there is no mechanism (really?) how do we write a reference which points to 
only some IDs.

What do you think? Do you have used assemblies already and how do you deal 
with referencing? Do I miss anything? 

Thank you for your ideas. :-)

---- References
[1] http://www.docbook.org/tdg51/en/html/output.html
[2a] http://www.docbook.org/tdg51/en/html/ref-elements.html#common.attributes
[2a] http://www.docbook.org/tdg51/en/html/ref-
[3] http://www.docbook.org/tdg51/en/html/ch06.html#relationships

  Thomas Schraitle

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]