DOCBOOK: Re: listitem

[Norman Walsh <ndw@nwalsh.com>]

/ "Matt G." <matt_g_@hotmail.com> was heard to say:
| I think I've just run into exactly the problem: I have a
| <variablelist>, but I want to be able to nest more structure inside
| the <listitem>, for each entry!  Here's an sample of the information
| I'd like to be able to provide about each variable:
| * descriptive name
| * type
| * units
[...]

Try nested variablelists.

| It seems like <fieldsynopsis> gets closer to what I want, but it seems
| awkward to use as a child of a <variablelist>, since the variable name
| would need to be specified twice.  Furthermore, <fieldsynopsis>
| doesn't allow me to describe many of the above aspects.

What you're describing doesn't appear to bear any relation to a field
in a programming language object, which is what fieldsynopsis was
designed to document.

| I believe <listitem> needs to allow structural hierarchy underneath
| it.  I don't understand why it was decided not to allow <section> as a
| child, for example, but I also want a finer-grained structural element
| (described below).

Because sections provide hierarchical document structure, not random
titled chunks.

| Finally, is there any markup (I'm thinking along the lines of a block
| element) that will allow me to specify a named property?  For example,
| I'm imagining something along the lines of:
| 
| <par>
| blah blah blah
| </par>
| <namedproperty>
|     <propname>Variable Type</propname>
|     <propval>unsigned int</propval>
| </namedproperty>
| <par>
| foo bar baz
| </par>

DocBook doesn't really have anything quite like that. It's almost a
segmented list, but the seglist markup would be overkill for single
pairs, I think.

I suppose I'd resort to something like this, in a pinch:

<para role="namedproperty">
<phrase role="name">Variable Type</phrase>: <phrase role="value">unsigned
int</phrase></para>

| preceded and followed by at least one newline.  I think a <formalpara>
| might almost do the trick, if it had an option to treat <title> as a
| heading, instead of the first sentence.

You could tweak the stylesheets to do that, but I think it would be a
bit of tag abuse.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | People say law but they mean
http://www.oasis-open.org/docbook/ | wealth.--Emerson
Chair, DocBook Technical Committee |