From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: [RFC] Org syntax (draft) Date: Sat, 9 Mar 2013 15:23:05 +0100 Message-ID: <393C6EDB-3795-42F0-909A-28205E6D6B73@gmail.com> References: <8738w7c5fh.fsf@gmail.com> <87vc913oh5.fsf@yahoo.fr> <87y5dxzgvo.fsf@gmail.com> Mime-Version: 1.0 (Mac OS X Mail 6.2 \(1499\)) Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([208.118.235.92]:42775) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UEKg6-0000zU-DI for emacs-orgmode@gnu.org; Sat, 09 Mar 2013 09:23:20 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UEKfv-0004lE-Fl for emacs-orgmode@gnu.org; Sat, 09 Mar 2013 09:23:14 -0500 Received: from mail-we0-x232.google.com ([2a00:1450:400c:c03::232]:39385) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UEKfv-0004kz-5z for emacs-orgmode@gnu.org; Sat, 09 Mar 2013 09:23:03 -0500 Received: by mail-we0-f178.google.com with SMTP id o45so2186618wer.9 for ; Sat, 09 Mar 2013 06:23:02 -0800 (PST) In-Reply-To: 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: Waldemar Quevedo Cc: Nicolas Richard , emacs-orgmode@gnu.org, Nicolas Goaziou On 9.3.2013, at 11:52, Waldemar Quevedo = wrote: > 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! Maybe someone knowledgeable can turn Nicola's description into a formal = parser description that can then be used by something like yacc to = produce code for arbitrary languages? I am not sure if I am making = sense though. - Carsten >=20 > 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?) >=20 > 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. >=20 > Cheers everyone, keep org-mode being an awesome tool :) >=20 > - Waldemar >=20 > On Sat, Mar 9, 2013 at 7:06 AM, Nicolas Goaziou = wrote: >> Hello, >>=20 >> "Nicolas Richard" writes: >>=20 >>> 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. >>>=20 >>> [for the record, the org file mentionned by Nicolas is currently at >>> ] >>>=20 >>> This looks truly awesome. I give some (na=C3=AFve) comments below, = from my >>> non-expert point of view. >>=20 >> Thank you for your comments. >>=20 >>>> 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. >>>=20 >>> 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 : >>=20 >> 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. >>=20 >>>> 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. >>>=20 >>> 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) >>=20 >> Again, it's a shortcut for "in the largest element or greater element >> ending before them". >>=20 >>>> 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 >>>>=20 >>>> A headline is defined as: >>>>=20 >>>> =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 >>>>=20 >>>> 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 = headline. >>>=20 >>> Perhaps it should be mentionned that STARS has to end by a space = (see >>> below). >>=20 >> I agree. >>=20 >>> I suggest adding : The number of stars defines the level of the >>> headline. >>=20 >> 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'. >>=20 >>>> KEYWORD is a TODO keyword, which have to belong to the list = defined in >>>> `org-todo-keywords'. Case is significant. >>>=20 >>> The option #+TODO: is used also. >>=20 >> Then it should be ~org-todo-keywords-1~, which is where all TODO >> keywords are added eventually. >>=20 >>>> PRIORITY is a priority cookie, i.e. a single letter preceded by a = hash >>>> sign # and enclosed within square brackets. Case is significant. >>>=20 >>> 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) >>=20 >> I'm not sure that the purpose of this document should be to explain = how >> syntax will be used. >>=20 >>>> =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 >>>> =E2=94=82 * >>>=20 >>> 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) >>>=20 >>>> If the first word appearing in the title is `org-comment-keyword', >>>> the >>>=20 >>> That should be `org-comment-string' I guess. >>=20 >> Indeed. Btw, I think this variable should be a defconst, not >> a defcustom. It just makes things harder for little benefit. >>=20 >>>> A headline contains directly at most one section, followed by any >>>> number of headlines. Only a section can contain another section. >>>=20 >>> =46rom 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.] >>=20 >> "Only a section can contain another section" is wrong. It should be >> removed. >>=20 >>>> 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. >>>=20 >>>=20 >>>> In a quoted headline contains a section, the latter will be = considered >>>> as a =E2=80=9Cquote section=E2=80=9D. >>>=20 >>> s/In/If/ >>=20 >> Yes. >>=20 >>> unsure: s/quote section/quoted section/ ? >>=20 >> No, it is "quote section". >>=20 >>>> BACKEND is a string constituted of alpha-numeric characters, = hyphens >>>> or underscores. >>>=20 >>> I suggest: BACKEND is a string which is an element of (mapcar 'car >>> org-export-registered-backends). >>=20 >> Not really. Parser can understand #+attr_foo even if foo is not >> registered as a valid back-end. >>=20 >>>> OPTIONAL and VALUE can contain any character but a new line. Only >>>> keywords in `org-element-dual-keywords' can have an optional = value. >>>=20 >>> I guess OPTIONAL cannot contain a closing square bracket ] >>=20 >> It can. >>=20 >>>> 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. >>>=20 >>> I suggest s/on multiple lines/more than once/ >>=20 >> Ok. >>=20 >>>> PARAMETERS can contain any character, and can be omitted. >>>=20 >>> any other than new line, I guess. >>=20 >> Correct. >>=20 >>>> CONTENTS can contain any element, but another greater block of the >>>> same type. >>>=20 >>> What is the type of a greater block ? the /name/ ? >>=20 >> Yes. I think it should be better to say something like: CONTENTS = cannot >> contain the string "#+END_NAME" on a line on its own. >>=20 >>> 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 : >>>=20 >>>> Even the LaTeX community suggests to use `\(...\)' over >>>> `$...$'. =E2=80=94 ngz >>>=20 >>> 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. >>=20 >> 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. >>=20 >> I also forgot to write about optional #+tblfm: line below Org tables. >>=20 >> Would you (or Someone) mind updating the org-syntax.org file on Worg? >>=20 >> Thank you again. >>=20 >>=20 >> Regards, >>=20 >> -- >> Nicolas Goaziou >>=20 >=20