Ihor Radchenko <yanta...@posteo.net> writes: > David Masterson <dsmaster...@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