Re: [docbook] alternative topic proposal

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

But if topics (or sections or whatever non-block level element) were
the only types of elements that could be children of topicref (or
sectionref), then we end up without the ability to insert paragraphs
and other things at the ends of sections. Why loose a great capability
like that?

Also, most people seem to be talking about adding two or more elements
to docbook. Adding topicref (or sectionref) with the same content
model as section (besides the part that allows one to pull in content)
would only require one new element and would add more capabilities
than the other proposals (I think).

On 10/31/06, Scott Hudson <scottys.log@gmail.com> wrote:
> Right. I know you weren't proposing block content between topics, but
> was trying to address Chris' question regarding segue para between
> topics. The best practice would still be to create a separate
> transitional topic that you would reference via a topicref.
>
> I don't know that DocBook has to say that topics MUST be able to
> standalone, but that has certainly been the mantra in DITA. Transitional
> topics, by definition, would depend on context and thus not "standalone".
>
> Best regards,
>
> --Scott
>
>
> Bob Stayton wrote:
> > 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.
> >
> > http://dita.xml.org/node/1410
> >
> >
> > 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
> > bobs@sagehill.net
> >
> >
> > ----- 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
> >>>>
> >>>>
> >>>
> >>>
> >>
> >>
> >
> >
> >
>
>
>
>


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