There's something about introducing <topic> into
DocBook that doesn't quite seem right to me.
I think that the DITA model is a "bottom-up"
approach, using <topic> as the building block for publications. However,
the DocBook model (so far) has been a "top-down" approach, with documents
typically being authored as entire publications that contain chapters and
sections.
Introducing a <topic> into DocBook muddies the
waters. Either:
(1) You use <topic>s instead of <book>s, in
which case why not just use DITA?; or,
(2) You insert <topic>s into <book>s, in
which case the <topic> wouldn't really seem to be a standalone
unit of information as intended.
That's my two cents', anyway.
*************************
Rob
Cavicchio
Principal Technical
Writer
EMC Captiva
EMC Corporation
10145 Pacific Heights Boulevard, 6th
Floor
San Diego, CA 92121-4234
P: (858) 320-1208
F: (858)
320-1010
E:
The opinions expressed here are my
personal opinions. Content published here is not read or approved in advance by
EMC and does not necessarily reflect the views and opinions of
EMC.
From: Bergfrid Skaara
[mailto:]
Sent: Monday, July 27, 2009
5:44 AM
To: Bob Stayton
Cc: DocBook Apps;
Subject: Re: [docbook-apps] DocBook
topic element
This would be most welcome!
We currently do modular authoring with customized section templates but
without schema validation. Topics might save us from the consistency
maintenance nightmare :)
About the design: you say in #2 that a topic can be for example a task,
does this mean that db.task will be a child of topic? If so, consider that
both topic, task, and procedure elements have a title. Today, with task as
child of section, you get the title three times (by default) - and if you do
not wrap tasks in sections , the tasks are not numbered and you easily get
validation errors when assembling your modular document.
If you implement this, please consider adding the DITA-like "Related
information" block at the end of topics.
Best regards, Bergfrid Skaara
On Sat, Jul 25, 2009 at 6:59 PM, Bob Stayton <> wrote:
The
DocBook Technical Committee is considering adding features to DocBook to
better support modular authoring and assembly of documents. The
Committee is developing an assembly structure that lets you point to DocBook
files and elements, similar in function (but not form) to DITA maps. A
process would be run on an assembly to pull the various elements together
for further processing as a document.
While it would be possible to
assemble a document from existing DocBook elements, I submitted an
additional proposal to add a new <topic> element. Such a topic element
would be a natural candidate for assembly of modular units into larger
documents.
A new topic element is needed because no other
DocBook
element meets the needs for authoring standalone units
of
information. A section element is not appropriate, because
it
implies a "section of something" with a larger context.
The article
element comes closest, but it allows appendix,
acknowledgements, and
colophon children, which are not
appropriate for a topic. Also,
article currently cannot
be a child of chapter or appendix.
The
design goals of this proposal are:
a. To provide a designated element
for authoring
modular content, each instance of which "stands alone",
but
which also has relationships to other modules.
b. Design the
topic element to be very general, so
that it can be adapted for many
types of topics.
c. Make the addition of topic backwards
compatible
with DocBook 5.0.
d. Clearly distinguish topics and
sections.
Here are is the proposed design for topic:
1.
The content model for topic is identical to that of section.
2. A
topic type is indicated by a CDATA "type" attribute value.
For example,
"task", "reference", "concept", etc.
3. A topic cannot include topic
children. Allowing a topic
to contain other topic elements breaks
the semantic of
"standalone unit of information".
4. A topic can
contain section children to subdivide its content
for clarity and ease of
reference.
5. A section element cannot contain a topic
element.
Placing a topic inside a section implies the topic
depends on
the section parent for its context.
It also hopelessly muddles the
distinction between
topic and section.
6. Allow topic as a
child of book or part. This allows you
to author groups of topics in a
convenient container.
Such topics could be siblings of chapters and
other
component elements, the way article can be such a
sibling.
7. Allow topic as a child of chapter or appendix, but
not
as a sibling of section. This also allows you to
author
groups of topics in a convenient container, this time
grouped
into a chapter or appendix. There is an additional
constraint,
though. A chapter can contain either section
children or topic
children, but not both. This is to
maintain a clear distinction
between topics and sections.
The Committee would like to allow
some experimentation and comment before adopting the new element. I
include here a customization of DocBook 5.0 RelaxNG (compact syntax) to add
a topic element as described above. The Committee looks forward to
users trying it out and commenting on their experiences and
ideas.
------------------ topic customization
-------------------------------
default namespace = "http://docbook.org/ns/docbook"
namespace db = "http://docbook.org/ns/docbook"
namespace xlink = "http://www.w3.org/1999/xlink"
namespace s = "http://www.ascc.net/xml/schematron"
namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
include
"docbook.rnc" inherit = db {
db.toplevel.sections
=
((db.section+, db.simplesect*) | db.simplesect+)
|
(db.sect1+, db.simplesect*)
| db.refentry+
|
dbx.topic+
}
dbx.topic =
element topic {
dbx.topic.attlist,
dbx.topic.info,
db.recursive.blocks.or.sections,
db.navigation.components*
}
dbx.topic.type.attribute
=
attribute type { text }
dbx.topic.attlist =
db.section.attlist & dbx.topic.type.attribute?
dbx.topic.info =
db._info.title.req
-----------------------------------------------------------------------
Bob
Stayton
Sagehill Enterprises
---------------------------------------------------------------------
To
unsubscribe, e-mail:
For
additional commands, e-mail:
