- fill in lots of blanks!
This commit is contained in:
Bryce Denney
parent
9ad0990fd7
commit
24cbe1e7f6
@ -1,4 +1,12 @@
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
|
||||
<!-- example entity that can be used with &bochs; -->
|
||||
<!ENTITY bochs '<ulink url="http://bochs.sourceforge.net">The Bochs Project</ulink>'>
|
||||
<!ENTITY FIXME '<inlinegraphic format="GIF" fileref="../images/undercon.gif">'>
|
||||
<!ENTITY NEEDHELP '<inlinegraphic format="GIF" fileref="../images/undercon.gif">'>
|
||||
<!ENTITY docbookTDG '<ulink url="http://www.docbook.org/tdg/en/html/docbook.html">DocBook: The Definitive Guide</ulink>'>
|
||||
<!ENTITY OASIS '<ulink url="http://www.oasis-open.org/">OASIS</ulink>'>
|
||||
]>
|
||||
|
||||
<book>
|
||||
<bookinfo>
|
||||
<title>Bochs Documentation Manual</title>
|
||||
@ -6,40 +14,368 @@
|
||||
<author><firstname>Michael</firstname><surname>Calabrese</surname></author>
|
||||
</authorgroup>
|
||||
</bookinfo>
|
||||
<chapter><title>Layout</title>
|
||||
<para>
|
||||
</para>
|
||||
<para>
|
||||
Master document....Books...chapter...sections...toc...Index...glossary..remarks(comments)
|
||||
</para>
|
||||
</chapter>
|
||||
<chapter><title>Layout of Bochs Documentation</title>
|
||||
|
||||
<chapter><title>Docbook Basics</title>
|
||||
<section><title>Small Tutorial</title>
|
||||
<para>
|
||||
text file...chapter...section..references (xref...web..)...graphics
|
||||
<para>
|
||||
The Bochs documentation is divided into three major divisions:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
The User's Guide introduces the Bochs Emulator, and covers installation and use.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Developer's Guide: Describes the internals of the Bochs Emulator for developers.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section><title>Refences and Other Tutorials</title>
|
||||
<para>
|
||||
docbook.org...
|
||||
</para>
|
||||
</section>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
</chapter>
|
||||
|
||||
</chapter>
|
||||
<chapter><title>Docbook Basics</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<chapter><title>Conventions</title>
|
||||
<para>
|
||||
lower case elements...indentation...remarks...master document/include files
|
||||
</para>
|
||||
</chapter>
|
||||
<section><title>Small Tutorial</title>
|
||||
|
||||
<chapter><title>Rendering</title>
|
||||
<para>
|
||||
rendering tools ...jw/jade ... docbook tools...sgml tools (how to get/what to see)
|
||||
</para>
|
||||
</chapter>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Every paragraph must begin with the <para> tag and end with the
|
||||
corresponding end tag, </para>.
|
||||
<programlisting>
|
||||
<<ulink url="http://www.docbook.org/tdg/en/html/para.html">para</ulink>>
|
||||
This is a paragram
|
||||
</para>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A chapter looks like this:
|
||||
<programlisting>
|
||||
<<ulink url="http://www.docbook.org/tdg/en/html/chapter.html">chapter</ulink>>
|
||||
<title><replaceable>title of the chapter</replaceable></title>
|
||||
<replaceable>text of the chapter</replaceable>
|
||||
</chapter>
|
||||
</programlisting>
|
||||
The text of the chapter must contain at least one complete <para> tag,
|
||||
and it can include <section>s.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A section looks like this:
|
||||
<programlisting>
|
||||
<<ulink url="http://www.docbook.org/tdg/en/html/section.html">section</ulink>>
|
||||
<title><replaceable>title of the section</replaceable></title>
|
||||
<replaceable>text of the section</replaceable>
|
||||
</section>
|
||||
</programlisting>
|
||||
The text of the section must contain at least one complete <para> tag,
|
||||
and it can include other <section>s.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To make a link to any URL, use the syntax:
|
||||
<programlisting>
|
||||
<<ulink url="http://www.docbook.org/tdg/en/html/ulink.html">ulink</ulink> url="<replaceable>URL</replaceable>"><replaceable>text of the hyperlink</replaceable></ulink>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To include a picture in the text, use the <graphic> tag. In SGML, this
|
||||
graphic tag has no closing tag.
|
||||
<programlisting>
|
||||
<<ulink url="http://www.docbook.org/tdg/en/html/graphic.html">graphic</ulink> format="<replaceable>fmt</replaceable>" fileref="<replaceable>filename</replaceable>">
|
||||
</programlisting>
|
||||
The <replaceable>fmt</replaceable> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
<ulink url="http://www.docbook.org/tdg/en/html/docbook.html">DocBook: The Definitive Guide</ulink>
|
||||
for more details.
|
||||
</para>
|
||||
|
||||
</section> <!-- end of Docbook Basics:Small Tutorial section -->
|
||||
|
||||
<section><title>References and Other Tutorials</title>
|
||||
|
||||
<para>
|
||||
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
|
||||
<ulink url="http://www.oasis-open.org/committees/docbook">OASIS website</ulink>
|
||||
distributes the official DocBook DTDs, and has pages on Docbook history,
|
||||
samples, tools, and runs a few docbook mailing lists.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Since the Linux Documentation Project uses docbook, they have written some
|
||||
good tutorial material. In particular the <ulink url="http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html">LDP Author Guide</ulink>, by Jorge Godoy
|
||||
is very good.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
O'Reilly & Associates publishes a book called <ulink
|
||||
url="http://www.docbook.org/tdg/en/html/docbook.html">DocBook: The Definitive
|
||||
Guide</ulink> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<ulink url="http://www.ibiblio.org/godoy/sgml/docbook/howto/index.html">DocBook
|
||||
HOWTO, also by Jorge Godoy</ulink>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An article on lwn.net called <ulink
|
||||
url="http://lwn.net/2000/features/DocBook">Exploring SGML Docbook</ulink>
|
||||
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.
|
||||
</para>
|
||||
|
||||
</section> <!-- end of Docbook Basics:References and Other Tutorials -->
|
||||
|
||||
</chapter>
|
||||
|
||||
<chapter><title>Conventions</title>
|
||||
<para>
|
||||
Put a &FIXME; near things that need to be fixed up. A &FIXME; causes
|
||||
the under construction symbol to appear, like this &FIXME;.
|
||||
</para>
|
||||
<para>
|
||||
&FIXME; SGML docbook...lower case elements...indentation...remarks...master document/include files
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter><title>Rendering</title>
|
||||
|
||||
<para>
|
||||
The docbook source code is a text file that can be edited with any text editor
|
||||
such as emacs or vi. Several software tools are required to render this
|
||||
source code into a nice readable form, such as HTML, PDF, or PostScript.
|
||||
This section describes the tools you need and the steps you take to render
|
||||
the Bochs documentation.
|
||||
</para>
|
||||
|
||||
<tip>
|
||||
<para>
|
||||
If you just want to read the documentation, you should not
|
||||
need to read and understand this section, and render the docs yourself. The
|
||||
<ulink url="http://bochs.sourceforge.net">bochs web site</ulink> has all this
|
||||
information in readable form already.
|
||||
</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 purpose 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
|
||||
<quote>Document Style Semantics and Specification Language</quote>, 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 <ulink
|
||||
url="http://www.jclark.com/dsssl">Jim Clark's DSSSL page</ulink>.
|
||||
The DocBook DTD is the formal description of what elements and attributes can
|
||||
be used in a docbook.
|
||||
</para>
|
||||
|
||||
<sect2>
|
||||
<title>Installation</title>
|
||||
|
||||
<para>
|
||||
The easiest way to get jade working in Linux is to install packages. The
|
||||
recent RedHat, Suse, and Mandrake Linux distributions all include
|
||||
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:
|
||||
|
||||
<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>
|
||||
|
||||
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;
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
<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 DSSSL
|
||||
stylesheets</ulink> 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.
|
||||
</para>
|
||||
<tip> <para> Just use the packages. </para> </tip>
|
||||
|
||||
<para>
|
||||
For now, building the Bochs documentation also depends on some scripts called
|
||||
docbook2html, docbook2pdf, and docbook2ps. I'm not sure which packages these
|
||||
come from, but they are very convenient. &NEEDHELP;
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Using jade with docbook2x scripts</title>
|
||||
|
||||
<para>
|
||||
Check to see if you have the docbook2ps, docbook2pdf, and docbook2html
|
||||
scripts. 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 one
|
||||
in and documentation. If there are no errors, look for the user guide
|
||||
in <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 broken
|
||||
into lots of little chunks that link to each other, but book1.html is the first
|
||||
one.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Using jade directly</title>
|
||||
<para>
|
||||
If you don't have docbook2<replaceable>format</replaceable> 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 <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 print
|
||||
stylesheet 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. Some
|
||||
other 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 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.
|
||||
</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 many
|
||||
other things, this command will validate the docbook against the DTD which
|
||||
defines 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 and
|
||||
entity management" by James Clark <email>jjc@jclark.com</email>. SP can be
|
||||
found 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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user