From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Nicolas Richard" Subject: Re: [RFC] Org syntax (draft) Date: Fri, 08 Mar 2013 16:23:02 +0100 Message-ID: <87vc913oh5.fsf@yahoo.fr> References: <8738w7c5fh.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([208.118.235.92]:55177) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UDz8a-0007rk-Bs for emacs-orgmode@gnu.org; Fri, 08 Mar 2013 10:23:17 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UDz8U-00011t-Mw for emacs-orgmode@gnu.org; Fri, 08 Mar 2013 10:23:12 -0500 Received: from plane.gmane.org ([80.91.229.3]:58337) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UDz8U-00011h-CU for emacs-orgmode@gnu.org; Fri, 08 Mar 2013 10:23:06 -0500 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1UDz8o-0002i2-LQ for emacs-orgmode@gnu.org; Fri, 08 Mar 2013 16:23:26 +0100 Received: from geodiff-mac3.ulb.ac.be ([164.15.131.113]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 08 Mar 2013 16:23:26 +0100 Received: from theonewiththeevillook by geodiff-mac3.ulb.ac.be with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 08 Mar 2013 16:23:26 +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: emacs-orgmode@gnu.org 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ï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: > 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.