To render DocBook source code into the nice readable form the end-user willrequire, several tools are needed.  These tools allow the .dbk file to berendered into such formats as HTML, PDF, and PostScript.  This sectiondescribes the tools you need and the steps you take to render the Bochsdocumentation.</para><tip><para>The rendering process is one-way.  That is, the DocBook source files will be downloaded from CVS, edited, and uploaded to CVS as .dbk files.  Along theway, 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 theonly person to spend nine minutes trying to figure out how to 'compile' HTMLinto DocBook format.)</para></tip><sect1><title>Jade and DSSSL</title><para>Here is what the Linux Documentation Project says about jade:  <blockquote>  <attribution>  LDP author's guide  </attribution>  <para>  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.  </para>  </blockquote></para><para>What does all this mean?For purposes of Bochs documentation, jade reads the docbook source file andwrites out a HTML/PDF/PS file.  Bochs documentation is in SGML format, thoughapparantly jade can handle XML Docbooks as well.  DSSSL stands for <quote>Document Style Semantics and Specification Language</quote>, and ittells jade how to translate the docbook tags into the target format.  DSSSLfiles are written in the Scheme programming language, which is a variant ofLISP.  Learn more about DSSSL at <ulinkurl="http://www.jclark.com/dsssl">Jim Clark's DSSSL page</ulink>.The DocBook DTD is the formal description of what elements and attributes canbe used in a docbook.</para><sect2><title>Installation</title><para>The easiest way to get jade working in Linux is to install packages.  Therecent RedHat, Suse, and Mandrake Linux distributions all includeinclude 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 thathe installed on Mandrake to get jade working:<programlisting>  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</programlisting>Under Debian, the following packages seem to be a bare minimum to installDocBook and get it to render Bochs documentation into reader-friendly formats:<programlisting>  jade  docbook  docbook-dsssl</programlisting>It's worth mentioning that, at the time of this writing, at least some ofthe above-mentioned packages were in the testing or unstable branches ofDebian.</para><para>Hopefully, the required packages on other Linux distributions havesimilar names.  If you have jade working, please tell a documentationwriter the package names that you used so that we can include it in the docs.&NEEDHELP;</para><para>If you cannot get jade to work using packages, you need to find and installthree things: the DocBook DTD version 4.1 from &OASIS;, the program <ulink url="http://www.jclark.com/jade/">jade</ulink> (or <ulink url="http://openjade.sourceforge.net/">openjade</ulink>), and the<ulink url="http://sourceforge.net/projects/docbook/">Docbook DSSSLstylesheets</ulink> for the formats that you want to render to.  The wholeprocess is described in &docbookTDG; in Appendix III section A.  If you wantto render to PostScript or Adobe PDF, you also need to install TeX andand some associated tools.  It is a nontrivial process.</para><tip><para>Just use the packages.</para></tip><para>For now, building the Bochs documentation also depends on some scripts calleddocbook2html, docbook2pdf, and docbook2ps.  These come from the docbook-toolsproject at <ulink url="http://sources.redhat.com/docbook-tools">http://sources.redhat.com/docbook-tools</ulink>.</para></sect2><sect2><title>Using jade with docbook2x scripts</title><para>Check to see if you have the docbook2ps, docbook2pdf, and docbook2htmlscripts.  If so, you can probably use the Bochs Makefile.  Just do<programlisting>  cd $BOCHS/doc/docbook  make</programlisting>It should render three docbook books, one in user, one in development, and onein and documentation.  If there are no errors, look for the user guidein <filename>$BOCHS/doc/docbook/user/user.pdf</filename>,<filename>$BOCHS/doc/docbook/users/user.ps</filename>, and<filename>$BOCHS/doc/docbook/users/book1.html</filename>.  The HTML is brokeninto lots of little chunks that link to each other, but book1.html is the firstone.</para></sect2><sect2><title>Using jade directly</title><para>If you don't have docbook2<replaceable>format</replaceable> scripts, youcan 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 thatyou installed Norman Walsh's DSSSL stylesheets in <varname>$DSSSL</varname>.To render the user's guide into HTML, type:<programlisting>  cd $BOCHS/doc/docbook/user  jade -t sgml -d <varname>$DSSSL</varname>/html/docbook.dsl user.dbk</programlisting>Or, if you want to render the developer's guide into TeX format,<programlisting>  cd $BOCHS/doc/docbook/developer  jade -t tex -d <varname>$DSSSL</varname>/print/docbook.dsl developer.dbk</programlisting>Or, if you want to render the documentation guide into Rich Text Format,<programlisting>  cd $BOCHS/doc/docbook/documentation  jade -t rtf -d <varname>$DSSSL</varname>/print/docbook.dsl documentation.dbk</programlisting>I believe that the HTML stylesheet must have "-t sgml" but the printstylesheet in the second example can have "-t rtf" for Rich Text Format,"-t tex" for TeX, or "-t mif" for MIF.</para><para>Bochs has the convention of calling the docbook files<replaceable>name</replaceable>.dbk, but any file name would work.  Someother people call them <replaceable>NAME</replaceable>.sgm for SGML.</para></sect2></sect1><sect1> <title>Nsgmls</title><para>The Bochs documentation is written in SGML docbook style, so any tool which cancheck SGML syntax can be used to check the docbook.  The DTD (data typedescription) for docbook tells exactly which elements can be used and where.It says which attributes are required and which are optional, and how elementsshould be nested.  The term "validate" has a specific meaning in SGML.  Whenyou validate a SGML document, it means that you read the DTD and then checkthat the document conforms to all the rules of the DTD.</para><para>A program called nsgmls, written by James Clark <email>jjc@jclark.com</email>,can validate an SGML document such as our docbook.  Although nsgmls can do manyother things, this command will validate the docbook against the DTD whichdefines the syntax: <cmdsynopsis>  <command>nsgmls</command>  <arg choice="plain">-s</arg>  <arg choice="plain"><replaceable>filename</replaceable></arg></cmdsynopsis></para><para>Nsgmls is part of SP, a "free object-oriented toolkit for SGML parsing andentity management" by James Clark <email>jjc@jclark.com</email>.  SP can befound at <ulink url="http://www.jclark.com/sp">http://www.jclark.com/sp</ulink>.There is a complete man page for nsgmls <ulink url="http://www.jclark.com/sp/nsgmls.htm">here</ulink>.</para></sect1></chapter>   <!-- end Rendering chapter --></book>