%bochsdefs; ]> Bochs Documentation Manual BryceDenney MichaelCalabrese Layout of Bochs Documentation The Bochs documentation is divided into three major divisions: The User's Guide introduces the Bochs Emulator, and covers installation and use. Developer's Guide: Describes the internals of the Bochs Emulator for developers. Documentation Guide: Describes how the documentation is organized, and how to render it, and how to add to it. This section is in the documentation guide. In docbook terminology, each of the three divisions is a book. Inside each book are a series of chapters. A chapter may be divided into sections, and each section is divided into more sections. Eventually we will add fancy things like a table of contents, index, and glossary, when we learn how. Docbook Basics Some of the most commonly used docbook patterns are described here for quick reference. For all the details (sometimes more than you wanted), try &docbookTDG; by Norman Walsh and Leonard Muellner, which O'Reilly & Associates has generously placed on their web site. In this section, many of the SGML tags are linked to the page of Walsh's book that describes that tag in detail.
Small Tutorial Docbook files are text files containing SGML. If you have ever looked at HTML, then a docbook file will look familiar. Not the same, but familiar. The easiest way of getting familiar with the docbook format is by looking at examples such as the Bochs documentation itself. When you compare the source code to the rendered documentation on the web site, it will be pretty obvious what all the codes are doing. HTML is very forgiving about breaking the syntax rules, such as not putting </h1> at then end of an <h1> section. SGML is picky; if you forget that kind of thing in SGML, it will insist that you fix it. Every paragraph must begin with the <para> tag and end with the corresponding end tag, </para>. <para> This is a paragraph. </para> A chapter looks like this: <chapter> <title>title of the chapter</title> text of the chapter </chapter> The text of the chapter must contain at least one complete <para> tag, and it can include <section>s. A section looks like this: <section> <title>title of the section</title> text of the section </section> The text of the section must contain at least one complete <para> tag, and it can include other <section>s. To make a link to any URL, use the syntax: <ulink url="URL">text of the hyperlink</ulink> However, if you like to link to another target inside the same document, for example to a section, use something like that: <section id="unique identifier"> All stuff that is needed here... </section> ... <link linkend="unique identifier to link to">text of hyperlink</link> To include a picture in the text, use the <graphic> tag. In SGML, this graphic tag has no closing tag. <graphic format="fmt" fileref="filename"> The fmt can be one of many formats including GIF, JPG, PNG, PS, and EPS. The filename should be on the local disk. If there is a pathname, it should be relative to the source file or it won't be found on anyone's system other than yours. There are over 300 tags defined in the latest version of docbook, so we won't try to list them all here. Once you get the idea, you can either find examples in the rest of the documentation that do what you need, or look at Walsh and Muellner's DocBook: The Definitive Guide for more details.
References and Other Tutorials Docbook was created more than 10 years ago, but since 1999, Docbook has been under the guidance of the DocBook Technical Committee at OASIS. The OASIS website distributes the official DocBook DTDs, and has pages on Docbook history, samples, tools, and runs a few docbook mailing lists. Since the Linux Documentation Project uses docbook, they have written some good tutorial material. In particular the LDP Author Guide, by Jorge Godoy is very good. O'Reilly & Associates publishes a book called DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner. You can buy it or read it online. Norman Walsh knows what he's talking about, since he is the chair of the DocBook Technical Committee. This is good for reference, since it has a complete list of tags and their grammar. DocBook HOWTO, also by Jorge Godoy An article on lwn.net called Exploring SGML Docbook focuses mostly on installation of tools from scratch: openjade, Norman Walsh's DSSSL stylesheets, and jade2tex. If you can get the tools from RPMs or whatever package your OS uses, use that instead.
Conventions Put a &FIXME; near things that need to be fixed up. A &FIXME; causes the under construction symbol to appear, like this &FIXME;. A &NEEDHELP; indicates, that you need someone's help in order to document something, you don't know for sure. This is mostly the case if you need inside information from a developer. The symbol looks like this: &NEEDHELP;. Don't get confused because &FIXME; looks the same as &NEEDHELP; - this is just for the moment. When you like to use one of them, think of what it should mean, instead of how it looks like: Take &FIXME; if you have great ideas of what to document, but have no time or no knowledge about it, or just noticed something wrong or outdated. &NEEDHELP; instead should be used to request help on something (see above). This is just a first try to clearify the difference between &NEEDHELP; and &FIXME;. To maintain a consistent spelling, some "problem words" are mentioned here, along with a hint on how to spell them. list of problem words Bochs Bochs is written with a leading capital letter. bochsrc This is what the Bochs configuration file should be refered as. It is a good compromise between what is common on Unix and what is possible on Windows (file names starting with a dot aren't easy to create). Remember to use <filename>bochsrc</filename>. CD-ROM This abbreviation is written in all capital letters, with a hyphen in between. Unix Unix is written using a leading capital letter, followed by all lower-case letters. See the Unix entry in Wikipedia.
&FIXME; SGML docbook...lower case elements...indentation...remarks...master document/include files 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. If you just want to read the documentation, you should not need to read and understand this section, and render the docs yourself. The &bochswebsite; 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. 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.) Jade and DSSSL Here is what the Linux Documentation Project says about jade:
LDP author's guide 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.
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. 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. &NEEDHELP; 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 &docbookTDG; 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. 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. 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. 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. 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) Nsgmls The Bochs documentation is written in SGML docbook style, so any tool which can check SGML syntax can be used to check the docbook. The DTD (data type description) for docbook tells exactly which elements can be used and where. It says which attributes are required and which are optional, and how elements should be nested. The term "validate" has a specific meaning in SGML. When you validate a SGML document, it means that you read the DTD and then check that the document conforms to all the rules of the DTD. A program called nsgmls, written by James Clark jjc@jclark.com, can validate an SGML document such as our docbook. Although nsgmls can do many other things, this command will validate the docbook against the DTD which defines the syntax: nsgmls -s filename Nsgmls is part of SP, a "free object-oriented toolkit for SGML parsing and entity management" by James Clark jjc@jclark.com. SP can be found at http://www.jclark.com/sp. There is a complete man page for nsgmls here.