Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> We do document the line breaks in
>>> https://orgmode.org/manual/Paragraphs.html
>>
>> The only thing I see with respect to '\\' is:
>>
>>   Paragraphs are separated by at least one empty line.  If you need to
>>   enforce a line break within a paragraph, use ‘\\’ at the end of a line.
>>
>> Which doesn't answer the question of why org-add-note (etc) added it the
>> end of the first line of a Note which lead to my confusion. It's easy to
>> assume, if Org is adding '\\' to the first line of the Note and the Note
>> is a unit, then this is there to prevent folding/wrapping in the Note
>> when Org does "something" (but what?).
>
> Line break is a "forced" break of a line in paragraph. When there is a
> line break, paragraph does not re-flow to the page width.
>
> Re-flow may imply different things, including `fill-region' command in
> Emacs or paragraph layout during export.
>
> The detailed reason why we use this particular markup is that
> otherwise some internal code assumptions inside Org mode may break when
> users run `fill-region' on the notes. This is an internal implementation
> detail which should not be explained in the manual.

Hmm.  Fill-region will also compress the blanks in the generate note
header -- does that run up against the code assumptions?

I'm all for keeping internal implementation details out of the user's
manual, unless...

> What we might explain better is what is a line break, although I am not
> very sure what to explain here - I may be too familiar with the concept
> from my LaTeX-foo.

The manual should set expectations on what an Org file should look like
-- at least the key components.  It already defines Header, Paragraph
and Timestamp. What I think is missing here is the definition of a Note
along with some structure info about it (header line + 2 space indented
paragraphs[s]) to prepare the user.  In this, I probably come from a
more Reference Manual viewpoint (ie. "this is what all the pieces could
look like -- now lets discuss why you want each piece"). You could say
that the '\\' is needed to keep "other things" from combining the header
and paragraph of the note.  You could leave the details of "other
things" to variable or function docstrings as well as internal code.

p.s. would requiring a blank line after the Note header eliminate the
need for '\\' ?

-- 
David Masterson