Re: [boost] [quickbook] Strange error regarding lists

Subject: Re: [boost] [quickbook] Strange error regarding lists
From: Edward Diener (eldiener_at_[hidden])
Date: 2014-07-20 10:14:41

On 7/20/2014 5:03 AM, Daniel James wrote:
> On 19 July 2014 15:52, Edward Diener <eldiener_at_[hidden]> wrote:
>> On 7/19/2014 9:50 AM, Daniel James wrote:
>>>
>>> On 19 July 2014 14:21, Edward Diener <eldiener_at_[hidden]> wrote:
>>>>
>>>> Using the latest quickbook on 'develop' in some documentation I have:
>>>>
>>>> * a comment
>>>>
>>>>    SOMENAME
>>>>
>>>> only to get the quickbook error:
>>>>
>>>> my_file:14: error: Nested blocks in lists won't be supported in quickbook
>>>> 1.6.
>>>>
>>>> Why am I seeing this ?
>>>
>>>
>>> Such indentation is going to be used for paragraphs in lists, but I
>>> hadn't fully worked out how to do it when I was finishing off 1.6.
>>> Previously such indentation would be interpreted as a code block,
>>> which is usually not intended. Markup that is usually interpreted
>>> incorrectly and would change meaning when upgrading to 1.7 will cause
>>> problems in the long run, so it's better to catch it sooner rather
>>> than later. If you want paragraphs in lists then you'll need to use an
>>> explicit list tag, if you want a code block then you should use an
>>> explicit code block (i.e. two backticks at the beginning and end).
>>
>>
>> Does not a list end when there is a blank list following the last list
>> element ? If not, how does one end a list ?
>
> Blank line followed by non-indented text.
>
> * item 1
> * item 2
>
> Following paragraph.
>
>> I had ended for the line to be a code block. I had assumed my list had
>> ended.
>
> AFAICT most people's intuitive understanding of something like this:
>
> * xxxx
>
>    xxxx
>
> * xxxx
>
>    xxxx
>
> Is that it's paragraphs in single list item. It fits in with the idea
> of using indentation to model lists. This is how markdown and
> restructedtext both handle lists (other markup languages that I looked
> at use multiple asterisks to indicated a nested list, rather than
> indentation). Looking through the archives I found an example of
> someone expecting that:
>
> http://lists.boost.org/Archives/boost/2010/12/174181.php
>
> I think other people have had the same issue.
>
>> Although I appreciatethe idea of being able to have paragrrpahs in lists I
>> suggest that paragraphs in lists should not override the normal ending of
>> lists.
>
> It's only changing for lists followed by code blocks, which is an
> unusual thing to do.

Maybe in the documentation you can then mention how to have a code block 
directly following a list, rather than have such syntax be a paragraph 
in a list item.