documentation.dbk

虚拟计算机源代码,一个虚拟计算机的源码,做虚拟计算机的朋友可以

<!--
================================================================
doc/docbook/documentation/documentation.dbk
$Id: documentation.dbk,v 1.9 2001/11/17 17:14:42 bdenney Exp $

This is the top level file for the Bochs Documentation Manual.
================================================================
-->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- include definitions that are common to all bochs documentation -->
<!ENTITY % bochsdefs SYSTEM "../include/defs.sgm">
%bochsdefs;

]>

<book>
<bookinfo>
   <title>Bochs Documentation Manual</title>
   <authorgroup>
   <author><firstname>Bryce</firstname><surname>Denney</surname></author>
   <author><firstname>Michael</firstname><surname>Calabrese</surname></author>
   <editor><firstname>Vasudeva</firstname></editor>
   </authorgroup>
</bookinfo>
<chapter><title>Layout of Bochs Documentation</title>

<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>

<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><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
&amp; 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>

<section><title>Small Tutorial</title>

<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 &lt;/h1&gt; at then end of an &lt;h1&gt; 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 &lt;para&gt; tag and end with the
corresponding end tag, &lt;/para&gt;.
<programlisting>
&lt;<ulink url="http://www.docbook.org/tdg/en/html/para.html">para</ulink>&gt;
This is a paragram
&lt;/para&gt;
</programlisting>
</para>

<para>
A chapter looks like this:
<programlisting>
&lt;<ulink url="http://www.docbook.org/tdg/en/html/chapter.html">chapter</ulink>&gt;
  &lt;title&gt;<replaceable>title of the chapter</replaceable>&lt;/title&gt;
  <replaceable>text of the chapter</replaceable>
&lt;/chapter&gt;
</programlisting>
The text of the chapter must contain at least one complete &lt;para&gt; tag,
and it can include &lt;section&gt;s.
</para>

<para>
A section looks like this:
<programlisting>
&lt;<ulink url="http://www.docbook.org/tdg/en/html/section.html">section</ulink>&gt;
  &lt;title&gt;<replaceable>title of the section</replaceable>&lt;/title&gt;
  <replaceable>text of the section</replaceable>
&lt;/section&gt;
</programlisting>
The text of the section must contain at least one complete &lt;para&gt; tag,
and it can include other &lt;section&gt;s.
</para>

<para>
To make a link to any URL, use the syntax:
<programlisting>
&lt;<ulink url="http://www.docbook.org/tdg/en/html/ulink.html">ulink</ulink> url="<replaceable>URL</replaceable>"&gt;<replaceable>text of the hyperlink</replaceable>&lt;/ulink&gt;
</programlisting>
</para>

<para>
To include a picture in the text, use the &lt;graphic&gt; tag.  In SGML, this
graphic tag has no closing tag.
<programlisting>
&lt;<ulink url="http://www.docbook.org/tdg/en/html/graphic.html">graphic</ulink> format="<replaceable>fmt</replaceable>" fileref="<replaceable>filename</replaceable>"&gt;
</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 &amp; 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 &amp;FIXME; near things that need to be fixed up.  A &amp;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>Reading and Writing</title>

<para>
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.  
</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
&bochswebsite; has all this information in readable form already.
</para>
</tip>

<para>