Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

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

Hmm. The docstring on that should discuss what it's looking for to say
"this is the end of the state notes".  Does a plain note (org-add-note)
count as a state note?

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

Oh! That's an interesting point.  That variable is not mentioned in the
Manual (AFAICS), but perhaps it should be -- particularly around the
talk of "rescheduling" (and "delschedule" which I don't see in the
manual). Mentioned only in the sense of, if you want to change the note
header, look here.

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

I'd agree.  In particular, what depends on the format of the note
(header) -- like Agenda.  To warn people what they can or cannot touch.

-- 
David Masterson