Re: Clarification on blank lines following list items

[Ihor Radchenko]

"Tom Alexander" <tom@fizz.buzz> writes:

> I am noticing the list items have some very context-sensitive specific 
> behavior regarding ownership of the trailing blank lines. I was hoping to get 
> some clarification on this (namely, are my observations correct, am I 
> stumbling across a bug, or have I not dug deep enough to suss out the real 
> rules?). The org-mode documentation states:
>
>> With the exception of list items and footnote definitions blank lines belong 
>> to the preceding element with the narrowest possible scope
>
> but it does not state who ends up owning those blank lines.

I can see how this explanation steered you into wrong line of thoughts.
It should better be explained from the widest scope to the narrowest
scope, not the opposite.

Greater Org elements are generally represented by contents where child
elements are located + markup defining the greater element itself +
optional trailing blank lines.

For example, drawers are

:NAME:
<contents begin>
...
<contents end>:END:
<blank lines>

Naturally, blank lines are the attribute of such drawer - they belong to
it and are recorded as :post-blank property.

The above works for many greater elements. However, it becomes a bit
tricky when a greater element does not have any "end" delimiter:

--------
- item
  Some text
  Or even
  :drawer:
  with text
  :end:

Not an item.
--------

Now, assigning contents vs. blank lines is not so obvious. We can either
include these blank lines into contents or keep them separate within
:post-blank property.

Then, there are two kinds of greater elements that can end with blank
lines without separator:

1. Elements where blank lines do not affect parsing (headlines)

2. Elements where trailing blank lines are syntactically meaningful and
   by themselves serve as a marker of element ending.
   
   - footnote-definition ends when Org see two consecutive blank lines
     or a heading or another footnote-definition.
     
   - plain-list also uses two consecutive blank lines as delimiter.

   
In the second case, Org makes the plain-list/footnote-definition element
"own" the blank lines (set :post-blank) instead of putting these blank
lines inside contents. If we did otherwise, changes in contents could
make the parent plain-list/footnote-definition invalid - if the double
blank delimiter is edited away.

-----

Further, there is a special case with greater elements without contents:

* Heading with no contents


* Another heading

The first heading does not have contents, yet we want to record the fact
that it has multiple blank lines before the next element - :post-blank
here is set, unlike heading with contents.

-----

Finally, :post-blank in items is special.

Consider:

- item 1

- item 2

- item 3

We do not treat blank between items as parts of their paragraphs
historically. Also, it makes sense for such short items.
(there are actually some reasons why we might want to alter this
historical convention, but for now it is how it is)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>