Re: [RFC] Org syntax (draft)

["Nicolas Richard" <theonewiththeevillook@yahoo.fr>]

Nicolas Goaziou <n.goaziou@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.