OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [docbook] Add topic element to DocBook?

Comments inline..


-----Original Message-----
From: chris.chiasson@gmail.com [mailto:chris.chiasson@gmail.com] On Behalf Of Chris Chiasson
Sent: Friday, October 27, 2006 8:51 AM
To: Johnson, Eric
Cc: docbook@lists.oasis-open.org
Subject: Re: [docbook] Add topic element to DocBook?


I haven't checked this, but I think section is not allowed as a root

element. This means that documents beginning with <section> will

require a DocBook schema customization to validate. I have had this

problem with documents that begin with <equation>.


Maybe it would be better if someone who actually wants <topic> to make

a case for it?






Topic - as we're discussing here - is a semantically meaningful standalone piece of content..


It greatly facilitates modular writing, where we're not just focused on books but individual units of information.. The style of writing in the book changes from being a single flow from beginning-to-end to instead be a collection of topics.. This allows organizations (I work at Juniper), to provide their content in book form as well as searchable topics on the web or for re-use of content elsewhere.


Does that make a high-level case for having <topic>?


Having said that, once we move to the topic world, people will need have the need for their own topic types.. For e.g. at Juniper we have: <command-summary>, <verification-task>, <example>, <procedure>, <trouble-shooting> etc.. The reason is that once we agree on the idea of standalone topics/modular writing, semantically meaningful topic elements and their structure gets important for authors - who are now assigned to topics and not be a book-owner as such.. I am hoping that DocBook can standardize some of them too at some point.. J








[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]