[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: Fwd: Looking for advice on appropriate tags
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC