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
> bobssagehill.net
>
>
> ----- Original Message -----
> From: "Chris Chiasson" <chrischiasson.name>
> To: "Scott Hudson" <scottys.loggmail.com>
> Cc: "Bob Stayton" <bobssagehill.net>; "Sean Wheller"
<seaninwords.co.za>;
> <docbooklists.oasis-open.org>; "Dave
Pawson" <davepdpawson.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.loggmail.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/nod
e/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
> >> > bobssagehill.net
> >> >
> >> >
> >> > ----- Original Message ----- From:
"Scott Hudson"
> >> > <scottys.loggmail.com>
> >> > To: "Chris Chiasson"
<chrischiasson.name>
> >> > Cc: "Bob Stayton" <bobssagehill.net>; "Sean Wheller"
> >> > <seaninwords.co.za>;
<docbooklists.oasis-open.org>; "Dave Pawson"
> >> > <davepdpawson.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
<bobssagehill.net> wrote:
> >> >>>> ----- Original Message -----
> >> >>>> From: "Sean
Wheller" <seaninwords.co.za>
> >> >>>> To: <docbooklists.oasis-open.org>
> >> >>>> Cc: "Bob Stayton"
<bobssagehill.net>; "Dave Pawson"
> >> >>>> <davepdpawson.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
> >> >>>> bobssagehill.net
> >> >>>>
> >> >>>>
> >> >>>>
> >> >>>>
> >> >>>>
------------------------------------------------------------
---------
> >> >>>> To unsubscribe, e-mail:
docbook-unsubscribelists.oasis-open.org
> >> >>>> For additional commands,
e-mail: docbook-helplists.oasis-open.org
> >> >>>>
> >> >>>>
> >> >>>
> >> >>>
> >> >>
> >> >>
> >> >
> >> >
> >> >
> >>
> >>
> >>
> >>
> >
> >
> > --
> > http://chris.chiasson.nam
e/
> >
> >
------------------------------------------------------------
---------
> > To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
> > For additional commands, e-mail: docbook-helplists.oasis-open.org
> >
> >
> >
>
>
>
--
http://chris.chiasson.nam
e/
------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org
|