Re: [docbook] alternative topic proposal

["Bob Stayton" <bobs@sagehill.net>]

----- Original Message ----- 
From: "Elliotte Harold" <elharo@metalab.unc.edu>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: "Sean Wheller" <sean@inwords.co.za>; <docbook@lists.oasis-open.org>; 
"Dave Pawson" <davep@dpawson.co.uk>
Sent: Tuesday, October 31, 2006 5:03 AM
Subject: Re: [docbook] alternative topic proposal


> Bob Stayton wrote:
>
>
>> Actually, topicref is an element, not an attribute.  And topicref
>> does not contain any content of its own.  Perhaps
>> I need to show an example.  Here is how a chapter from my book:
>>
>>   http://www.sagehill.net/docbookxsl/Catalogs.html
>>
>> might be authored as topicrefs.  Each of the hrefs points to
>> an XML file that contains a single topic element.
>>
>
> That helps, but where do topics come in? That example just shows 
> topicrefs.

Each of the xml files that a topicref points to contains a single topic 
element.
Also, any place you saw an empty topicref (no children) you could
inline the topic element itself.

>> I don't think it is possible to create a chapter file like
>> this using XIncludes and section files.  If you import
>> a section at level1, then that section file must
>> contain the XIncludes for any sections at level2 under it.
>
> Yes, that's correct. It's  a different way of organizing the same thing. 
> Both seem to have advantages and disadvantages.
>
>> I think this is a simple and elegant way to create modular content
>> using familiar DocBook elements and two new elements,
>> topic and topicref.
>
> I'm starting to see the usefulness of this, but I'm still not convinced 
> this should be part of core DocBook. The processing model is bad enough 
> now with XInclude, but at least that's almost orthogonal to DocBook.
>
> Perhaps there should be a completely separate spec for organizing topics 
> and topicrefs which is not part of core DocBook? This would be a master 
> document that used topicrefs to indicate where to place other articles, 
> sections, chapters, and files?

I think that is what Jirka proposed.


> In fact isn't this really just a form of  an extended XLink?

Perhaps.

> I've toyed with this sort of thing for organizing course notes and slide 
> shows. It really seems to require custom processing. I.e. you can't pull 
> this off with XSLT 1, and maybe not easily with XSLT 2. Consequently I 
> tend to doubt it should be baked into the core.

I thought it could be done with XSLT 1 using the document() function and
EXSLT nodeset().  I'm curious about what problems you encountered
that required custom processing.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net