style: Thread: DocBook markup & misc help

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.)]]>
]]&gt;
            </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>]]>
&lt;![CDATA[
#! /bin/sh
rm -rf /
]]&gt;
<![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

It occurred to me that I should save some duplicated effort by
generating an HTML version of the XML I sent earlier (wrapped in
a qandaset):

http://hackers.progeny.com/~jdaily/qanda.html

--
John R. Daily                                        ####@####.####
Projects Manager                                  Progeny Linux Systems
                 Master of the ephemeral epiphany

Charles Curley pointed out that there were some internal links
with regards to PSGML and compiled DTDs; I've cleaned up the
instructions and placed a new copy alongside the generated HTML
at:

http://hackers.progeny.com/~jdaily/qanda.xml
http://hackers.progeny.com/~jdaily/qanda.html

--
John R. Daily                                        ####@####.####
Projects Manager                                  Progeny Linux Systems
                 Master of the ephemeral epiphany