Nicolas Goaziou <n.goaz...@gmail.com> writes: > As discussed a few days ago, here is a document describing the complete > Org syntax as read by the parser. I also added some comments. I am going > to put the Org file on Worg, so anyone can update it and fix mistakes.
[for the record, the org file mentionned by Nicolas is currently at <http://orgmode.org/worg/dev/org-syntax.org>] This looks truly awesome. I give some (naïve) comments below, from my non-expert point of view. > The paragraph is the unit of measurement. An element defines > syntactical parts that are at the same level as a paragraph, i.e. which > cannot contain or be included in a paragraph. An object is a part that > could be included in an element. Greater elements are all parts that > can contain an element. This is very clear but I'm slightly worried about confusion that might come from "Greater element" not being an "element", and the word "element" being a common word : > Empty lines belong to the largest element ending before them. For > example, in a list, empty lines between items belong are part of the > item before them, but empty lines at the end of a list belong to the > plain list element. Is the word "element" (in /largest element ending.../) to be understood as an "element" from the above definition ? I guess not (this would require both list items and plain lists to be on the level 'element', from your example) > 1 Headlines and Sections > ════════════════════════ > > A headline is defined as: > > ╭──── > │ STARS KEYWORD PRIORITY TITLE TAGS > ╰──── > > STARS is a string starting at column 0 and containing at least one > asterisk (and up to `org-inlinetask-min-level' if `org-inlinetask' > library is loaded). It’s the sole compulsory part of a headline. Perhaps it should be mentionned that STARS has to end by a space (see below). I suggest adding : The number of stars defines the level of the headline. > KEYWORD is a TODO keyword, which have to belong to the list defined in > `org-todo-keywords'. Case is significant. The option #+TODO: is used also. > PRIORITY is a priority cookie, i.e. a single letter preceded by a hash > sign # and enclosed within square brackets. Case is significant. I suggest dropping "Case is significant" (or maybe give the whole story : IIRC, it is the ascii code of the given letter that is used as priority) > ╭──── > │ * I don't see a space character after that one in your email and it doesn't seem to be recognized as a headline by the exporter (hence my above suggestion) > If the first word appearing in the title is `org-comment-keyword', > the That should be `org-comment-string' I guess. > A headline contains directly at most one section, followed by any > number of headlines. Only a section can contain another section. >From what I understand, "A section is delimited by two headlines (and buffer limits)." [I initially thought it was "by two headlines of the same level", which it is not from the structure example you give later.] > A section contains directly any greater element or element. Only > a headline can contain a section. As an exception, text before the > first headline in the document also belongs to a section. > In a quoted headline contains a section, the latter will be considered > as a “quote section”. s/In/If/ unsure: s/quote section/quoted section/ ? > As an example, consider the following document: <snip, useful example> > BACKEND is a string constituted of alpha-numeric characters, hyphens > or underscores. I suggest: BACKEND is a string which is an element of (mapcar 'car org-export-registered-backends). > OPTIONAL and VALUE can contain any character but a new line. Only > keywords in `org-element-dual-keywords' can have an optional value. I guess OPTIONAL cannot contain a closing square bracket ] > An affiliated keyword can appear on multiple lines if KEY belongs to > `org-element-multiple-keywords' or if its pattern is “#+ATTR_BACKEND: > VALUE”. I suggest s/on multiple lines/more than once/ > PARAMETERS can contain any character, and can be omitted. any other than new line, I guess. > CONTENTS can contain any element, but another greater block of the > same type. What is the type of a greater block ? the /name/ ? I did have a quick look at the rest of your mail, and it is very nice to have all of it written down explicitly, so again a big thanks for all of this (and the rest of your) work. Unfortunately I don't have much time right now to read it thoroughtfully, so just one single comment : > Even the LaTeX community suggests to use `\(...\)' over > `$...$'. — ngz AFAIK that's not for technical reasons and also I would be curious to know who does that in real documents : '$' is so much more convenient. But one might think of rebinding $ to a command which would insert \( and \) appropriately within org-mode (see below). (OTOH, there are technical reasons for avoiding $$ and $$.) Here some elisp for the above behaviour : (defun yf/org-electric-dollar nil "When called once, insert \\(\\) and leave point in between. When called twice, replace the previously inserted \\(\\) by one $." (interactive) (if (and (looking-at "\\\\)") (looking-back "\\\\(")) (progn (delete-char 2) (delete-char -2) (insert "$")) (insert "\\(\\)") (backward-char 2))) (define-key org-mode-map (kbd "$") 'yf/org-electric-dollar) -- N.