Re: [Boost-docs] Another quickbook multi-line issue

Subject: Re: [Boost-docs] Another quickbook multi-line issue
From: Joel de Guzman (joel_at_[hidden])
Date: 2007-08-03 00:23:07

John Maddock wrote:
>> Hmm, not quite sure what you want. Do you need more than one paragraph
>> in list items? Do you want to manually control the flow of the the text?
> 
> Basically more than one paragraph in a single list item, yes.  But Docbook 
> allows any block-level element inside a <listitem>...</listitem>: tables, 
> paragraphs, admonishments etc.

Paul A Bristow wrote:
>
> Both of these
>
> * The formula for diameter is too long to go on this line and would look funny
> 	so want to decide where to split and if and how to indent
> 	diameter = curcum/pi
>   or want to put something else in this list item
>      diameter + 2 * radius
> * other....
>
> \n works fine - but is deprecated ;-)

The same is true for tables, right? We'd also want
lists in tables, for example, or even tables in tables.

Ok. I knew that would come one day. Both are really valid needs.
The difficulty is the wiki list-item syntax not terminating
cleanly.

The simple wiki style syntax gets in the way here. One reliable
(umambiguous) way to allow blocks inside lists and tables
that I know is by providing a special syntax for blocks that's
clearly delimited. For example:

* Item1 [{
     This is a table inside a list:

     [table foo
      [[a][b][c]]
      [[d][e][f]]
     ]
   }]

* Item2 [{
     Or how about a list inside a table in the list:

     [table bar
      [[a][b][c]]
      [[d][e]
      [[{
         * item1
         * item2
         * item3
       }]
      ]]
     ]
   }]

Here, the proper (nestable) delimiter is the [{ ... }].
Everything inside it is parsed as a block, of course with
certain exceptions (e.g. sections cannot be allowed).

Another way is to:
* Make tables phrase level
* Provide an alternate, well behaved phrase level syntax
   for lists: [list [item1][item2][item3]]
* Provide an alternate, well behaved syntax for paragraphs:
   [para this is a paragraph].

Then, we can allow these alternate markups inside lists
and tables with as much nesting as you want.

Thoughts?

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net