Subject:
DocBook markup & misc help
From:
"John R. Daily" ####@####.####
Date:
9 Apr 2002 19:06:28 -0000
Message-Id: <20020409190602.45CAD18035@albus.progeny.com>
After seeing Glen Turner's note on discuss re: useful DocBook
markup advice, and Joy's response, I thought I'd send this along.
Included below is a subset of a qandaset I wrote for Progeny many
months ago, when I was learning DocBook. I can't guarantee that
the advice here is the best available; my overall DocBook
experience is still somewhat limited.
If any of this is of interest, feel free to use it; consider the
copyright on this assigned to the LDP. All we'd ask is for
Progeny Linux Systems, Inc. to be listed as a contributor to the
resulting document.
(A warning: I've tweaked this a bit after copying it into my
email buffer, so there could be validation issues.)
<qandadiv>
<title>DocBook meta-queries</title>
<qandaentry>
<question>
<para>How do I find out more about DocBook?</para>
</question>
<answer>
<para>The definitive site for DocBook information is
<ulink url="http://www.oasis-open.org/docbook/"/>.
Despite the URL,
<ulink url="http://www.docbook.org/"/> is only
a partial mirror of
<ulink url="http://www.oasis-open.org/who/index.shtml">OASIS'</ulink>
site, although it is the official home
page for <emphasis>DocBook: The Definitive
Guide</emphasis>.
</para>
<para>
Of particular interest is the
<ulink url="http://docbook.org/tdg/en/html/docbook.html">online
version</ulink> of the DocBook book. Recently, the
online book was updated for DocBook 4.
</para>
<para>
Norm Walsh is the most visible DocBook technical
committee member, and
<ulink url="http://www.nwalsh.com/">his site</ulink>
contains much useful information.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why DocBook?</para>
</question>
<answer>
<para>DocBook/XML is now the "standard" open source
documentation format. See
<ulink url="http://www.oreilly.com/frank/oscon_summit.html">http://www.oreilly.com/frank/oscon_summit.html</ulink>
for a discussion of the issue.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
What elements do I need under my belt to get started?
</para>
</question>
<answer>
<para>
The elements that I've identified as the most important
are largely structural. I'll list them here linked to the
online reference guide; to view any particular tag, just
visit
<literal>http://www.docbook.org/tdg/en/html/[tag].html</literal>.
</para>
<para>
<ulink
url="http://www.docbook.org/tdg/en/html/abstract.html">Abstract</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/answer.html">Answer</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/article.html">Article</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/40update/articleinfo.html">ArticleInfo</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/author.html">Author</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/authorgroup.html">AuthorGroup</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/copyright.html">Copyright</ulink>,
<ulink url="http://www.docbook.org/tdg/en/html/date.html">Date</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/firstname.html">FirstName</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/imagedata.html">ImageData</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/imageobject.html">ImageObject</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/informalexample.html">InformalExample</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/itemizedlist.html">ItemizedList</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/keyword.html">Keyword</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/keywordset.html">KeywordSet</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/listitem.html">ListItem</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/mediaobject.html">MediaObject</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/orderedlist.html">OrderedList</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/othername.html">OtherName</ulink>,
<ulink url="http://www.docbook.org/tdg/en/html/para.html">Para</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/procedure.html">Procedure</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/qandaentry.html">QandAEntry</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/qandaset.html">QandASet</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/question.html">Question</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/section.html">Section</ulink>,
<ulink
url="http://www.docbook.org/tdg/en/html/surname.html">Surname</ulink>,
<ulink url="http://www.docbook.org/tdg/en/html/title.html">Title</ulink>,
<ulink url="http://www.docbook.org/tdg/en/html/ulink.html">ULink</ulink>,
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv>
<title>How do I...?</title>
<qandaentry>
<question>
<para>
How do I include images in my document?
</para>
</question>
<answer>
<para>
The top-level wrapper for images is <sgmltag
class="element">mediaobject</sgmltag>, although it is
often enclosed in other tags such as <sgmltag
class="element">informalfigure</sgmltag>.
</para>
<para>
Here is one example (but see also
<link linkend="imageformats">this question</link> for a
discussion of handling both <acronym>HTML</acronym> and
Postscript output).
</para>
<informalexample>
<programlisting format="linespecific">
<![CDATA[
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="flowchart.png"/>
</imageobject>
</mediaobject>
</informalfigure>
]]>
</programlisting>
</informalexample>
</answer>
</qandaentry>
<qandaentry id="imageformats">
<question>
<para>How do I include images to
display in both print (Postscript) and web documents?</para>
</question>
<answer>
<para>
If you include multiple
<sgmltag class="element">imageobject</sgmltag>
elements within a
<sgmltag class="element">mediaobject</sgmltag> tag, the
stylesheet processor should select the first appropriate
image type.
</para>
<para>
However, <application>jadetex</application> will only try
the first <sgmltag class="element">imageobject</sgmltag>,
so typically any
<filename role="extension">.eps</filename> image should be
listed first.
</para>
<para>
Here's an example:
</para>
<informalexample>
<programlisting>
<![CDATA[
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="flowchart.eps"/>
</imageobject>
<imageobject>
<imagedata fileref="flowchart.png"/>
</imageobject>
</mediaobject>
</informalfigure>
]]>
</programlisting>
</informalexample>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I introduce non-parsed data (like XML tags
that shouldn't be interpreted)
into a document?
</para>
</question>
<answer>
<para>
Through use of CDATA (short for character data). Example:
</para>
<informalexample>
<programlisting>
<![CDATA[
<![CDATA[
<para> </para> is roughly comparable to HTML's <p> </p> (except
that few people use the closing </p> tag.)]]>
]]>
</programlisting>
</informalexample>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I mark up a command that the user should type
at a prompt?
</para>
</question>
<answer>
<para>In-line, use <ulink
url="http://www.docbook.org/tdg/en/html/command.html"><sgmltag
class="element">command</sgmltag></ulink>, <ulink
url="http://www.docbook.org/tdg/en/html/parameter.html"><sgmltag
class="element">parameter</sgmltag></ulink>, and <ulink
url="http://www.docbook.org/tdg/en/html/option.html"><sgmltag
class="element">option</sgmltag></ulink>.</para>
</answer>
<answer>
<para>On its own line, use the following.
</para>
<informalexample>
<programlisting format="linespecific">
<![CDATA[
<informalexample>
<screen>$ <userinput><command>/sbin/ifconfig</command> <option>-m</option> <parameter>eth0</parameter></userinput>
</screen>
</informalexample>]]>
</programlisting>
</informalexample>
<para>
Which renders as:
</para>
<informalexample>
<screen>$ <userinput><command>/sbin/ifconfig</command> <option>-m</option> <parameter>eth0</parameter></userinput>
</screen>
</informalexample>
<para>
Note that the above is
outside any enclosing <sgmltag class="element">para</sgmltag>
tag, and that the <sgmltag>command</sgmltag> and
<sgmltag>option</sgmltag> tags are optional.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I mark up in-line user input? For example, "When
prompted for the username, type 'root'."
</para>
</question>
<answer>
<para>With <ulink
url="http://www.docbook.org/tdg/en/html/userinput.html"><sgmltag
class="element">userinput</sgmltag></ulink>, like:
<![CDATA[When prompted for the username, type
<userinput>root</userinput>.]]>
</para>
</answer>
</qandaentry>
<qandaentry id="synopsisquery">
<question>
<para>How do I represent the general form of a command?</para>
</question>
<answer>
<para>With <ulink
url="http://www.docbook.org/tdg/en/html/cmdsynopsis.html"><sgmltag
class="element">cmdsynopsis</sgmltag></ulink> or <ulink
url="http://www.docbook.org/tdg/en/html/synopsis.html"><sgmltag
class="element">synopsis</sgmltag></ulink>.
</para>
</answer>
</qandaentry>
<qandaentry id="programlisting">
<question>
<para>How do i include program listings?</para>
</question>
<answer>
<para>Use <ulink
url="http://docbook.org/tdg/en/html/programlisting.html"><sgmltag
class="element">programlisting</sgmltag></ulink> like
this:</para>
<literallayout>
<![CDATA[<programlisting>]]>
<![CDATA[
#! /bin/sh
rm -rf /
]]>
<![CDATA[</programlisting>]]>
</literallayout>
</answer>
</qandaentry>
</qandadiv>
<qandadiv>
<title>Limitations</title>
<qandaentry>
<question>
<para>Can <sgmltag class="element">qandaset</sgmltag>
elements contain meta-data?</para>
</question>
<answer>
<para>Not yet. The DocBook technical committee is
considering adding a general meta-data wrapper which could
be used under all block elements. See <ulink
url="http://lists.oasis-open.org/archives/docbook-tc/200105/msg00005.html">2001-05-18
meeting minutes</ulink>.</para> <para>In the meantime, use
<sgmltag class="element">article</sgmltag> to enclose
<sgmltag class="element">qandaset</sgmltag>s.</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv>
<title>PSGML</title>
<qandaentry>
<question>
<para>PSGML is confused. What do I do?</para>
</question>
<answer>
<para>Occasionally, PSGML loses track of your current
context. Symptoms include:</para>
<itemizedlist>
<listitem>
<para>Inconsistent indentation.</para>
</listitem>
<listitem>
<para>The message <computeroutput>No
elements allowed in markup</computeroutput> appears when
you use the key sequence <keycombo>
<keysym>C-c</keysym>
<keysym>C-e</keysym></keycombo>
to insert a new element in a valid location.</para>
</listitem>
</itemizedlist>
<para>To correct the situation, select
<guimenuitem>Reset Buffer</guimenuitem> from the
<guimenu>SGML</guimenu> menu.</para>
<para>I cannot find a way to invoke this function
directly.</para>
<warning>
<para>Currently, I'm having severe problems with one
document and its internal entities. The entities seem to
confuse PSGML, forcing me to repeatedly reset the
buffer. See <link linkend="precompile">this
question</link> for a way to avoid the time
required to parse DocBook.</para>
</warning>
</answer>
</qandaentry>
<qandaentry id="precompile">
<question>
<para>Compiling DocBook takes too long. How can I speed
things up?</para>
</question>
<answer>
<para>The <ulink
url="http://mandark/progeny/doctools/">doctools</ulink>
module contains a PSGML parsed DTD for Docbook. Just
tell Emacs about it by putting this at the bottom of your
document. You should, of course, correct the path to your
module's copy of <ulink
url="http://mandark/progeny/doctools/">doctools</ulink>.</para>
<literallayout>
<![CDATA[
<!-- Local variables: -->
<!-- eval: (sgml-load-dtd "../../doctools/docbook.ced") -->
<!-- End: -->
]]>
</literallayout>
<warning>
<para>I've had very little experience with saving and
loading parsed DTDs, so there may be complications of
which I am not aware.</para>
</warning>
</answer>
</qandaentry>
</qandadiv>
--
John R. Daily ####@####.####
Projects Manager Progeny Linux Systems
Master of the ephemeral epiphany