Bochs Documentation Manual
PrevNext

Chapter 4. Reading and Writing

The DocBook source code -- user.dbk, for example -- is a plain text file that can be directly edited and saved with any text editor such as emacs or vi.

Tip: If you just want to read the documentation, you should not need to read and understand this section, and render the docs yourself. The Bochs web site has all this information in readable form already.

To render DocBook source code into the nice readable form the end-user will require, several tools are needed. These tools allow the .dbk file to be rendered into such formats as HTML, PDF, and PostScript. This section describes the tools you need and the steps you take to render the Bochs documentation.

Tip: The rendering process is one-way. That is, the DocBook source files will be downloaded from SVN, edited, and uploaded to SVN as .dbk files. Along the way, it will probably be necessary to render them into HTML, but only to check one's work or to post them as part of a web page. (I hope I'm not the only person to spend nine minutes trying to figure out how to 'compile' HTML into DocBook format.)

4.1. Jade and DSSSL

Here is what the Linux Documentation Project says about jade:

 

Jade is the front-end processor for SGML and XML. It uses the DSSSL and DocBook DTD to perform the verification and rendering from SGML and XML into the target format.

 
-- LDP author's guide  

What does all this mean? For purposes of Bochs documentation, jade reads the docbook source file and writes out a HTML/PDF/PS file. Bochs documentation is in SGML format, though apparantly jade can handle XML Docbooks as well. DSSSL stands for "Document Style Semantics and Specification Language", and it tells jade how to translate the docbook tags into the target format. DSSSL files are written in the Scheme programming language, which is a variant of LISP. Learn more about DSSSL at Jim Clark's DSSSL page. The DocBook DTD is the formal description of what elements and attributes can be used in a docbook.

4.1.1. Installation

The easiest way to get jade working in Linux is to install packages. The recent RedHat, Suse, and Mandrake Linux distributions all include openjade and SGML tools. If you can get the right packages installed, you may save yourself a few hours of compiling and configuring from scratch. For plex86, which also uses docbook, Kevin Lawton listed the packages that he installed on Mandrake to get jade working: 

  jadetex-3.5-2mdk
  openjade-1.3-10mdk
  docbook-dtd31-sgml-1.0-3mdk
  docbook-utils-0.6-1mdk
  docbook-style-dsssl-1.62-4mdk
  docbook-dtd412-xml-1.0-3mdk
  sgml-common-0.2-4mdk
  xml-common-0.1-3mdk
Under Debian, the following packages seem to be a bare minimum to install DocBook and get it to render Bochs documentation into reader-friendly formats: 
  jade
  docbook
  docbook-dsssl
It's worth mentioning that, at the time of this writing, at least some of the above-mentioned packages were in the testing or unstable branches of Debian.

Under FreeBSD, just install the following ports: 

  textproc/jade
  textproc/dsssl-docbook-modular
  textproc/docbook-410

Hopefully, the required packages on other Linux distributions have similar names. If you have jade working, please tell a documentation writer the package names that you used so that we can include it in the docs.

If you cannot get jade to work using packages, you need to find and install three things: the DocBook DTD version 4.1 from OASIS, the program jade (or openjade), and the Docbook DSSSL stylesheets for the formats that you want to render to. The whole process is described in DocBook: The Definitive Guide in Appendix III section A. If you want to render to PostScript or Adobe PDF, you also need to install TeX and and some associated tools. It is a nontrivial process.

Tip: Just use the packages.

For now, building the Bochs documentation also depends on some scripts called docbook2html, docbook2pdf, and docbook2ps. These come from the docbook-tools project at http://sources.redhat.com/docbook-tools.

4.1.2. Using jade with docbook2x scripts

Check to see if you have the docbook2ps, docbook2pdf, and docbook2html scripts. If so, you can probably use the Bochs Makefile. Just do 

  cd $BOCHS/doc/docbook
  make
It should render three docbook books, one in user, one in development, and one in and documentation. If there are no errors, look for the user guide in $BOCHS/doc/docbook/user/user.pdf, $BOCHS/doc/docbook/users/user.ps, and $BOCHS/doc/docbook/users/book1.html. The HTML is broken into lots of little chunks that link to each other, but book1.html is the first one.

4.1.3. Using jade directly

If you don't have docbook2format scripts, you can also run jade manually. The command is long, so you may want to make your own script or edit your copy of the makefile. These commands assume that you installed Norman Walsh's DSSSL stylesheets in $DSSSL. To render the user's guide into HTML, type: 

  cd $BOCHS/doc/docbook/user
  jade -t sgml -d $DSSSL/html/docbook.dsl user.dbk
Or, if you want to render the developer's guide into TeX format, 
  cd $BOCHS/doc/docbook/developer
  jade -t tex -d $DSSSL/print/docbook.dsl developer.dbk
Or, if you want to render the documentation guide into Rich Text Format, 
  cd $BOCHS/doc/docbook/documentation
  jade -t rtf -d $DSSSL/print/docbook.dsl documentation.dbk
I believe that the HTML stylesheet must have "-t sgml" but the print stylesheet in the second example can have "-t rtf" for Rich Text Format, "-t tex" for TeX, or "-t mif" for MIF.

Bochs has the convention of calling the docbook files name.dbk, but any file name would work. Some other people call them NAME.sgm for SGML.

4.1.4. Configuration

If the generated HTML files do not have the same names as the Bochs documentation on the web, some kind of configuration is required. You need to edit the DSL file to make sure the following settings are used. 

(define %root-filename% "index")        ;; name for the root html file
(define %html-ext% ".html")             ;; default extension for html output files
(define %html-prefix% "")               ;; prefix for all filenames generated (except root)
(define %use-id-as-filename% #t)        ;; if #t uses ID value, if present, as filename
                                        ;;   otherwise a code is used to indicate level
                                        ;;   of chunk, and general element number
                                        ;;   (nth element in the document)
(define use-output-dir #f)              ;; output in separate directory?

If you like to have the screen sections shaded, this setting should help. 

(define %shade-verbatim% #t)

PrevHomeNext
Conventions Nsgmls