From mboxrd@z Thu Jan 1 00:00:00 1970 From: Waldemar Quevedo Subject: Re: [RFC] Org syntax (draft) Date: Sat, 9 Mar 2013 19:52:08 +0900 Message-ID: References: <8738w7c5fh.fsf@gmail.com> <87vc913oh5.fsf@yahoo.fr> <87y5dxzgvo.fsf@gmail.com> 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]:60225) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UEHOG-0006YT-9z for emacs-orgmode@gnu.org; Sat, 09 Mar 2013 05:52:42 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UEHO9-00071h-Hi for emacs-orgmode@gnu.org; Sat, 09 Mar 2013 05:52:36 -0500 Received: from mail-ob0-x236.google.com ([2607:f8b0:4003:c01::236]:41590) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UEHO9-00071Q-AV for emacs-orgmode@gnu.org; Sat, 09 Mar 2013 05:52:29 -0500 Received: by mail-ob0-f182.google.com with SMTP id va7so2022237obc.13 for ; Sat, 09 Mar 2013 02:52:28 -0800 (PST) In-Reply-To: <87y5dxzgvo.fsf@gmail.com> 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 Goaziou Cc: Nicolas Richard , emacs-orgmode@gnu.org Hey Nicolas, this looks very detailed and I think it could be useful for people trying to write other parsers implementations for org-mode. Thanks for sharing! By the way, does it exist somewhere a set of examples of Emacs org-mode -> html conversion for all org-mode features? (How are changes from org-mode -> html converstion from Emacs tested during development?) I am mantaining the org-ruby gem which is used to render org-mode texts to = html, and currently there is no "roadmap" of features to implement for it. As a result, features and tweaks are added to the library as long as someone submits a ticket requesting the feature in Github. (Here is a list of the export features supported in case someone wants to take a look: https://github.com/bdewey/org-ruby/tree/master/spec/html_examples ) Having a set of examples features from org-mode would be very useful to see how much coverage other implementations of org-mode exporting features have. Cheers everyone, keep org-mode being an awesome tool :) - Waldemar On Sat, Mar 9, 2013 at 7:06 AM, Nicolas Goaziou wrote= : > 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 goin= g >>> 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 c= ome >> 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 headl= ine. >> >> 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 i= n >>> `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 has= h >>> 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 considere= d >>> 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_= BACKEND: >>> 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, > > -- > Nicolas Goaziou >