LWN: Comments on "A survey of the DocBook landscape"

OASIS Standard

JLCdjinn — Tue, 10 Nov 2009 20:36:29 +0000

And over three years later (as of 2009-11-02), DocBook 5 is now an OASIS Standard.

DocBook 5.0 finalized

JLCdjinn — Fri, 08 Feb 2008 00:42:58 +0000

DocBook 5 will likely have a stable release soon.

Clearly, by "soon" I meant 17 months. Ahem. My prognostication abilities leave something to be desired. In any case, DocBook 5.0 has been finalized (that is, approved as a committee draft) as of 2008-02-06! And there was much rejoicing!

When I wrote this article, DocBook 5 was at beta 7; after two more betas, it also went through 7 release candidates before arriving at 5.0 final. There were a number of bug fixes and minor enhancements, but the overall DocBook architecture is largely the same as described in this article. For all the gory details, check out the change log.

Missing where?

JLCdjinn — Mon, 18 Sep 2006 21:56:17 +0000

I use docbook2man to create man pages.
If there are better tools (not ideas) for transforming a docbook file to a man page I will certainly have a look.

Some casual poking around the Internet leads me to believe that the DocBook XSL stylesheets seem to be a better-supported solution than docbook2man. For example, I created a simple DocBook-formatted man page with the lang="ru" attribute set on the root element. I then ran xsltproc http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl manpage.docbook, and the resulting troff source contains Russian section headings (although I cannot speak at all to their accuracy, not being able to speak Russian and all). Any incompleteness or inaccuracy in a particular l10n should be fixed through the DocBook XSL stylesheets project.

Granted, after generating the UTF-8 troff source, I was unable to actually view the Russian headings in a formatted man page, but that's a different story...

Missing where?

kreutzm — Mon, 18 Sep 2006 19:42:35 +0000

I use docbook2man to create man pages. You can read the entire problem including my patch and attempts to reach the author or Debian maintainer at my bug report regarding this issue.

The first of your items sounds interesting, but from a practical point of view (i.e. for applications I envisage) having all languages in one file does not look optimal. The second paragraph is exactly the one describing my problem. If there are better tools (not ideas) for transforming a docbook file to a man page I will certainly have a look. The third paragraph describes an issue I have not thought about. First, of course, as I speak english but secondly because I treat docbook like a programming language - you'll have to know the tags/keywords to get your work done. It's very interesting, though, that there are solutions for this, even. Hopefully it'll work even if documents are interchanged.

Missing where?

JLCdjinn — Mon, 18 Sep 2006 17:43:39 +0000

There are issues here at a variety of levels that usually include DocBook (the language) as well as tools that process DocBook. First, you (in the generic sense) may want to write the same text in several different languages in the same document. This is called profiling, and DocBook has facilities for profiling such as the lang and os attributes. DocBook XSL: The Complete Guide has a chapter called "Profiling (conditional text)" that talks about these issues both in DocBook as well as support for these features in the DocBook XSL stylesheets.

It sounds like you may also be interested in i18n (internationalization) support with respect to automatically generated portions of an output document. Clearly, such support is the responsibility of tools that process DocBook. Again, DocBook XSL: The Complete Guide provides a thorough treatment of the way in which the DocBook XSL stylesheets allow for language-specific generated content in its section titled "Language support".

One criticism that you might level against DocBook (and many XML dialects) is the choice of language (usually English) for their tag names. Clearly element names like article and section only have meaning to those who understand English. A problem like this must be solved at the XML level; one possible solution is the DSRL (Document Schema Renaming Language) approach. See the DSRL documents on the DSDL (Document Schema Definition Languages) web site for details.

It would be interesting to learn what tools you are using in order to try to fix the problem with those tools.

So far, so missing i18n

kreutzm — Sun, 17 Sep 2006 20:14:57 +0000

I really like docbook, but what is severly missing is i18n. I wrote several man pages in german, but the transformation to nroff insists on using english terms and conventions. Writing to the upstream authors or opening bugs (with patches!) in the bug tracker of my distribution did not cause any response. I hope future versions of docbook deal with this deficiency.