From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: [RFC] Org syntax (draft) Date: Fri, 08 Mar 2013 23:06:03 +0100 Message-ID: <87y5dxzgvo.fsf@gmail.com> References: <8738w7c5fh.fsf@gmail.com> <87vc913oh5.fsf@yahoo.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([208.118.235.92]:46879) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UE5Qm-0003M2-RR for emacs-orgmode@gnu.org; Fri, 08 Mar 2013 17:06:30 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UE5Qe-0006yp-3x for emacs-orgmode@gnu.org; Fri, 08 Mar 2013 17:06:24 -0500 Received: from mail-we0-x231.google.com ([2a00:1450:400c:c03::231]:63081) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UE5Qd-0006yk-PF for emacs-orgmode@gnu.org; Fri, 08 Mar 2013 17:06:16 -0500 Received: by mail-we0-f177.google.com with SMTP id d7so1562286wer.36 for ; Fri, 08 Mar 2013 14:06:14 -0800 (PST) In-Reply-To: <87vc913oh5.fsf@yahoo.fr> (Nicolas Richard's message of "Fri, 08 Mar 2013 16:23:02 +0100") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Nicolas Richard Cc: emacs-orgmode@gnu.org Hello, "Nicolas Richard" writes: > Nicolas Goaziou 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 > ] > > This looks truly awesome. I give some (na=C3=AFve) comments below, from my > non-expert point of view. Thank you for your comments. >> 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 co= me > from "Greater element" not being an "element", and the word "element" > being a common word : element means "Element + Greater Element". It is to be understood as the opposite of object. I think there shouldn't be much ambiguity according to context. >> 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) Again, it's a shortcut for "in the largest element or greater element ending before them". >> 1 Headlines and Sections >> =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90= =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2= =95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90 >> >> A headline is defined as: >> >> =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 >> =E2=94=82 STARS KEYWORD PRIORITY TITLE TAGS >> =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 >> >> 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=E2=80=99s the sole compulsory part of a headli= ne. > > Perhaps it should be mentionned that STARS has to end by a space (see > below). I agree. > I suggest adding : The number of stars defines the level of the > headline. Does it belong to the syntax definition? Level is how Org uses syntax internally. Also the sentence, although right, is misleading, because level definition also depends on `org-odd-levels-only'. >> 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. Then it should be ~org-todo-keywords-1~, which is where all TODO keywords are added eventually. >> 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'm not sure that the purpose of this document should be to explain how syntax will be used. >> =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 >> =E2=94=82 * > > 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. Indeed. Btw, I think this variable should be a defconst, not a defcustom. It just makes things harder for little benefit. >> 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.] "Only a section can contain another section" is wrong. It should be removed. >> 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 =E2=80=9Cquote section=E2=80=9D. > > s/In/If/ Yes. > unsure: s/quote section/quoted section/ ? No, it is "quote section". >> 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). Not really. Parser can understand #+attr_foo even if foo is not registered as a valid back-end. >> 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 ] It can. >> An affiliated keyword can appear on multiple lines if KEY belongs to >> `org-element-multiple-keywords' or if its pattern is =E2=80=9C#+ATTR_B= ACKEND: >> VALUE=E2=80=9D. > > I suggest s/on multiple lines/more than once/ Ok. >> PARAMETERS can contain any character, and can be omitted. > > any other than new line, I guess. Correct. >> CONTENTS can contain any element, but another greater block of the >> same type. > > What is the type of a greater block ? the /name/ ? Yes. I think it should be better to say something like: CONTENTS cannot contain the string "#+END_NAME" on a line on its own. > 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 >> `$...$'. =E2=80=94 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. Yes, I mixed $$...$$ and $...$. This sentence could be removed. Though I still maintain my POV about $...$. It may be convenient in a latex file, but in a free-form text format like Org, it's error prone. I also forgot to write about optional #+tblfm: line below Org tables. Would you (or Someone) mind updating the org-syntax.org file on Worg? Thank you again. Regards, --=20 Nicolas Goaziou