Re: [docbook] alternative topic proposal

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

Yes, as you say, it would absorb the interstitial content into the
topic (or section) that is being transcluded and will appear at the
end of that transcluded topic (or section).

In addition to the example you gave, my proposal would also allow this:

<sectionref href="HowToWriteCatalogs.xml"> <!-- begins "how to write
catalogs" -->

<para><!-- begins interstitial content to be added to "how to write
catalogs" -->
now that I'm done talking about how to write catalogs, I want to talk
about some other important issues, such as resolving the DTDLocation
and locating XSLstylesheets.
</para>

<sectionref  href="ResolveDTDLocation.xml"/> <!-- begins and ends
resolve dtd location -->

<sectionref href="LocateXSLstylesheet.xml"> <!-- begins locate xsl
stylesheet -->

<section><!-- begins interstitial conent to be added to "locate xsl
stylesheet" -->

<title>Connection with Resolving DTD Locations</title>

<para>Let's review what we've covered so far about locating XSL
stylesheets and relate that to resolving DTD  locations. A few points
I would like to raise are:</para>

<orderedlist>random xml here</orderedlist>

<example>more xml here</example>

</section><!-- ends interstitial content to be added to "locate xsl
stylesheet" -->

</sectionref><!--ends locate xsl style sheet--> <!-- also ends
interstitial content to be added to "how to write catalogs" -->

</sectionref><!--ends how to write catalogs-->




<topicref  href="HowToWriteCatalogs.xml">
 <para>Some transition block elements that appear after the content
referenced by href above, and before the content referenced by the
topicrefs below</para>
<section><title>stuff</title>
<para>so the weather is nice</para>
</section>
 <topicref  href="ResolveDTDLocation.xml"/>
 <topicref  href="LocateXSLstylesheet.xml"/>
 [other topicrefs]
</topicref>

and, as you said, the transition content would be appended *into* (but
at the end of) the topic (or section) referenced by





On 10/31/06, Bob Stayton <bobs@sagehill.net> wrote:
> Hi Chris,
> I'm not sure I understand your proposal.
>
> > Adding topicref (or sectionref) with the same content
> > model as section (besides the part that allows one to pull in content)
>
> So you are suggesting something like this example:
>
> <topicref  href="HowToWriteCatalogs.xml">
>   <para>Some transition block elements that appear after the content
> referenced by href above, and before the content referenced by the
> topicrefs below</para>
>   <topicref  href="ResolveDTDLocation.xml"/>
>   <topicref  href="LocateXSLstylesheet.xml"/>
>   [other topicrefs]
> </topicref>
>
> In the output presentation, the transition blocks would look like they were
> the end of the first topic, unless your stylesheet purposely formatted it
> differently to indicate transitional content.
>
> I presume the transition content model would be block elements and would
> not include section? More like the content model of simplesect?
>
> Bob Stayton
> Sagehill Enterprises
> DocBook Consulting
> bobs@sagehill.net
>
>
> ----- Original Message -----
> From: "Chris Chiasson" <chris@chiasson.name>
> To: "Scott Hudson" <scottys.log@gmail.com>
> Cc: "Bob Stayton" <bobs@sagehill.net>; "Sean Wheller" <sean@inwords.co.za>;
> <docbook@lists.oasis-open.org>; "Dave Pawson" <davep@dpawson.co.uk>
> Sent: Tuesday, October 31, 2006 11:12 AM
> Subject: Re: [docbook] alternative topic proposal
>
>
> > 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/
> >
> > ---------------------------------------------------------------------
> > 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/