OK, thanks Bob. I look forward to seeing the proposal for
the assembly process.
In my comment about DITA, I did not mean to imply that
there is nothing else about DocBook that is "better" than DITA, but I do
consider the topic-based vs. publication-based authoring to be the major
distinguishing characteristic. I'm just leery of turning DocBook into too much
of a Swiss-army knife, so that it loses its focus on what it's good
at.
************************* 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: Cavicchio_Rob@emc.com
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.
Hi Rob,
Thanks for your thoughts. The idea here is
to extend DocBook into the "bottom-up" approach by supporting standalone units
of information that can be assembled into larger units of publication.
What you have not yet seen is the proposal for the assembly process, because
the DocBook TC is still hashing that out. That proposal is forthcoming,
and then the discussion can be a bit more complete. The combination of
assembly and topic will allow those who are currently using section elements
as modules to instead use an element designed as a standalone
topic.
You ask "why not just use DITA?". I think
there are going to be lots of answers and discussions about that. Just
because someone wants to set their content up in a modular fashion does not
mean they have to use DITA, if there is a good alternative. This
proposal is for those who want to do modular content but don't need the
special features of DITA, or who prefer to use DocBook markup and
stylesheets.
----- Original Message -----
Sent: Wednesday, July 29, 2009 8:19
AM
Subject: RE: DocBook topic
element
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: Cavicchio_Rob@emc.com
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.
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 <bobs@sagehill.net>
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 bobs@sagehill.net
--------------------------------------------------------------------- To
unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org For
additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
|