Missing where? [LWN.net]

Missing where?

Posted Sep 18, 2006 17:43 UTC (Mon) by JLCdjinn (subscriber, #1905)
In reply to: So far, so missing i18n by kreutzm
Parent article: A survey of the DocBook landscape

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.

(Log in to post comments)

Missing where?

Posted Sep 18, 2006 19:42 UTC (Mon) by kreutzm (subscriber, #4700) [Link]

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?

Posted Sep 18, 2006 21:56 UTC (Mon) by JLCdjinn (subscriber, #1905) [Link]

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