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

Subject: Re: [boost] [quickbook] Strange error regarding lists
From: Daniel James (dnljms_at_[hidden])
Date: 2014-07-20 05:03:57

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.