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

Subject: Re: [Boost-docs] Another quickbook multi-line issue
From: Paul A Bristow (pbristow_at_[hidden])
Date: 2007-08-03 08:09:39

>-----Original Message-----
>From: boost-docs-bounces_at_[hidden] 
>[mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Joel de Guzman
>Sent: 03 August 2007 01:23
>To: boost-docs_at_[hidden]
>Subject: Re: [Boost-docs] Another quickbook multi-line issue
>
>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?

[{ sounds far too much for such a marginal need.

>* Make tables phrase level  - I don't understand this :-(

>* Provide an alternate, well behaved syntax for paragraphs:
>   [para this is a paragraph].

this feels clean, and may be generally useful for layout control?

>* Provide an alternate, well behaved phrase level syntax
>   for lists: [list [item1][item2][item3]]

feels right too - though I think people would not want to lose the * list syntax because it is so convenient and readable.

(Both might be useful for automatically generated documentation).

But you're the expert ...

How difficult to implement should also be a consideration.

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]