DocBook DSSSL Stylesheet FAQ

Michael Wiedmann

mw@miwie.in-berlin.de

Revision History
Revision 0.0.18 2002-01-26

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no invariant sections, with no Front-Cover texts and no Back-Cover Texts.

Abstract

During the past few months I noticed that many questions on DocBook ML are repeated again and again. So it looks for me like it is really necessary to collect all these questions and the corresponding answers and make them publicly available to new DocBook users.

Because the whole thing is about DocBook some members of the DocBook ML suggested to use DocBook's QandASet for this purpose. Quoting Nik Clayton: "so that there's one more example of good DocBook markup available for people to copy from."

I began to collect these questions and answers on 2001-04-20 and made this FAQ publicly accessible at http://www.miwie.org/docbook-dsssl-faq.html.

DocBook users are encouraged to email their questions (and hopefully the corresponding answers as well) to me so that this FAQ will grow and become more valuable for all of us.


1. FAQ

1. General
Q: How do I customize the default stylesheets?
Q: How do I include images?
Q: How do I center images in print output?
Q: Which tools are best for converting graphic files to other formats?
Q: How do I generate an index?
2. HTML
Q: How do I generate chunked output?
Q: How do I change the appearance of <emphasis>?
3. Text
Q: How do I generate text version of my document?
4. PDF and/or PS
Q: Where do I find the user customizable variables?
Q: How do I set the paper type?
Q: How do I get justified output?
Q: How do I generate entries in the PDF Document Info?
Q: How do I generate bookmarks?
Q: How do I show the bookmark entries expanded?
Q: How do I control the level of expanded bookmark subtrees?
Q: How do I change the link appearance from boxed to coloured?
Q: How do I change the link colour?
Q: How do I influence hyphenation?
Q: How do generate two sided output?
Q: How do I markup very long URLs?
5. Miscellaneous
Q: How do I generate output for PalmPilot?
6. Documentation
Q: Where do I find more documentation?
Q: Where can I find DocBook examples?

1. General

Q: How do I customize the default stylesheets?

A: In chapter 4 of DocBook; TDG you'll find a section covering this topic.

In short: write your own driver file, e.g.:

    <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
    <!ENTITY html-ss
      PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
    <!ENTITY print-ss
      PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl>
    ]>
    
    <style-sheet>
    <style-specification id="print" use="print-stylesheet">
    <style-specification-body> 
    
    ;; customize the print stylesheet
    
    </style-specification-body>
    </style-specification>
    <style-specification id="html" use="html-stylesheet">
    <style-specification-body> 
    
    ;; customize the html stylesheet
    
    </style-specification-body>
    </style-specification>
    <external-specification id="print-stylesheet" document="print-ss">
    <external-specification id="html-stylesheet" document="html-ss">
    </style-sheet>
and use this stylesheet file for processing your source file with (open)jade (providing the stylesheet pathname as a command line option like -d ./mystyle.dsl). Choose the corresponding part for HTML or print output by setting the variable print or html using the command line option -i (e.g. -i print).

Q: How do I include images?

A: tbd.

Q: How do I center images in print output?

