Docbook v. 1.61 gives less errors than 1.58

Use XML source files.  SGML is old fashioned crap.
Note that many of the Docbook docs are written for SGML source files.
Be aware that XML element names (and atts?) are always all lowercase.

Need to install docbook-xsl-stylesheets rpm.  You will need to install
several other rpm's to satisfy dependency requirements for this rpm.

Style sheets to make chunk html, all-in-one html, etc., reside at
/usr/share/sgml/docbook/*-xsl-stylesheets-*/*.  Output formats:
    fo (pdf/rtf/postscript?)
    html
    xhtml  (XML-ified HTML.  ulinks DON'T WORK IN BROWSERS!!!!)
    manpages
    javahelp
(for html and xhtml, use docbook.xsl for all-in-one, chunk.xsl for split-up).

Source files just need the xml header.  If your schema is in a
static location, then add the schema def line for validation.

PORTABLE HARDCOPY GENERATION
To generate print output, you need the Apache FOP.
http://xml.apache.org/fop/.  Since docbook uses png's, you also need
Sun's jimi JimiProClasses.zip file renamed to FOP_HOME/lib/jimi-1.0.jar
(or JAI, which is faster but not as portable).
N.b.!  I think that text outside of <para> doesn't print at all.
Many build errors like the following appear.
     fop: [ERROR] property - "background-position-horizontal" is not 
                             implemented yet.
    [fop] [ERROR] Error in column-width property value '33%': org.apache.fop.f
    o.expr.PropertyException: No conversion defined
    [fop] [ERROR] Unknown enumerated value for property 'relative-align': base
    line
).
Note that the <fop> ant task has an undocumented attribute 'basedir', which
works just like the 'dir' attribute of <exec>.


See my template build file docbook.xml.


NON-PORTABLE HARDCOPY GENERATION
(xmltex is in the xmltex rpm.
Since FOP isn't compatibile enough with DocBook at this time, the work-around
is to use the Linux-only programs to use tex to get from .fo to pdf
    pdfxmltex -interaction=batchmode *.fo; pdfxmltex -interaction=batchmode *.fo
    xmltex -interaction=batchmode *.fo; xmltex -interaction=batchmode *.fo
or dvi:
Either way, you need to run the command twice to get page numbering right 
 in the TOC.

Have to turn off tablecolumns.extension xsl param when using the po style
sheet, since it doesn't support columWidthAdjustment (or similar) function.


ONLY IMAGE TYPES OF png, jpg, gif, bmp are supported by Docbook.  (No eps!).



DOCBOOK SOURCE
================================

Looks like all text needs to be in a <title>, <para>, or <screen>/
<programlisting> elements.  Even lists need to be inside a <para>!

I see no difference between <simpara> and <para>.

"formal" means "titled".  "informal" means "non-titled".

SELF-LINKS
    <link linkend='element-id-of-target'>this</link>
    OR
    <link linkend='element-id-of-target' endterm='element-id-of-text'/>
    These self-link tags are just ignored for non-HTML output.
URL Links
    Defaults to text same as target URL.
    <ulink url='http://x/y.html'>thing</ulink>
    OR
    <ulink url='http://x/y.html'><citetitle>other</citetitle></ulink>
    If text is given, then for non-HTML output, user sees "... TEXT [url]...".

XRefs
    This just includes text from elsewhere in the document.  XRefs do 
    not result in hyperlinks, but they are coded similarly to links.


INCLUSION MECHANISMS
    The only inclusion mechanism is using entities (which could be dead-end,
    since they are a DTD, not XML Schema feature).
To include a non-XML file, you have to make a copy of the file with the
original file contents sandwiched between 
        <![CDATA[
and
        ]]>
    then include using the XML  entity feature.
    SUPPOSED TO WORK:  <textobject><textdata fileref='file.path'/></textobject>
    with xsl params use.extensions=1 and textinsert.extension=1.
    DOES NOT WORK

EXAMPLES
    INLINE.  There's no good facility for inline exaples or source code.
     Just use the inline <literal> element.
    Examples surrounded by either <example> or <informalExample>.
    The difference being that <example> has a title (which defaults to
    auto-generated numerical).  To specify your own title with <example>:
        <example><title>My Title</title><para>The example...
    Within this, use one of
        <programlisting>
        <literallayout> (no font change)
        <screen>
    If it has XML characters, then you'll have to <![CDATA[...]]> the example.


DIVISIONS
    Each major division (book, chapter) has
        OPTIONAL <*info> METADATA ELEMENT
        <title>the title</title>
        <section>
            <section> (subsection)
                <simplesect>  (leaf-level section)
            <bridgehead>title</bridgehead>
    Bridgeheads appear to be == <section><title>title</title></section>, i.e.,
     a section and title tag without any content.
    N.b.:  Bridgehead gets indented differently from section titles in pdf.

    <preface> is exactly like <title>, but it doesn't say "Chapter X" in the
    output.

    You can put <para>s directly under <chapter>.  You don't have to use
    sections.

<phrase> is just a grouping of words.

TEXT
    <warning>
    <note>
    <literal>
    <tip>
    <errortext>
    <emphasis> italic
    <emphasis role='bold'> bold
    <important>

LISTS
    <itemizedlist mark='opencircle'>  bulletted (mark defaults to 'bullet').
    <orderedlist>   numbered
    <segmentedlist> Supposed to like a table with list-presentation=table,
                    but my DocBook impl. doesn't support borders, so use
                    <table> instead. :(
        <title>A title</title>
        <?dbhtml list-presentation='table'?>
        <segtitle>State</segtitle><segtitle>Capital</segtitle>
        <seglistitem><seg>Alabama</seg><seg>Montgomery</seg></seglistitem>
        <seglistitem><seg>Alaska</seg><seg>Anchorage</seg></seglistitem>
    </segmentedlist>
    <simplelist>    base
    <variablelist>

        <listitem><para>the text</para></listitem>
        <member> ?

    <procedure><title>An example procedure</title>
        <step><para>...  </step>
        <step><para>... <substeps>
            <step><para>...</step>
        </substeps></step>
    </procedure>

There is also <table>.  See the formats-section.xml file for that.


Different images sizes for HTML and FO output.
http://www.sagehill.net/docbookxsl/ImageSizing.html#d0e18028


DocBook Website
===============
Unimpressive.
Underwhelming.


Stylesheets:  With Linux docbook-xsl-stylesheets RPM, or get the
docbook-xsl-X zip/tar file from Sourceforget DocBook project.



MATH
====
No good way to do math.
Best current way is to produce images for one format or the other.
Archaic.
See sample "math.xml".



INSERTING ADS
Copy the entire XSL root from ${docbook.xsl.home}.
Edit ${docbook.xsl.home}/html/docbook.xsl (this is used for both HTML
and Chunked HTML).
Replace the '<xsl:param name="node" select="."/>' body with your own HTML,
for any of the following template names:
    user.head.content.  Very top of page.
    user.header.navigation.  Above nav header.
    user.header.content.  Beneath <HR> of nav header.
    user.footer.content.  Above <HR> of nav footer.
    user.footer.navigation.  Beneath nav footer.
    OR change the header.navigation or footer.navigation in chunk-common.xsl
(Note that the *.navigation's don't apply to the non-chunk pages).