DOCBOOK: Fwd: Looking for advice on appropriate tags

["John R. Daily" <john at geekhavoc dot com>]

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?

Dave


______________________
http://lists.tldp.org/



------- End of Forwarded Message