Re: DOCBOOK: Fwd: Looking for advice on appropriate tags

[Bob Stayton <bobs at caldera dot com>]

On Tue, Nov 26, 2002 at 06:29:20PM -0500, John R. Daily wrote:
> I'm forwarding this note (originally sent to the LDP's DocBook
> mailing list) because it expresses a desire to have more
> expressive procedure semantics.
> 
> I didn't see any response to my earlier note on test cases as a
> similar concept that lacked expression in DocBook.  Was it
> irrelevant, or simply lacking in concreteness worthy of further
> discussion?
> 
> -John
> 
> ------- Forwarded Message
> 
> Message-ID: <3DE3FEA0.50809@megsinet.net>
> Date: Tue, 26 Nov 2002 17:07:12 -0600
> From: David Horton <dhorton@megsinet.net>
> User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.2b) Gecko/20021016
> X-Accept-Language: en-us, en
> MIME-Version: 1.0
> To: docbook@en.tldp.org
> Subject: Looking for advice on appropriate tags
> Content-Type: text/plain; charset=us-ascii; format=flowed
> Content-Transfer-Encoding: 7bit
> 
> Hi everyone,
> 
> I am in the process of taking some documentation that I originally wrote
> in HTML and converting it into Docbook XML.  Most of it is pretty
> painless, like turning the P tag into PARA and LI into LISTITEM, but I
> am a bit confused on what to do with some of the interactive procedures.
> 
> For example, I am really hung up on a section that looks like this:
> 
> 
> Prepare the boot disk floppy
> 
> Insert a blank diskette labled "boot disk".
> 
> bash# mke2fs -m0 /dev/fd0
> bash# mount /dev/fd0 /mnt
> 
> 
> Build the kernel
> 
> bash# cd /usr/src/linux
> bash# make menuconfig
> 
> Be sure to configure support for the following:
> 
>      * 386 processor
>      * floppy disk
>      * RAM disk
>      * Text console
> 
> bash# make dep
> bash# make clean
> bash# make bzImage
> 
> 
> What I am trying to get across by laying it out this way is this:
> 
> "Prepare the boot floppy" is a major step.  If the reader can handle
> that task without further coaching, he can skip to the next major step
> which is "build the kernel".  If he needs a little extra help, he can
> read the detailed, minor steps inbetween.  Hopefully this way advanced
> readers can jump from major step to major step and not get bored while
> the novice can go into more detail and not get lost.
> 
> With HTML I have marked this up using headings for the major steps,
> paragraphs for the steps like "insert a blank diskette" and preformatted
> tags for the interactive stuff typed at the bash# prompt.
> 
> What I would like to know is how to keep this major step, minor step
> thing using Docbook XML.
> 
> * Is this something that would fit the PROCEDURE and STEP tags?
> * Should I use SCREENSHOT or COMPUTEROUTPUT for the lines with the 
> "bash#" prompt?
> * Should I surround "bash#" with the PROMPT tag?
> * Is there a standard way of doing this?
> 
> I've been looking for examples of Docbook XML with similar requirements,
> but so far have had no luck.
> 
> Can anyone point me to a good example or make some suggestions?
 
Here is how I would do it. I'd use procedure with steps and
substeps, and capture the main idea in each step's title.
I've included indents in literallayout here for illustration
purposes only.  I also tend to avoid showing prompts unless
it is an interactive session showing output as well.

<procedure>
  <step>
    <title>Prepare the boot disk floppy</title>
    <substeps>
      <step>
        <para>Insert a blank diskette labled "boot disk".</para>
      </step>
      <step>
        <para>Execute the following commands:</para>
        <literallayout class="monospaced">
          mke2fs -m0 /dev/fd0
          mount /dev/fd0 /mnt
        </literallayout>
      </step>
    </substeps>
  </step>
  <step>
    <title>Build the kernel</title>
    <substeps>
      <step>
        <para>Execute the following commands:</para>
        <literallayout class="monospaced">
          cd /usr/src/linux
          make menuconfig
        </literallayout>
      </step>
      <step>
        <para>Be sure to configure support for the following:</para>
	<itemizedlist>
	  <listitem>
            <para>386 processor</para>
	  </listitem>
	  <listitem>
            <para>floppy disk</para>
	  </listitem>
	</itemizedlist>
      </step>
      <step>
        <para>Execute the following commands:</para>
        <literallayout class="monospaced">
          make dep
          make clean
          make bzImage
        </literallayout>
      </step>
    </substeps>
  </step>
</procedure>


-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com