[quickbook] Strange error regarding lists

newer
[boost-test] question about using...

Edward Diener

19 Jul 2014 19 Jul '14

1:21 p.m.

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 ?

Show replies by date

Daniel James

19 Jul 19 Jul

1:50 p.m.

On 19 July 2014 14:21, Edward Diener 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).

Edward Diener

2:52 p.m.

On 7/19/2014 9:50 AM, Daniel James wrote:

...

On 19 July 2014 14:21, Edward Diener 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 ? I had ended for the line to be a code block. I had assumed my list had ended. 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.

Edward Diener

3:50 p.m.

On 7/19/2014 10:52 AM, Edward Diener wrote:

...

On 7/19/2014 9:50 AM, Daniel James wrote:

...
On 19 July 2014 14:21, Edward Diener 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 ?

Should have been: Does not a list end when there is a blank line following the last list element ? If not, how does one end a list ?

...

I had ended for the line to be a code block. I had assumed my list had ended.

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.

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Daniel James

20 Jul 20 Jul

9:03 a.m.

On 19 July 2014 15:52, Edward Diener wrote:

...

On 7/19/2014 9:50 AM, Daniel James wrote:

...
On 19 July 2014 14:21, Edward Diener 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.

Andrey Semashev

10:14 a.m.

On Sunday 20 July 2014 10:03:57 Daniel James wrote:

...

It's only changing for lists followed by code blocks, which is an unusual thing to do.

I use code blocks in lists quite often. Things like changelogs and inline examples [1] are the natural use cases. In fact, I think I want to use code blocks in lists more often than multi-paragraph list items. I realize there is ambiguity in the previous syntax but perhaps there could be an option to select the default behavior? [1] http://www.boost.org/doc/libs/1_55_0/libs/log/doc/html/log/detailed/sink_bac...

Daniel James

11:02 a.m.

On 20 July 2014 11:14, Andrey Semashev wrote:

...

On Sunday 20 July 2014 10:03:57 Daniel James wrote:

...
It's only changing for lists followed by code blocks, which is an unusual thing to do.

I use code blocks in lists quite often.

"lists followed by code blocks", not code blocks in lists. The example shows a use of a code block in a list in 1.7: http://www.boost.org/doc/libs/1_55_0/doc/html/quickbook/versions.html#langua...

...

I realize there is ambiguity in the previous syntax but perhaps there could be an option to select the default behavior?

Other than the version switch, I won't introduce any such alternatives. Currently if someone asks about a bit of quickbook, I just need to know which version they're using, but with that I'd have to ask multiple questions - which they probably wouldn't understand, as most people copy their basic setup from someone else.

John Maddock

11:16 a.m.

...

...
It's only changing for lists followed by code blocks, which is an unusual thing to do.

I use code blocks in lists quite often. Things like changelogs and inline examples [1] are the natural use cases. In fact, I think I want to use code blocks in lists more often than multi-paragraph list items. I realize there is ambiguity in the previous syntax but perhaps there could be an option to select the default behavior?

What you're trying to do does not produce a code block *in* a list, but a list *followed* by a code block, in fact this change enables you to do what you want: * An item. `code_block_inside_list_item()` * Next item. John.

Edward Diener

2:14 p.m.

On 7/20/2014 5:03 AM, Daniel James wrote:

...

On 19 July 2014 15:52, Edward Diener wrote:

...
On 7/19/2014 9:50 AM, Daniel James wrote:

...
On 19 July 2014 14:21, Edward Diener 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.

3784

Age (days ago)

3785

Last active (days ago)

List overview

Download

8 comments

4 participants

participants (4)

Andrey Semashev
Daniel James
Edward Diener
John Maddock