[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [O] [RFC] Org syntax (draft)
From: |
Nicolas Goaziou |
Subject: |
Re: [O] [RFC] Org syntax (draft) |
Date: |
Fri, 08 Mar 2013 23:06:03 +0100 |
Hello,
"Nicolas Richard" <address@hidden> writes:
> Nicolas Goaziou <address@hidden> 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
- Re: [O] (no subject), (continued)
- Re: [O] (no subject), Andreas Röhler, 2013/03/08
- Re: [O] (no subject), Bastien, 2013/03/08
- Re: [O] (no subject), T.F. Torrey, 2013/03/08
- Re: [O] (no subject), Nicolas Goaziou, 2013/03/08
- Re: [O] (no subject), Suvayu Ali, 2013/03/08
- [O] interoperability matters Re: (no subject), Gregor Zattler, 2013/03/08
- Re: [O] (no subject), Bastien, 2013/03/09
- Re: [O] (no subject), T.F. Torrey, 2013/03/11
Re: [O] [RFC] Org syntax (draft), François Pinard, 2013/03/08
Re: [O] [RFC] Org syntax (draft), Nicolas Richard, 2013/03/08
- Re: [O] [RFC] Org syntax (draft),
Nicolas Goaziou <=
Re: [O] [RFC] Org syntax (draft), Nicolas Goaziou, 2013/03/15
Re: [O] [RFC] Org syntax (draft), Samuel Wales, 2013/03/17
Re: [O] [RFC] Org syntax (draft), Nicolas Richard, 2013/03/13
Re: [O] [RFC] Org syntax (draft), Nicolas Goaziou, 2013/03/15
Re: [O] [RFC] Org syntax (draft), Achim Gratz, 2013/03/09