docbook: Thread: Looking for advice on appropriate tags

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

Hi David,

Rather than bore you with all the ways in which I would markup that type
of documentation, since it can be somewhat different for each person,
I'd rather point you to examples!

You might want to head to LDP and visit CVS.  I recall the Caudium HOWTO
containing a lot of stuff like that (I reviewed with the author), and
you could simply check-out the XML source from CVS and see how these
were done there.

I can't think of anymore off the top of my head, but my best advice is
to browse through the HOWTOs, and when you find one that has similar
items, just check them out and follow their source to create your own.

Hope that helps!

Tabatha


On Tue, 2002-11-26 at 15:07, David Horton wrote:
> 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/
> 
-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)