DocBook is a very popular SGML and XML format for writing documentation, especially computer related documents.

The DocBook project releases a set of XSLT stylesheets that can transform any XML document that conforms to the DocBook DTD in multiple formats:

• HTML
• XHTML
• XML FO, and from here to PDF using something like Apache FOP

GNU Emacs and XEmacs are very powerful editors, and with the help of XSLT-process and PSGML, you can transform them into a complete DocBook editing and processing system.

Note: To be able to process DocBook documents, you need to use XSLT-process version 2.1 or higher.

There are few steps that need to be followed.

1. Download and install the PSGML package. If you're using XEmacs, chances are PSGML is already installed on your system.

   To test if you already have PSGML installed, open an XML file and type:

   M-x xml-mode RET

   M-x stands for the key x typed while holding down the Alt key, and RET stands for the key RETURN or ENTER. Similarly, something like C-c, means the key c typed while holding down the Control key.

   If you get any error or if hitting RET produces a beep, you don't have the PSGML mode installed. Follow the PSGML installation instructions described in the PSGML manual posted at its home page, and come back here when you're done.

2. Download and install the latest version of the DocBook-XSL distribution package.

   Unarchive this package in a convenient place on you machine. One such place might be /usr/local/share, if you have the right permissions. Otherwise any other directory should do it.

      cd /usr/local/share
      gunzip -c docbook-xsl-x.xx.tar.gz | tar xf -
    

   or if you're using the GNU tar (Linux comes with GNU tar):

      cd /usr/local/share
      tar zxf docbook-xsl-x.xx.tar.gz
    

3. After you installed the DocBook package, you need to make XSLT-process aware of its location. In your Emacs, type

      M-x xslt-process-install-docbook RET
    

   This will ask you for the directory where the DocBook package is installed. If you installed it in /usr/local/share, you should then enter:

      /usr/local/share/docbook-xsl-x.xx
    

   Or if you have XSLT-process already installed, open an XML file, and choose the "XSLT" => "Customize" => "DocBook location" menu item. This will prompt you for the directory where DocBook is installed.

   Registering DocBook with XSLT-process automatically registers the HTML and XML FO stylesheets within the XSLT-process' stylesheet registry. To see how this is useful, please read on.

4. At this point, you're ready to start editing and formatting your own DocBook document! I assume of course you have already installed XSLT-process on your Emacs editor. If you have not done so, please follow the steps described in the XSLT-process' documentation, or take a look at the quick setup page.

   You can now open a DocBook XML file in your Emacs editor. If you don't have one already, you can start with the docbook-example.xml file (Shift-click to save it).

   After you open a DocBook file, you can associate a stylesheet with it. You do this by typing C-c C-x a, which will bring up a buffer with all the stylesheets registered with XSLT-process. If you want to see how the HTML page looks like, you need to associate the DocBook file with the /docbook/install/dir/html/docbook.xsl. If you're interested in the PDF version, you need to associate it with /docbook/install/dir/fo/docbook.xsl.

   After you associate the DocBook file with a stylesheet, you can process the file from within Emacs. Just type C-c C-x n to view the processed file in a Web browser, or C-c C-x p to view the file in a PDF viewer.

   Note: If the DOCTYPE of the DocBook document references the DTD document using http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd, the DTD and the supporting files will be referenced and downloaded every time you process the DocBook document. This may be a problem if you don't have access to the Internet or you have a slow connection.

   A better solution is to create a local copy of the DocBook DTD files. To do this go to http://www.oasis-open.org/docbook/xml/4.1.2/ and download the ZIP file containing the DocBook DTD. Put it in an accesible place on your file system, for example in /usr/local/share/docbook-4.1.2. Then modify the DOCTYPE of your DocBook documents to be:

      <!DOCTYPE book
       PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
       "file:/usr/local/share/docbook-4.1.2/docbookx.dtd">
    

1. There are some annoyances with the above way of processing a DocBook document. The problem is that when you want to switch between the Web browser and the PDF viewer, you will need to change the associated stylesheet. I'm thinking to associate the notion of a stylesheet type with a stylesheet in the registry. An XML file could then have multiple stylesheets associated with it, each one generating a different output. The XSLT-process mode would then decide which one to use based on the action invoked by the user.

   For example, one could associate with a DocBook file both the HTML and FO DocBook stylesheets. The XSLT-process mode would automatically apply the HTML stylesheet if you invoke C-c C-x n (view in browser), or it will choose the FO stylesheet if you invoke C-c C-x p (view PDF).

2. Would be nice to have XSLT-process mode detect a DocBook file (based on the DOCTYPE) and automatically associate the DocBook XSL files with it. DocBook processing would then be as simple as choosing "View in Browser" or "View PDF" menu items!