DocBook topic element

[Bob Stayton]

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@...



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Ron Catterall]

Sounds not only very interesting, but very usefull. I'll give it a try.

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
> bobs@...
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@...
> For additional commands, e-mail: docbook-apps-help@...
>
>
>

--
Ron Catterall Ph.D. D.Sc.
ron@...
http://catterall.net

[Bergfrid Skaara]

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@...> 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@...



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[David Cramer (Tech Pubs)]

This does look very intersting. I gather this portion only relates to
the new topic element and the assembly structure will come later?

I second Bergfrid's request that there be some mechanism(s) for avoiding
the intertopic dependencies created by crossreferences (i.e. the problem
that dita reltables are supposed to solve).

Thanks,
David

> -----Original Message-----
> From: Bob Stayton [mailto:bobs@...]
> Sent: Saturday, July 25, 2009 12:00 PM
> To: DocBook Apps; docbook@...
> Subject: [docbook] DocBook topic element
>
> 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@...
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@...
> For additional commands, e-mail: docbook-help@...
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Cavicchio_Rob]

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: [phone]
F: [phone]
E: Cavicchio_Rob@...

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:bergfrid.digitaldias@...]
Sent: Monday, July 27, 2009 5:44 AM
To: Bob Stayton
Cc: DocBook Apps; docbook@...
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 <bobs@...> 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@...



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Bob Stayton]

Some parts of this message have been removed. Learn more about Nabble's security policy.

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.

 

Bob Stayton
Sagehill Enterprises
bobs@...

 

 

----- Original Message -----

From: Cavicchio_Rob@...

To: bergfrid.digitaldias@... ; bobs@...

Cc: docbook-apps@... ; docbook@...

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: [phone]
F: [phone]
E: Cavicchio_Rob@...

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:bergfrid.digitaldias@...]
Sent: Monday, July 27, 2009 5:44 AM
To: Bob Stayton
Cc: DocBook Apps; docbook@...
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 <bobs@...> 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@...



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Cavicchio_Rob]

Some parts of this message have been removed. Learn more about Nabble's security policy.

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: [phone]
F: [phone]
E: Cavicchio_Rob@...

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: Bob Stayton [mailto:bobs@...]
Sent: Wednesday, July 29, 2009 11:28 AM
To: Cavicchio, Rob; bergfrid.digitaldias@...
Cc: docbook-apps@...; docbook@...
Subject: Re: DocBook topic element

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.

 

Bob Stayton
Sagehill Enterprises
bobs@...

 

 

----- Original Message -----

From: Cavicchio_Rob@...

To: bergfrid.digitaldias@... ; bobs@...

Cc: docbook-apps@... ; docbook@...

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: [phone]
F: [phone]
E: Cavicchio_Rob@...

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:bergfrid.digitaldias@...]
Sent: Monday, July 27, 2009 5:44 AM
To: Bob Stayton
Cc: DocBook Apps; docbook@...
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 <bobs@...> 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@...



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Bergfrid Skaara]

Hi,

On Wed, Jul 29, 2009 at 8:28 PM, Bob Stayton <bobs@...> wrote:

-snip-

 

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.

 

Bob Stayton
Sagehill Enterprises
bobs@...

 

I could not agree more. We want to do modular documentation, and are required to publish PDFs. Customizing DITA to get decent and accepptable looking PDFs is extremely hard, and we do not want to venture down that road. DocBook's stylesheets, the new RelaxNG schemas, and the solid documentation for customizing them are superior.

 

As Adobe said when I asked about DocBook 5 support in FrameMaker: "We have chosen DITA [and abandoned DocBook] because our focus is light-weight documentation and HTML-publishing."

 

Best regards,

Bergfrid Skaara

[Ron Catterall]

I'm in full agreement with Bergfrid, keep <topic> in there, Docbook 5 is
the way to go.
I was also horrified at the comment from Adobe on Docbook 5 support in
Framemaker.  But I suppose that confirms that Framemaker is aimed at the
lower end of the market, not for professionals.
Ron

Bergfrid Skaara wrote:

> Hi,
>
> On Wed, Jul 29, 2009 at 8:28 PM, Bob Stayton <bobs@...
> <mailto:bobs@...>> wrote:
>
>     -snip-
>      
>     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.
>      
>     Bob Stayton
>     Sagehill Enterprises
>     bobs@... <mailto:bobs@...>
>
>  
> I could not agree more. We want to do modular documentation, and are
> required to publish PDFs. Customizing DITA to get decent and accepptable
> looking PDFs is extremely hard, and we do not want to venture down that
> road. DocBook's stylesheets, the new RelaxNG schemas, and the solid
> documentation for customizing them are superior.
>  
> As Adobe said when I asked about DocBook 5 support in FrameMaker: "We
> have chosen DITA [and abandoned DocBook] because our focus is
> light-weight documentation and HTML-publishing."
>  
> Best regards,
> Bergfrid Skaara

--
Ron Catterall Ph.D. D.Sc.
ron@...
http://catterall.net

[Cavicchio_Rob]

Ha. Well, I wrote the original comment about using DITA and was trying to get a grasp on the intended nature of the proposed markup. I publish Help files from DocBook without any problems right now; a <section> *is* a topic as far as I'm concerned.

 

I think that how difficult it is to get "acceptable looking" output is beside the point. There is the XML syntax and then there are the applications that process it. I prefer to separate the two and decide what makes logical sense for the markup before then deciding how best to publish it.

 

 

---

From: Bergfrid Skaara [mailto:bergfrid.digitaldias@...]
Sent: Thursday, September 10, 2009 4:56 AM
To: Bob Stayton; docbook-apps@...
Subject: Re: DocBook topic element

Hi,

On Wed, Jul 29, 2009 at 8:28 PM, Bob Stayton <bobs@...> wrote:

-snip-

 

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.

 

Bob Stayton
Sagehill Enterprises
bobs@...

 

I could not agree more. We want to do modular documentation, and are required to publish PDFs. Customizing DITA to get decent and accepptable looking PDFs is extremely hard, and we do not want to venture down that road. DocBook's stylesheets, the new RelaxNG schemas, and the solid documentation for customizing them are superior.

 

As Adobe said when I asked about DocBook 5 support in FrameMaker: "We have chosen DITA [and abandoned DocBook] because our focus is light-weight documentation and HTML-publishing."

 

Best regards,

Bergfrid Skaara