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] Ruminations on the future of DocBook


Conceptually in programming there is the main program (routine) and smaller modules that are called from the main program (subroutine). Therefore why couldn't the DocBook DTD have been simplified through the use of <subroutine role=method> for java and <subroutine role =function> for C? There may be a lot to be gained from using element names that define what something is generically (subroutine) rather than what it is called specifically in any given instance (function).

Would namespace allow this type of generalization? I have an idea of what a namespace but not that precise.

Jeff Biss

Adam Turoff wrote:
On Fri, May 30, 2003 at 09:19:35AM -0400, Stefan Seefeld wrote:
Yeah, I would very much like to see a discussion of all the different
domains docbook can be applied to ('use cases'), together with domain
specific vocabularies. Based on this one may be able to either unify
these vocabularies, or create a 'standard' vocabulary with a set of
'profiles'. I think that this is what we are doing informally right now
when arguing over task vs. process vs. procedure.

I think using DocBook V.next to make the one canonical vocabulary
for technical documentation is a fundementally bad move. Enumerating
all possible use cases would be a huge effort to wind up where we
are today.

Look at XHTML. For all of its warts, it does one thing well: provide a
stable foundation for the 20 or so tags people generally use for
presentation markup. The modularization of XHTML is a nice thing,
conceptually, but the uptake has been rather lukewarm at best. The only
extensions of XHTML I've seen have all been through comingling elements
from different namespaces together in one document.

The DocBook TC is never going to be able to come to a definitive conclusion
on the 'one true tag name' for a certain domain of document structures.
There will be instances where 'task' has a very clear meaning and content
model for some rather important class of documentation, and 'process' has
a totally different semantic meaning and content model for an equally
important yet different class of documentation.

So I think the *best* thing DocBook V.next could do would be to identify
the 100 or so most common structural elements and content models that are
*universal* and then standardize extensions via namespaces. Then, as
someone writing Perl documentation, I could ignore the C/C++/Java centric
tags on methods and classes and use similar elements that are better suited
to documenting Perl that most of the world will happily ignore.

By focusing on the most common structures, it also becomes easier to
learn and extend DocBook by properly labeling "elements I probably don't
care about" as extensions. :-)

Just $0.02,


To unsubscribe, e-mail: d ocbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org

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