• WhatIsWrongWithDocBook

DocBook ain't perfect.

NormanWalsh recently published a couple of ruminations about a few DocBook's current shortcomings and on what it might develop into in the future (see the DocBookFuture page for details about that).

Implied in one of the articles, More Ruminations on DocBook, are a list of problems that includes:

• complexity of content models for inlines
• more metadata wrapper (*info) elements than needed
• "cruft" that really ought to just be discarded (e.g., beginpage,

  contractsponsor, invpartnumber, msgset, segmentedlist) or replaced/updated (sgmltag -> xmltag, link/ulink/olink -> ubiquitous linking)

...or, why I ended up creating my own online help markup language.

• Insane number of tags.

  • No re-use of tag names (i.e. separate tags for same content type in different contexts). e.g. sect1 and refsect1.
  • Use of synonyms (eg (set, division, component, section) or numbering (sect1, sect2, etc) to create levels of tags instead of recursion.

• Complexity of tags: too many "wrapper" tags (e.g. qandaentry) that can give extra information to styling tools (which may be necessary for tools less powerful than XSLT), but increase the difficulty of writing DocBook by hand.

• Geared toward printed documentation, not very well adapted to online help.

  • Book/chapter/appendix/etc. hierarchy not well suited to modern online help systems.
  • No concept of a "topic" (ie a division that represents the basic unit of help content).

• Complex procedures to extend/subset the language, poorly documented. Especially when subsetting the language is almost mandatory.

• Slow: geared towards a workflow of working on the book/help system as one gigantic file (through entity inclusion). Doesn't allow "partial compilation".

• Vestigial reference page concept not well integrated with current documentation practice.

• SGML legacy leads to increased complexity of distribution/usage.

  • --Matt Chaput

• Extensibility: the domains docbook is used in are full of domain-specific artifacts such as programming language specific entities ('class', 'function', etc.) or engineering related ('requirement', 'pattern', 'principle', etc.). It would be nice if docbook could provide means to let individual users / communities extend the vocabulary into such domains, without itself becoming a modeling tool.

  • --Stefan Seefeld

• Modularity: aside from 'simplified docbook', it is currently not possible to use some of docbook without getting all of docbook.

An alternative, modular design could make docbook available in smaller chunks targeted towards specific usages/users (e.g. those writing articles vs specifications vs faq). Such a design would have several important benefits, such as obviating the need for simplified docbook (freeing up resources currently tied up in maintaining this product and keeping it in synch with full docbook), making docbook simpler to understand and more accessible, and providing a natural set of fault lines for organizing tutorials and documentation. ModularDocbook

• --Craeg Strong

• Usability: I remain dumbfounded at the current obsession with separating formatting from structure, and the insane levels of complexity that it introduces. Writing a complex document in DocBook (eg., with footnotes, index, cross references, bibliography, conditional inclusion, mathematical equations, etc.) is vastly more difficult than writing the same document in TeX or LaTeX, and the results are far less pleasing. In the end is there really a benefit to separating formatting from structure when we all choose the structural elements that provide the desired formatting anyway? Ultimately markup is about formatting because no human wants to read the tags and no program exists to do anything useful with the markup tags other than convert them into formatting. --Mystified

Other shortcomings? ...