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