Updated Thu, 13 Sep 2001
 FAQ

Frequently Asked Questions about DocBook

1. Questions about the FAQ
Q:. What version of the FAQ is this?
2. General Questions about DocBook
Q:. What is DocBook?
Q:. What is SGML? What is XML? What is a DTD?
Q:. Where can I get DocBook?
Q:. What is the current version of DocBook?
3. Questions about the Modular DocBook Stylesheets
3.1. General Questions about the Stylesheets
Q:. What are the Modular DocBook Stylesheets?
Q:. Where can I get the Modular DocBook Stylesheets?
Q:. What is the current version of the stylesheets?
Q:. How do I create my own custom stylesheet?
3.2. Internationalization
Q:. What languages are supported by the Modular DSSSL Stylesheets?
Q:. What does support mean?
Q:. What if the language I need isn't supported?
Q:. How do I make the stylesheets use French (German, etc.)?

1. Questions about the FAQ

Q:. What version of the FAQ is this?
Q:.

What version of the FAQ is this?

A:.

This is $Revision: 1.1 $ from $Date: 2001/06/26 13:25:03 $.

2. General Questions about DocBook

Q:. What is DocBook?
Q:. What is SGML? What is XML? What is a DTD?
Q:. Where can I get DocBook?
Q:. What is the current version of DocBook?
Q:.

What is DocBook?

A:.

DocBook is an SGML DTD An XML version is also available.

DocBook is maintained by the DocBook Technical Committee of OASIS.

Q:.

What is SGML? What is XML? What is a DTD?

A:.

There are many sources of information about these general topics. Robin Cover's SGML/XML Web Page is a great place to start.

Q:.

Where can I get DocBook?

A:.

DocBook is available from OASIS at http://www.oasis-open.org/docbook/.

Q:.

What is the current version of DocBook?

A:.

DocBook version 4.1 is the current version. The current XML version is 4.1.2.

3. Questions about the Modular DocBook Stylesheets

3.1. General Questions about the Stylesheets
Q:. What are the Modular DocBook Stylesheets?
Q:. Where can I get the Modular DocBook Stylesheets?
Q:. What is the current version of the stylesheets?
Q:. How do I create my own custom stylesheet?
3.2. Internationalization
Q:. What languages are supported by the Modular DSSSL Stylesheets?
Q:. What does support mean?
Q:. What if the language I need isn't supported?
Q:. How do I make the stylesheets use French (German, etc.)?

3.1. General Questions about the Stylesheets

Q:. What are the Modular DocBook Stylesheets?
Q:. Where can I get the Modular DocBook Stylesheets?
Q:. What is the current version of the stylesheets?
Q:. How do I create my own custom stylesheet?
Q:.

What are the Modular DocBook Stylesheets?

A:.

The Modular DocBook Stylesheets are a popular way to format DocBook documents for print presentation (using TeX, RTF, or FrameMaker) or online presentation (using HTML).

They are DSSSL stylesheets. The acronym stands for Document Style Semantics and Specification Language. It is defined by ISO/IEC 10179:1996. For more general information about DSSSL, see the DSSSL Page.

The most common DSSSL engine is Jade, by James Clark. Jade is available for Unix and Windows platforms.

Q:.

Where can I get the Modular DocBook Stylesheets?

A:.

From http://nwalsh.com/docbook/dsssl/. They are maintained by Norman Walsh.

Q:.

What is the current version of the stylesheets?

A:.

See http://nwalsh.com/docbook/dsssl/ for the latest version information.

Q:.

How do I create my own custom stylesheet?

A:.

DSSSL allows one stylesheet to "use" another. The stylesheet inherits all of the properties of the stylesheet that it is using, but local definitions take precedence over imported ones.

The simplest custom stylesheet looks like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY docbook.dsl 
         PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
         CDATA DSSSL>
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

;; your (re)definitions go here

</style-specification-body>
</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>

This stylesheet customizes the print stylesheet. If you want to customize the HTML stylesheet, use the HTML stylesheet public identifier in the declaration of the docbook.dsl entity.

3.2. Internationalization

Q:. What languages are supported by the Modular DSSSL Stylesheets?
Q:. What does support mean?
Q:. What if the language I need isn't supported?
Q:. How do I make the stylesheets use French (German, etc.)?
Q:.

What languages are supported by the Modular DSSSL Stylesheets?

A:.

As of January, 1999: Danish, Dutch, English, Finnish, French, German, Italian, Norsk Bokm´┐Żl, Polish, Portuguese, Russian, Spanish, and Swedish.

In version 1.33 of the stylesheets, I changed the language codes to be ISO/RFC compliant. Old lang attribute values will continue to work, but the filenames have changed.

Q:.

What does support mean?

A:.

Primarily, it means that generated text (the words "Chapter" or "Table of Contents") will appear in the desired language. Language support also changes some punctuation in some languages.

Q:.

What if the language I need isn't supported?

A:.

Please create a localization for the language and contribute it! Supporting another language is not very difficult.

  1. Choose the abbreviation for the language. This should be the ISO language code plus the ISO country code. For example, XXYY.

  2. Copy the files dbl1en.ent and dbl1en.dsl in the common directory to dbl1XX.ent and dbl1XX.dsl.

  3. Translate the English words in dbl1XX.ent into the proper language.

  4. Change "en" to "XX" in dbl1XX.dsl. Make any other required changes.

  5. In common/dbl10n.dsl, add a new marked section for "XX" to each of the functions. Update html/dbl10n.dsl in the same way.

  6. In print/docbook.dsl and html/docbook.dsl, add a new parameter entity for XX, source it in, and add a new <external-specification> for it.

  7. Create dbl1XX.dsl in the print and html directories. Again, you can use dbl1en.dsl as a model.

  8. If you have any questions, ask Norman Walsh.

Q:.

How do I make the stylesheets use French (German, etc.)?

A:.

There are two ways: set the lang attribute to the language code of the desired language, or create a stylesheet that defines the default language.

Table 1. DocBook Stylesheet Language Codes

Language Code[a] Language
nl Dutch
en English
fr French
de German
it Italian
no Norwegian
pl Polish
pt Portuguese
ru Russian
es Spanish

[a] The desired form for language codes is the two-letter ISO standard language code. If the language is not unique (e.g., if you wanted to make a British English stylesheet), use the two-letter country code plus the language code, as described in RFC 1766.

For example, to make a Russian book, start your document with <book lang="ru">.

Alternatively, put

(define %default-language% "fr")

in your custom stylesheet.

Didn't find the answer to your question? Try the DocBook mailing list. To contribute a question to the FAQ, send mail to faq@docbook.org.

 

TOP OF PAGE