A: Add the following to your customization stylesheet:

    (element imagedata
      (if (have-ancestor? (normalize "mediaobject"))
        ($img$ (current-node) #t)                 
        ($img$ (current-node) #f)))
(This is a bug in the default stylesheets which will be resolved in the near future)

Q: Which tools are best for converting graphic files to other formats?

A: There are for sure many possible solutions, but most people would like to try convert from the ImageMagick package.

Q: How do I generate an index?

A: Very short description:

  • Mark your entries for the index using the DocBook tags <indexterm>, <primary>, etc.

  • Generate an empty index file using collateindex.pl -N.

  • Generate the raw index data using (open)jade with the option -V html-index.

  • Process the raw index data usaing a command like collateindex.pl -o index.sgml HTML.index.

  • Include this generated index file in your SGML source file, e.g. using an external entity:

        <!DOCTYPE article ....
         <!entity index SYSTEM "index.sgml">
        ]>
    
    and put the following line at the place you want the index to appear in your document:
        &index;
    


  • Generate the desired output format as usual.



2. HTML

Q: How do I generate chunked output?

A: In general you switch between chunked and nochunked output by setting the variable nochunks to #t or #f. This can be achieved in your customization stylesheet or simply by adding -V nochunks on the (open)jade command line.

Q: How do I change the appearance of <emphasis>?

A: The <emphasis> tag is rendered by the default HTML stylesheet as italic (<I>). If you want to change the appearance you have to do this in your customization layer. Jirka Kosek proposed the following solution recently on DocBook-Apps ML:

    (element emphasis
    (if (equal? (normalize "bold") (attribute-string (normalize "role")))
        ($bold-seq$)                                                     
        ($italic-seq$)))
This solution looks at the role attribute and uses the <B> HTML tag to render <emphasis> if this attribute is set to bold.

3. Text

Q: How do I generate text version of my document?

A: Generate a HTML version first and convert with lynx or w3m like:

    w3m -T text/html -dump DOCUMENT.html > DOCUMENT.txt


4. PDF and/or PS

Q: Where do I find the user customizable variables?

A: The default styleheet files contain two files (for HTML and print output) named dbparam.dsl. Locate these files and look carefully over them. A few of the user customizable variables are mentioned below.

Q: How do I set the paper type?

A: Set the following in your customization stylesheet:

    (define %paper-type% "A4")
The default stylesheet sets this to "USletter".

Q: How do I get justified output?

A: Set the following in your customization stylesheet:

    (define %default-quadding% 'justify)
(the default stylesheet sets this to 'start, which means left-justified).

Q: How do I generate entries in the PDF Document Info?

A: Create a file jadetex.cfg in your working directory which looks like:

    \hypersetup{pdftitle={Some Title},
                pdfsubject={Some Subject},
                pdfauthor={Some Author}
               }
You should consult the documentation of hyperref.sty for a complete and more detailled description of the possible configuration options.

Q: How do I generate bookmarks?

A: Perform the following steps (works with at least V1.69 of the DSSSL stylesheets):

  • Use openjade to process your SGML file

  • Use a line like pdfpagemode=UseOutlines in your jadetex.cfg file (See How do I generate entries in the PDF Document Info? for the general layout of the file jadetex.cfg)

  • If you are writing a <book> include the following lines in your customization layer:

        (declare-characteristic heading-level
          "UNREGISTERED::James Clark//Characteristic::heading-level" 2)
    
    If you are writing an <article> don't use these lines.



Q: How do I show the bookmark entries expanded?

A: Use the following line in your jadetex.cfg file:

    bookmarksopen=true
(See How do I generate entries in the PDF Document Info? for the general layout of the file jadetex.cfg)

Q: How do I control the level of expanded bookmark subtrees?

A: Use the following line in your jadetex.cfg file:

    bookmarksopenlevel=level
and choose an appropriate value for level (See How do I generate entries in the PDF Document Info? for the general layout of the file jadetex.cfg).

Q: How do I change the link appearance from boxed to coloured?

A: Use the following line in your jadetex.cfg file:

    colorlinks=true
(See How do I generate entries in the PDF Document Info? for the general layout of the file jadetex.cfg)

Q: How do I change the link colour?

A: Use the following line in your jadetex.cfg file:

    linkcolor=blue
and choose an appropriate value for linkcolor. For this to work you have to set colorlinks=true too (and remember that entries in jadetex.cfg have to be comma separated - not white space separated! See How do I generate entries in the PDF Document Info? for the general layout of the file jadetex.cfg).

Q: How do I influence hyphenation?

A: The file jadetex.cfg can contain TeX code, so one possible solution is to specify the words you wish to hyphenate in jadetex.cfg in a special way like:

    \hyphenation{hyph-enate-me}
(See How do I generate entries in the PDF Document Info? for the general layout of the file jadetex.cfg).

Q: How do generate two sided output?

A: Set the following in your customization stylesheet:

    (define %two-side% #t)
(this is set already in the default stylesheet files).

Q: How do I markup very long URLs?

A: Use ulink and read the paper Correcting page make-up problems in SGML-based documentation which describes some very useful customization techniques used by Mandrake.

5. Miscellaneous

Q: How do I generate output for PalmPilot?

A: If you want to support AportisDoc convert your SGML source file to TXT first and convert with a command like: makedoc DOCUMENT.txt DOCUMENT.prc

If you want to support iSilo convert your SGML source file to HTML first and convert with a command like: iSilo386 -y -d0 -Idef DOCUMENT.html DOCUMENT.pdb

Carsten Wartmann pointed me to the following tools, which can convert TXT/HTML files to PalmPilot DOC format: txt2pdbdoc and html2pdbtxt.

6. Documentation

Q: Where do I find more documentation?

Q: Where can I find DocBook examples?

A: Mark Johnson posted among others the following links recently on DocBook-Apps ML:



Nik Clayton contributed the following examples:



Dave Brooks pointed me to the DSSSL customization files of the FreeBSD Documentation Project:



Dan York contributed the following examples:



Dave Pawson maintains the DocBook FAQ:




A. Credits

The following people have contributed substantial parts to this document:




B. About...

This document was processed using the following tools: