when rational discussion was still a possibility

[John MacFarlane]

+++ Michel Fortin [Sep 06 14 23:39 ]:

>Are you sure we're talking about the same thing? The issue is that in the middle item your code block content has a two space indent while it is indented by four spaces (minus one for the list marker) in the original. I'd have expected a four character indent to produce a code block with no leading space in its content. One thing that might be confusing here is that the input mixes tabs and spaces and tabs often get rendered as a 8 space indent. Is this really what stmd should be outputing:
>
>http://johnmacfarlane.net/babelmark2/?normalize=1&text=*%09List+Item%3A%0A%0A%09%09code+block%0A%0A%09%09with+a+blank+line%0A%0A%09within+a+list+item.%0A%0A*+++++++code+block%0A%0A++++++++as+first+element+of+a+list+item%0A%0A*%09List+Item%3A%0A%0A%09%09code+block+with+whitespace+on+preceding+line

We're talking about this case, right?

*       code block
        as first element of a list item

If you read the list item section of the spec, you'll see why
stmd works the way it does.  (And the motivations section compares
with alternative rules.)

Short version:  If you look at J.G.'s syntax description, it is
suggestive of the "4-space rule" for determining how far sublists
need to be indented.  It is explicit that a continuation paragraph
should be indented four spaces past the list marker, and that indented
code under the list should be indented eight spaces.  It is not
explicit about sublists, or indeed about indented code that occurs
at the beginning of the list item.  I would have naturally assumed
a 4-space rule throughout, but here the confusion begins, because
Markdown.pl didn't consistently do this, and didn't seem to allow
indented code at the beginning of a list item at all.

We considered the 4-space rule (as used in pandoc) as a coherent and
simple rule for determining where content must be placed in list items,
but it seemed too rigid and unforgiving of content that writers would
very naturally write.  For example, this is just obviously a nested list:

- a
  - b
  - c

Implementations are just all over the place on this, and many
give crazy results, e.g. Markdown.pl and PHP Markdown both interpret
this example

   - one

  two

as a list containing two paragraphs:
http://johnmacfarlane.net/babelmark2/?normalize=1&text=+++-+one%0A%0A++two%0A%0A

stmd uses the following basic idea, which I think goes naturally with
how writers think of lists:  The indentation required for a sublist,
continuation paragraph, or other included content is determined by
the position of the content on the opening line.  So, if your list
begins

-   a

then your continuation paragraph should be indented four spaces.

But if it begins

- a

then your continuation  should be indented two spaces.

And if it begins

  -   a

then your continuation should be indented six spaces.

All of this presupposes that we don't have indented code on the first
line.  The problem is, by the rules above there's no *fixed* position
for indented code in a list item, since it depends on the first line.
So where should indented code go if it's in the first line?  We settle
that with a rule that indented code in the first line should be indented
five spaces:  one space after the list marker, and four spaces which
can be thought of as the usual indentation for indented code.

That's why you get the two spaces there.

Note that if you started the list this way, it would

  *     code block
        as first element of a list item

it would give the results you expect.