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: Add topic element to DocBook?

/ Camille Bégnis <camille@neodoc.biz> was heard to say:
| Norman Walsh a écrit :
|> If we decide to do so, I think something along the following lines
|> fits into the design of DocBook:
|> 1. Add a <topic> element with the same content model as <section>
|>    except that where section allows (sect1|section|simplesect), we
|>    allow <topic>. So a topic contains subtopics analagous to the way a
|>    section contains subsections.
| I tend to concur with Doug here: why couldn't a topic be structured in
| sections? Since a topic is meant to have a specific semantic meaning,
| one might not want to organize his topic information in [your semantic
| meaning of topic here].

I think the question of whether a topic is allowed to contain sections
is seperable from the questions about how they might be mixed
together. But if your topic is so large that it benefits from having
sections, maybe you should be thinking about how to break it into
separate topics instead. I dunno.

|> 3. Allow topic as an alternative to (chapter|appendix|preface) in books..
|>    This allows one to have a book of topics.
| Wouldn't that wipe the main difference between a book and an article?

How so? You can already have a book of articles. I wouldn't expect
articles to be able to have topics though.

|> 4. Allow topic as an alternative to (sect1|section|simplesect) in
|>    chapters and appendixes. This allows one to have a chapter of
|>    topics.
| Given the above and the obvious similarity between a section and a
| topic, I'd rather suggest to specialize the section element with an
| attribute (type="topic"?). That would allow further specializing section
| (which is a renowned modular element).

That isn't very amenable to extension along the topic axis. Would you
be comfortable with a "tasksection" element, for example? And it
doesn't overcome the semantic problems I outlined a moment ago in
response to doug's mail.

|> As a slight extension of this model, we could also add a <tasktopic>
|> element. This would address the feature request[1] for "task" as a
|> peer to "section". If we did this, then I'd expect "topic" or
|> "tasktopic" to be allowed anywhere I've mentioned topic above.
| Wouldn't a topic containing a task serve the same purpose?

Not quite because tasks have to have titles and so do topics. Having
the task inside the topic would leave open the possibility of extra
material before and after the task which would then muddy the waters
surrounding the constrained content model of task.

|> Given that topics are often composed in a fairly arbitrary order for
|> publishing in print, we might want to consider adding a "contentmap"
|> element as well for describing the order of topics. But we might be
|> able to get "toc" to serve this purpose.
| How would that differ from an article containing a hierarchy of sections
| and xincludes to topics?

An xinclude just replaces one blob of content with another. The mapping
stuff can reorganize material. Imagine you have three topics, all discrete.
A mapping like this one:

    <mapentry ref="topic1"/>
    <mapentry ref="topic2">
      <mapentry ref="topic3"/>

would make the third topic a subtopic of the second for the purposes
of appearing in print (so they might be numbered 1, 2, 2.1, for example).

Yes, I think this is a little weird, but I accept that if you've
authored a hundred discrete topics and thirty five of them are about
different aspects of managing printers, *in print* you might want to
have an umbrella topic about printers and have those thirty five topics
appear as subtopics when presented in a linear order on dead trees,
even though you wouldn't do that for the online help-style

                                        Be seeing you,

Norman Walsh <ndw@nwalsh.com>      | Old and young, we are all on our
http://www.oasis-open.org/docbook/ | last cruise.--Robert Louis
Chair, DocBook Technical Committee | Stevenson

PGP signature

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