emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Carsten Dominik <carsten.dominik@gmail.com>
To: Waldemar Quevedo <waldemar.quevedo@gmail.com>
Cc: Nicolas Richard <theonewiththeevillook@yahoo.fr>,
	emacs-orgmode@gnu.org, Nicolas Goaziou <n.goaziou@gmail.com>
Subject: Re: [RFC] Org syntax (draft)
Date: Sat, 9 Mar 2013 15:23:05 +0100	[thread overview]
Message-ID: <393C6EDB-3795-42F0-909A-28205E6D6B73@gmail.com> (raw)
In-Reply-To: <CALzn4yiV7tJZtBgNbyDqWd+=qykGvKGuvMdP=iTYR+tm+ptu=Q@mail.gmail.com>


On 9.3.2013, at 11:52, Waldemar Quevedo <waldemar.quevedo@gmail.com> 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

> 
> 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 <n.goaziou@gmail.com> wrote:
>> Hello,
>> 
>> "Nicolas Richard" <theonewiththeevillook@yahoo.fr> writes:
>> 
>>> 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.
>> 
>> 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 come
>>> 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
>>>> ════════════════════════
>>>> 
>>>>  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 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.
>> 
>>>>  ╭────
>>>>  │ *
>>> 
>>> 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 “quote section”.
>>> 
>>> 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 “#+ATTR_BACKEND:
>>>>  VALUE”.
>>> 
>>> 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
>>>>       `$...$'.  — 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
>> 
> 

  reply	other threads:[~2013-03-09 14:23 UTC|newest]

Thread overview: 58+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2013-03-07 20:37 [RFC] Org syntax (draft) Nicolas Goaziou
2013-03-07 20:47 ` Carsten Dominik
2013-03-07 22:07 ` Achim Gratz
2013-03-08 10:04 ` Bastien
2013-03-08 10:39 ` was: " Andreas Röhler
2013-03-08 10:46   ` (no subject) Bastien
2013-03-08 10:59     ` Andreas Röhler
2013-03-08 11:05       ` Bastien
2013-03-08 11:18         ` Andreas Röhler
2013-03-08 11:23           ` Bastien
2013-03-08 13:00             ` Andreas Röhler
2013-03-08 13:12               ` Bastien
2013-03-08 15:22                 ` Andreas Röhler
2013-03-08 15:40                   ` Bastien
2013-03-08 20:39                     ` T.F. Torrey
2013-03-08 21:19                       ` Nicolas Goaziou
2013-03-08 21:57                         ` Suvayu Ali
2013-03-08 22:15                       ` interoperability matters " Gregor Zattler
2013-03-09 14:09                       ` Bastien
2013-03-10 22:40                         ` T.F. Torrey
2013-03-08 13:25 ` [RFC] Org syntax (draft) François Pinard
2013-03-08 15:23 ` Nicolas Richard
2013-03-08 22:06   ` Nicolas Goaziou
2013-03-09 10:52     ` Waldemar Quevedo
2013-03-09 14:23       ` Carsten Dominik [this message]
2013-03-09 14:42         ` Nicolas Goaziou
2013-03-09 15:05           ` Carsten Dominik
2013-03-15 20:22       ` Nicolas Goaziou
2013-03-17 18:48       ` Samuel Wales
2013-04-05 17:01       ` Bastien
2013-03-13 14:07     ` Nicolas Richard
2013-03-15 20:39       ` Nicolas Goaziou
2013-03-09 23:16 ` Achim Gratz
2013-03-09 23:49   ` Nicolas Goaziou
2013-03-10  4:35     ` Jambunathan K
2013-03-10  7:08       ` Nicolas Goaziou
2013-03-10 10:14         ` Bastien
2013-03-10 10:16           ` Bastien
2013-03-10 13:07             ` Achim Gratz
2013-03-10 14:11               ` Bastien
2013-03-10 16:02                 ` Achim Gratz
2013-03-10 16:09                   ` Jambunathan K
2013-03-10 17:12                     ` Achim Gratz
2013-03-10 21:44                       ` Jonathan Leech-Pepin
2013-03-10 15:44           ` Jambunathan K
2013-03-14 16:58             ` Eric S Fraga
2013-03-14 18:26               ` Jambunathan K
2013-03-14 18:51                 ` David Engster
2013-03-14 19:03                   ` [Out-of-Thread] " Jambunathan K
2013-03-14 19:15                     ` David Engster
2013-03-14 19:23                       ` Jambunathan K
2013-03-14 19:29                         ` David Engster
2013-03-14 19:52                           ` Jambunathan K
2013-04-09 16:37           ` Bastien
2013-03-17  7:18 ` Achim Gratz
2013-03-17  9:36   ` Sebastien Vauban
  -- strict thread matches above, loose matches on Subject: below --
2013-03-12 10:19 orgmode
2013-03-13 15:33 ` Nicolas Goaziou

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=393C6EDB-3795-42F0-909A-28205E6D6B73@gmail.com \
    --to=carsten.dominik@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=n.goaziou@gmail.com \
    --cc=theonewiththeevillook@yahoo.fr \
    --cc=waldemar.quevedo@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).