alternative topic proposal

----- Original Message ----- 
From: "Elliotte Harold" <elharometalab.unc.edu>
To: "Bob Stayton" <bobssagehill.net>
Cc: "Johnson, Eric" <Eric.Johnsoniona.com>; <docbooklists.oasis-open.org>
Sent: Sunday, October 29, 2006 1:07 PM
Subject: Re: [docbook] alternative topic proposal


> Bob Stayton wrote:
>> Yes, they could be siblings.  Article can appear in
book or part, and 
>> the book and part content models (after the title
stuff) consist of a 
>> collection of components in any order.
>>
>
> So what's the difference between a topic and an article
then?


A topic and an article are semantically similar, in that
they are both 
intended as standalone content.  But I would say that,
semantically 
speaking, an article is even more standalone, while a topic
is generally 
embedded in a collection of other topics of related subject
matter to which 
it makes references.  Maybe that sounds like a journal
containing a set of 
articles, but DocBook doesn't do journals.  8^)

In terms of content models, an article can contain appendix,
colophon, and 
ackno, which I think would be inappropriate for topic.  It
has been 
suggested that the content model of topic should be that of
section, but I 
think that assumption should be carefully examined.  The
content model of 
section includes refentry, which I think should be excluded
from topic 
(since a refentry is a reference-type topic, and I don't
think topics 
should be nested).  Both article and section allow glossary,
bibliography, 
index, and toc, and those should also be examined to see if
they are 
appropriate for topic.

In terms of usage, you can put a topic in a book, part,
chapter, appendix, 
preface, and article (the last four assuming you exclude
sections from 
same).  An article can only appear in a book or part.

If you think it might be odd to mix topic, chapter, article
and such in a 
book, I would like to take this opportunity to point out
that DocBook's 
content model for book is not prescriptive.  A book (after
the title stuff) 
is any collection of book component elements in any order. 
So you could 
start a book with an appendix and end it with a table of
contents, if you 
want.  In the early days, DocBook's book element prescribed
order along the 
lines of conventional front matter and back matter.  But
over time, people 
presented use cases for other ordering schemes. At some
point the committee 
just left it up to users to create the order they want. That
has made 
DocBook very flexible in meeting many needs, even if it
doesn't give the 
control that some people want.  You can always customize if
you want more 
control.

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