Re: [docbook] alternative topic proposal

["Chris Chiasson" <chris@chiasson.name>]

What if one needed an interstitial paragraph to segue from one
subtopic to another?

On 10/31/06, Bob Stayton <bobs@sagehill.net> wrote:
> ----- Original Message -----
> From: "Sean Wheller" <sean@inwords.co.za>
> To: <docbook@lists.oasis-open.org>
> Cc: "Bob Stayton" <bobs@sagehill.net>; "Dave Pawson" <davep@dpawson.co.uk>
> Sent: Monday, October 30, 2006 9:38 PM
> Subject: Re: [docbook] alternative topic proposal
>
>
> On Monday 30 October 2006 22:32, Bob Stayton wrote:
> > f we also introduce the idea of topicref, then we are adding new
> > capabilities to DocBook to assemble these modules into sequences and
> > hierarchies. The difference from XInclude is that a topicref is resolved
> > by an XSLT process, so the assembly process can actively filter and fix
> > content rather than just copy it into place. That's a big gain in modular
> > processing, if you need it.
>
> I agree that this is a benefit. Still however, I am not convinced that this
> must be an attribute of a new element. Why can't we have this anyway, on
> existing elements?
> ------------------------------------------------------------------------------------
> 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.
>
> <chapter>
>     <title>XML catalogs</title>
>     <para>A catalog in XML ...
>     <para>There are two kinds of catalogs ...
>     <topicref  href="WhyUseXMLCatalogs.xml"/>
>     <topicref  href="HowToWriteCatalogs.xml">
>         <topicref  href="ResolveDTDLocation.xml"/>
>         <topicref  href="LocateXSLstylesheet.xml"/>
>         <topicref  href="MapWebAddress.xml"/>
>         <topicref  href="MapWithRewrite.xml"/>
>         <topicref  href="MultipleCatalogs.xml"/>
>     </topicref>
>     <topicref  href="ExampleDocBookCatalog.xml"/>
>     <topiciref  href="HowToUseCatalog.xml">
>         <topicref  href="InSaxon.xml"/>
>         <topicref  href="InXalan.xml"/>
>         <topicref  href="InXsltproc.xml"/>
>     </topicref>
> </chapter>
>
> When an empty topicref is resolved, the referenced topic is
> simply imported and assigned the current level in the
> processing hierarchy of the output.  So the first topicref
> would be equivalent to a sect1 in formatted output in this
> instance.
>
> When a topicref contains other topicrefs, that expresses
> a hierarchy of topics.  The outer topic ref is imported and
> assigned the current level of processing (another sect1
> in this example).  After its content
> ends, the children topicrefs are imported in the order given
> and assigned formatting equivalent to sect2.
>
> The result of processing this chapter should match
> the output you see on my website.  If needed, the topics
> could be reshuffled using a different topicref
> hierarchy for a different purpose in another document.
>
> 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.
>
> I think this is a simple and elegant way to create modular content
> using familiar DocBook elements and two new elements,
> topic and topicref.
>
> Bob Stayton
> Sagehill Enterprises
> DocBook Consulting
> bobs@sagehill.net
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
>
>


-- 
http://chris.chiasson.name/