docbook: Thread: Re: Various lists used in DocBook

On Tue, Jul 22, 2003 at 07:25:15PM +0200, Kian Spongsveen wrote:
> I am gradually picking up speed writing my HowTo. Now I have a list that I 
> need some suggestions on. I'm using DocBook XML. Hope that's not too 
> off-topic here, let me know where to post if I'm wrong.

This discussion should probably be on the docbook list rather than the
discuss list, so I'll CC it there as well. If you haven't already
joined it, you may want to do so so that you can get reponses.

> 
> Basically, I want to describe a set of known problems, their
> symptoms, the cause behind and the workaround / kludge to avoid the
> problems. I want these as a list where the actual problem is the
> most important part, but I also want the other sections in a
> systematic order. It will be a list with short paragraphs, but
> several such "problem" points.
> 
> I want it to look something like:
> 
> Problem: Product does not install
> Symptom: Screen is blank
> Cause: The power is off
> Solution: Find the power switch, set it to ON position
> Solution2: Plug the power cord into the wall outlet
> 
> The words Problem, Symptom and Cause will be emphasized bold and
> there will only be one of each of these first 3 items.  Then there
> may be one Solution item, or several.

If you are still specifying bold and other formatting characteristics,
then you are new to SGML/XML. These tools separate formatting from
content. Writers write content, style sheet authors specify
formatting. You as an author have to leave the choice of bold or not,
ital or roman, to the style sheet.

> 
> I tried to use the <itemizedlist>, but that creates bullet points
> and makes each such section more or less become continuous with the
> next.
> 
> I tried to use <variablelist>, but I get some complaints from my
> editor (jEdit with XML plug-in), and sometimes from xsltproc, when I
> use multiple <listitem> and/or <term> tags within each
> <varlistentry> section.
> 
> So, which type of list that is supported by TLDP should I use for
> this?

TLDP supports anything your docbook tools will support.

I suggest a table, three columns, like so:

Problem &	Causes	Solution 1
Symptom			Solution 2
			...
			Solution N

With blank cells in the first two columns where you have multiple
solutions.

Tables are very sophisticated and very powerful in docbook, much more
so than HTML. You should be able to get what you want.

-- 

Charles Curley                  /"\    ASCII Ribbon Campaign
Looking for fine software       \ /    Respect for open standards
and/or writing?                  X     No HTML/RTF in email
http://www.charlescurley.com    / \    No M$ Word docs in email

Key fingerprint = CE5C 6645 A45A 64E4 94C0  809C FFF6 4C48 4ECD DFDB