Re: [docbook] Re: bridgehead not allowed in variablelist?

[Tim Arnold <jtim.arnold@gmail.com>]

On Mon, Aug 8, 2011 at 11:19 PM, Norman Walsh <ndw@nwalsh.com> wrote:
> Tim Arnold <jtim.arnold@gmail.com> writes:
>> Can someone help me understand the problem? example file appended below.
>> thanks,
>
> As Thomas pointed out, it's allowed in variablelist but not between entries.
>
> What are you trying to accomplish?
>
> Would it not be acceptable to end the list, insert the bridgehead, and start
> a new list?
>
>                                        Be seeing you,
>                                          norm
>
> --
> Norman Walsh <ndw@nwalsh.com>      | The voice of the intellect is a
> http://www.oasis-open.org/docbook/ | soft one, but it does not rest
> Chair, DocBook Technical Committee | until it has gained a hearing.--
>                                   | Freud
>

Thanks Thomas, Norm,
I should have started out with an explanation of the real problem. I
support a bunch of writers, some of whom have some pretty complicated
things to describe. They set out a list of items to describe and
sometimes these items can be categorized into groups; they want to
show the item, give some explanatory text and then, within the same
list provide a category heading and list the items within that
category.  This is the kind of thing, as an example that obviously
doesn't work (the subsection obviously can't come inside a list):

section: 'Options'
   'Option1'
       two types of values explained

   subsection: 'type1 values for Option1'
                     paragraphs of general explanation
      'value1'
         value1 explained
      'value2'
         value2 explained

   subsection: 'type2 values for Option1'
                     paragraphs of general explanation
      'value1'
         value1 explained
      'value2'
         value2 explained

   'Option 2'
      option 2 explained

 end section

Norm, your suggestion is exactly what I suggested to them, but after
looking over their documents, I see that they really need to keep the
variablelist open. FWIW, they are writing in LaTeX and I'm converting
that to DocBook.  The 'subsection' is what I was trying to render as a
bridgehead.

Thomas, I did read the element reference but I didn't understand how
to read the synopsis. After your message I think the synopsis provides
the specification *in order*. So if you have a bridgehead or an
annotation, it must come before any varlistentries.  Didn't realize
the order mattered, now it makes sense!

I'm still not sure how to render the example above into DocBook--is it
possible without rewriting?  Any ideas much appreciated.

thanks,
--Tim