Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> 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?

No. See `org-skip-over-state-notes'.

> 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.

Unlike headings, paragraphs, and timestamps, notes are not a part of Org
syntax. Their format is customizeable via `org-log-note-headings'.

However, it is probably worth describing the notes in 5.3 Progress
Logging section of the manual.

> ... 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.

I am not sure if I understand what you mean here.

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

Yes.

-- 
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>