Re: [docbook] alternative topic proposal

["Bob Stayton" <bobs@sagehill.net>]

----- Original Message ----- 
From: "Elliotte Harold" <elharo@metalab.unc.edu>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: "Johnson, Eric" <Eric.Johnson@iona.com>; <docbook@lists.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
bobs@sagehill.net