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: Re: [docbook] alternative topic proposal

Hi Scott,
Just to be clear, putting block content between topics or topicrefs is not 
something I proposed.  I was thinking of something parallel to the current 
chapter/section structure, where once you start a section in a chapter, you 
don't include any more block elements ampng them.

DITA committee member JoAnn Hackos wrote a paper on transitional text. The 
paper questions the need for such transitional text in technical writing.


Personally, for DocBook I would want to keep the usage of topicref really 
simple and not permit it. I could be convinced otherwise.  Maybe we could 
make title optional in topic to serve such a purpose. Write a short topic 
and reference it with topicref to provide the transition.  That keeps it 
modular, and you can reuse the transition topic.  8^)

Bob Stayton
Sagehill Enterprises
DocBook Consulting

----- Original Message ----- 
From: "Scott Hudson" <scottys.log@gmail.com>
To: "Chris Chiasson" <chris@chiasson.name>
Cc: "Bob Stayton" <bobs@sagehill.net>; "Sean Wheller" <sean@inwords.co.za>; 
<docbook@lists.oasis-open.org>; "Dave Pawson" <davep@dpawson.co.uk>
Sent: Monday, October 30, 2006 10:53 PM
Subject: Re: [docbook] alternative topic proposal

> If you use Bob's example below, you could put para or most other allowed
> children of chapter between topicrefs...
> Of course, if you want seques inside of a topicref and between nested
> topicrefs, then we'd have to adjust the model for topicref.
> Then again, you can always do what the DITA folks recommend: if you need
> transitional text, stick it into a separate topic. Of course, that
> transitional topic won't meet the standalone requirement at that point,
> but that's the same situation in DITA...
> --Scott
> Chris Chiasson wrote:
>> 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

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