Re: [O] [RFC] Org syntax (draft)
Hi all, Bastien b...@altern.org writes: the manual would enjoy a subsection in Hacking on how to create a new exporter, either from scratch or as a derived exporter. (Such a subsection can be short enough, thanks to derived backend.) FWIW, I started a rudimentary one. This is Adding export back-ends in the current manual from master. -- Bastien
Re: [O] [RFC] Org syntax (draft)
Hi Waldemar, Waldemar Quevedo waldemar.quev...@gmail.com writes: By the way, does it exist somewhere a set of examples of Emacs org-mode - html conversion for all org-mode features? Not really -- and it would be nice to have one, especially for developers like you who are in charge of an external exporter! 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 :) Thank *you* for maintaining the org-ruby gem -- truly a gem to the github community! Hopefully you'll be able to update the gem wrt the latest syntactic changes. There are not too many of them, and not every will use Org 8.0 so soon, but still. Best, -- Bastien
Re: [O] [RFC] Org syntax (draft)
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. after some playing with the Org manual in Org that Tom has been working on I am starting to think that there should be a way to define the same macro differently for different export backends. That would be mainly so that you could have a macro expansion use export snippets tailored to that backend where (after stripping the export snippets) the expansion makes little or no sense in other backends. What do you think? Regards, Achim. -- +[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]+ DIY Stuff: http://Synth.Stromeko.net/DIY.html
Re: [O] [RFC] Org syntax (draft)
Hi Achim,
Achim Gratz wrote:
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.
after some playing with the Org manual in Org that Tom has been working
on I am starting to think that there should be a way to define the same
macro differently for different export backends. That would be mainly
so that you could have a macro expansion use export snippets tailored to
that backend where (after stripping the export snippets) the expansion
makes little or no sense in other backends. What do you think?
This is already possible, as once explained by Nicolas on this ML:
╭
│ You can also have macros generating raw code geared towards LaTeX or HTML
│ back-ends (through export-snippets). For example:
│
│ #+MACRO: my-mod @@e-latex:\something{$1}e-html:div
class=something$1/div@@
│
│ This is an example: {{{my-mod(text)}}}.
╰
Best regards,
Seb
--
Sebastien Vauban
Re: [O] [RFC] Org syntax (draft)
On 3/9/13, Waldemar Quevedo waldemar.quev...@gmail.com wrote: 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?) +1 That would be great. I'd definitely donate any of my blog posts, but perhaps others have more comprehensive tests. Samuel -- The Kafka Pandemic: http://thekafkapandemic.blogspot.com The disease DOES progress. MANY people have died from it. Just like AIDS, it attacks MANY body systems. ANYBODY can get it. There is NO hope without activist action. This means YOU.
Re: [O] [RFC] Org syntax (draft)
Hello, Waldemar Quevedo waldemar.quev...@gmail.com writes: 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 don't think something like this exists. Though, html back-end supports all Org syntax described in the document. Regards, -- Nicolas Goaziou
Re: [O] [RFC] Org syntax (draft)
Hello, Nicolas Richard theonewiththeevill...@yahoo.fr writes: As you know, Comment is also a french word meaning how, and that could very well appear uppercased as the first word of a title. (I'd personally recommend against uppercasing titles, but I'd understand if someone wanted to customize the word for such reasons) Comment is not COMMENT, as you say. Also, it is a minor annoyance. On the other hand, crippling portability of Org format because it depends on an external variable is a major problem. Therefore, I stand on my ground: I suggest to turn `org-comment-string' and al. into defconst. Would you (or Someone) mind updating the org-syntax.org file on Worg? Please review the attached patch and apply parts as you wish (even if I wanted to do it myself, I don't have worg access.) I applied the patch. Thank you. Last word about #+TBLFM: I'm not sure if that should go into the affiliated keywords section (thus rewriting parts of it, because that one goes below the table, unlike other affiliated keywords) or a special section on its own. Thus I'm not changing anything wrt that. TBLFM is not an affiliated keyword. It's a keyword specific to Org tables. It can exist anywhere, but it only makes sense right after a table. Regards, -- Nicolas Goaziou
Re: [O] [RFC] Org syntax (draft)
Jambunathan K kjambunat...@gmail.com writes: You are a jerk, a BIG JERK. This is completely uncalled. What satisfaction do you gain from this? This is a brilliant, informative and polite mailing list except when it comes to your contributions. Don't bother answering because I've added you to my spam database. I've not had to do this for an individual for some years now. I'll never see any of your emails again. Bye. -- : Eric S Fraga, GnuPG: 0xC89193D8FFFCF67D : in Emacs 24.3.50.1 and Org release_7.9.3f-1199-g3a0e55
Re: [O] [RFC] Org syntax (draft)
Eric Eric S Fraga e.fr...@ucl.ac.uk writes: Jambunathan K kjambunat...@gmail.com writes: You are a jerk, a BIG JERK. This is completely uncalled. What satisfaction do you gain from this? This is a brilliant, informative and polite mailing list except when it comes to your contributions. Don't bother answering because I've added you to my spam database. I've not had to do this for an individual for some years now. I'll never see any of your emails again. Bye. Still you haven't answered my Fudging the mail reply headers question to my satisfaction. I just let you off the hook (at the last moment) before charging ahead. Jambunathan K. --
Re: [O] [RFC] Org syntax (draft)
Jambunathan K. writes: Still you haven't answered my Fudging the mail reply headers question to my satisfaction. http://www.gnu.org/software/emacs/manual/html_node/message/Mailing-Lists.html A mailing list poster can use MFT to express that responses should be sent to just the list, and not the poster as well. This will happen if the poster is already subscribed to the list. -David
Re: [O] [RFC] Org syntax (draft)
Hi, I obviously did not send and actually lost a message I prepared two days ago. I'll try again. 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'. I think it's partly in the syntax, since it defines parentness for headlines (the numeric level is of no importance, but the relative level is used). 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. That is why I suggested dropping the mention : case is not significant for the syntax. Very minor though, obviously. 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. As you know, Comment is also a french word meaning how, and that could very well appear uppercased as the first word of a title. (I'd personally recommend against uppercasing titles, but I'd understand if someone wanted to customize the word for such reasons) Would you (or Someone) mind updating the org-syntax.org file on Worg? Please review the attached patch and apply parts as you wish (even if I wanted to do it myself, I don't have worg access.) Last word about #+TBLFM: I'm not sure if that should go into the affiliated keywords section (thus rewriting parts of it, because that one goes below the table, unlike other affiliated keywords) or a special section on its own. Thus I'm not changing anything wrt that. From f97c00bfbd8a14d0b2953ee0e8b6817a2b9f0306 Mon Sep 17 00:00:00 2001 From: Nicolas Richard theonewiththeevill...@yahoo.fr Date: Mon, 11 Mar 2013 16:25:21 +0100 Subject: [PATCH] dev/org-syntax.org: minor --- dev/org-syntax.org | 34 +++--- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/dev/org-syntax.org b/dev/org-syntax.org index 9b2a843..a918a75 100644 --- a/dev/org-syntax.org +++ b/dev/org-syntax.org @@ -15,7 +15,8 @@ within specific environments. Three categories are used to classify these environments: Greater elements, elements, and objects, from the broadest scope to the -narrowest. +narrowest. The word element is used for both Greater and non-Greater +elements, the context should make that clear. The paragraph is the unit of measurement. An element defines syntactical parts that are at the same level as a paragraph, @@ -41,16 +42,17 @@ Unless specified otherwise, case is not significant. STARS KEYWORD PRIORITY TITLE TAGS #+END_EXAMPLE - STARS is a string starting at column 0 and containing at least one + STARS is a string starting at column 0, 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. + library is loaded) and ended by a space character. The number of + asterisks is used to define the level of the headline. It's the + sole compulsory part of a headline. KEYWORD is a TODO keyword, which has to belong to the list defined - in ~org-todo-keywords~. Case is significant. + in ~org-todo-keywords-1~. Case is significant. PRIORITY is a priority cookie, i.e. a single letter preceded by - a hash sign # and enclosed within square brackets. Case is - significant. + a hash sign # and enclosed within square brackets. TITLE can be made of any character but a new line. Though, it will match after every other part have been matched. @@ -71,7 +73,7 @@ Unless specified otherwise, case is not significant. , TODO [#A] COMMENT Title :tag:a2%: #+END_EXAMPLE - If the first word appearing in the title is ~org-comment-keyword~, + If the first word appearing in the title is ~org-comment-string~, the headline will be considered as commented. If that first word is ~org-quote-string~, it will be considered as quoted. In both situations, case is significant. @@ -82,14 +84,14 @@ Unless specified otherwise, case is not significant. If ~org-archive-tag~ is one of its tags, it will be considered as archived. Case is significant. - A headline contains directly at most one section, followed by any - number of headlines. Only a section can contain another section. + A headline contains directly one section, followed by any + number of deeper level headlines. 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 + If a quoted headline contains a section, the latter will be considered as a quote section.
Re: [O] [RFC] Org syntax (draft)
Hello, orgm...@h-rd.org writes: What may help is to document the syntax machine readable and somewhat more formal. I think it's a bit too early for that. The document describes the current syntax, but also uncovers some ambiguous parts of that syntax, which may need to be fixed (at least require to be discussed). I agree that both tasks can be done in parallel, but I wouldn't like the one you propose to shadow the one that I describe. Anyway, improvements are welcome. Feel free to provide a patch for the document. This ensures that there are less differences in interpretation and that the specification can be used to generate an orgmode parser directly. An example could be how the ietf specifies things, have a look at https://en.wikipedia.org/wiki/ABNF or EBNF. It's not much difference from what you have done, but it's more unambigous. Regards, -- Nicolas Goaziou
Re: [O] [RFC] Org syntax (draft)
Hi Nicolas, great work! It's fantastic that orgmode now gets a specification. What may help is to document the syntax machine readable and somewhat more formal. This ensures that there are less differences in interpretation and that the specification can be used to generate an orgmode parser directly. An example could be how the ietf specifies things, have a look at https://en.wikipedia.org/wiki/ABNF or EBNF. It's not much difference from what you have done, but it's more unambigous. Thanks for the great work!
Re: [O] [RFC] Org syntax (draft)
Hi Nicolas, the manual would enjoy a subsection in Hacking on how to create a new exporter, either from scratch or as a derived exporter. (Such a subsection can be short enough, thanks to derived backend.) From this section, we can throw links to the exporter reference document and the Org syntax document published on Worgs. We may also add footnotes referring to the Org syntax relevant sections, when needed. But both reference documents don't fit into the manual IMO. They are great resources for developers, not for users. The footnotes are enough for advanced users who want to go beyond the manual. Thanks! -- Bastien
Re: [O] [RFC] Org syntax (draft)
Bastien b...@altern.org writes: But both reference documents don't fit into the manual IMO. They are great resources for developers, not for users. The footnotes are enough for advanced users who want to go beyond the manual. That said, we can also bundle both documents into Org's distribution, as .org files in the doc/ directory. And have a make rule to convert them to .pdf and info docs. -- Bastien
Re: [O] [RFC] Org syntax (draft)
Bastien writes: That said, we can also bundle both documents into Org's distribution, as .org files in the doc/ directory. And have a make rule to convert them to .pdf and info docs. I don't want to be the party pooper, but if these documents should go into the distribution, then we must insist that all modifications be FSF copyrighted, otherwise we'd have to remove and/or rewrite the ones that aren't when they are incorporated into the distribution. Regards, Achim. -- +[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]+ SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2: http://Synth.Stromeko.net/Downloads.html#WaldorfSDada
Re: [O] [RFC] Org syntax (draft)
Achim Gratz strom...@nexgo.de writes: Bastien writes: That said, we can also bundle both documents into Org's distribution, as .org files in the doc/ directory. And have a make rule to convert them to .pdf and info docs. I don't want to be the party pooper, but if these documents should go into the distribution, then we must insist that all modifications be FSF copyrighted, otherwise we'd have to remove and/or rewrite the ones that aren't when they are incorporated into the distribution. No, the documents can go into the distribution with contributions from anyone, because they won't be in Emacs. FSF assignment is needed only for things that go into Emacs. Best, -- Bastien
Re: [O] [RFC] Org syntax (draft)
Bastien But both reference documents don't fit into the manual IMO. You are a jerk, a BIG JERK. Jambunathan K. --
Re: [O] [RFC] Org syntax (draft)
Bastien writes: No, the documents can go into the distribution with contributions from anyone, because they won't be in Emacs. FSF assignment is needed only for things that go into Emacs. I understood that these or substantial parts of it will end up in the Org manual, which is in Emacs. If that's not the case, then disregard my comment. Regards, Achim. -- +[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]+ SD adaptation for Waldorf rackAttack V1.04R1: http://Synth.Stromeko.net/Downloads.html#WaldorfSDada
Re: [O] [RFC] Org syntax (draft)
Achim Gratz strom...@nexgo.de writes: Bastien writes: No, the documents can go into the distribution with contributions from anyone, because they won't be in Emacs. FSF assignment is needed only for things that go into Emacs. I understood that these or substantial parts of it will end up in the Org manual, which is in Emacs. If that's not the case, then disregard my comment. Emacs lisp has a manual of it's own. I don't see how Org export reference *cannot* end in Emacs. Bastien is doing what(ever) suits his whims and you are approving of it. I disapprove of what you are doing, Achim. Export syntax deserves to be part of Org/Emacs. Let the maintainer go to hell. He is talking irreverently/hand-wavingly about some work which has stretched to good part of around 3 years. The Orgmode maintainership is in the hands of the wrong person, he calls shots based on his owh whims and I regret it. Jambunathan K. Regards, Achim. --
Re: [O] [RFC] Org syntax (draft)
Jambunathan K writes: Emacs lisp has a manual of it's own. I don't see how Org export reference *cannot* end in Emacs. I said that I'm expecting these references to become part of the manual(s). I still expect that and will try to help it along, but it doesn't necessarily need to take the exact sequence of events that I envisioned. Bastien is doing what(ever) suits his whims and you are approving of it. I haven't approved or disapproved anything. I have only stated the plain fact that if my understanding of the future course of events is incorrect, then my comment does not apply (and conversely, if it does, then the issue I've stated needs to be dealt with). I disapprove of what you are doing, Achim. You're welcome. (Sun Tzu, III/2) Regards, Achim. -- +[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]+ SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2: http://Synth.Stromeko.net/Downloads.html#WaldorfSDada
Re: [O] [RFC] Org syntax (draft)
Hello On 10 March 2013 13:12, Achim Gratz strom...@nexgo.de wrote: Jambunathan K writes: Emacs lisp has a manual of it's own. I don't see how Org export reference *cannot* end in Emacs. I said that I'm expecting these references to become part of the manual(s). I still expect that and will try to help it along, but it doesn't necessarily need to take the exact sequence of events that I envisioned. I have to agree with Bastien that they do not really fit into the main Org manual. Providing them with Emacs (so that they are immediately available) is a good thing in my mind, however I would put them as a separate document similarly to how the Elisp manual is separate. Regards, Jon Bastien is doing what(ever) suits his whims and you are approving of it. I haven't approved or disapproved anything. I have only stated the plain fact that if my understanding of the future course of events is incorrect, then my comment does not apply (and conversely, if it does, then the issue I've stated needs to be dealt with). I disapprove of what you are doing, Achim. You're welcome. (Sun Tzu, III/2) Regards, Achim. -- +[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]+ SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2: http://Synth.Stromeko.net/Downloads.html#WaldorfSDada
Re: [O] [RFC] Org syntax (draft)
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 n.goaz...@gmail.com wrote: Hello, Nicolas Richard theonewiththeevill...@yahoo.fr writes: Nicolas Goaziou n.goaz...@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.]
Re: [O] [RFC] Org syntax (draft)
On 9.3.2013, at 11:52, Waldemar Quevedo waldemar.quev...@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.goaz...@gmail.com wrote: Hello, Nicolas Richard theonewiththeevill...@yahoo.fr writes: Nicolas Goaziou n.goaz...@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.
Re: [O] [RFC] Org syntax (draft)
Hello, Carsten Dominik carsten.domi...@gmail.com writes: On 9.3.2013, at 11:52, Waldemar Quevedo waldemar.quev...@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. *cough* you mean GNU Bison or, perhaps better, Wisent (from Semantic). I don't know how well they handle context sensitive grammars, though.. Regards, -- Nicolas Goaziou
Re: [O] [RFC] Org syntax (draft)
On 9.3.2013, at 15:42, Nicolas Goaziou n.goaz...@gmail.com wrote: Hello, Carsten Dominik carsten.domi...@gmail.com writes: On 9.3.2013, at 11:52, Waldemar Quevedo waldemar.quev...@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. *cough* you mean GNU Bison Told you I am not sure if I am making sense. Anyway, a general parser would be useful for extensions like org-ruby... - Carsten
Re: [O] [RFC] Org syntax (draft)
Hi Nicolas, here are my first comments. I'm still trying to wrap my head around some things, so if I'm off the map on something, please be patient. Do you mind if I fix some obvious typos directly on Worg or do you'd rather want patches? Nicolas Goaziou writes: A core concept in this syntax is that only headlines and sections are context-free[1][2]. Every other syntactical part only exists within specific environments. Blank lines or empty lines are also context-free syntactical elements, I'd think. Three categories are used to classify these environments: “Greater elements”, “elements”, and “objects”, from the broadest scope to the narrowest. It might be easier to talk about those things if Greater Element was called Collection to perhaps keep with the thingies theme of naming the syntax. 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. Here's my main contention with that model: I think there should be an greater element, maybe named paragraph block that translates into a paragraph at the backend level. Most backends will have a paragraph model that is much less limited than what the current definition of an Org paragraph is. This could be optionally be an implicit greater block that is defined by the presence or absence of blank lines between elements, I'd think. 3.1 Greater Blocks ── The same naming confusion as with the various elements, for now I'd link to think of these as Box. Greater blocks consist in the following pattern: ╭ │ #+BEGIN_NAME PARAMETERS │ CONTENTS │ #+END_NAME ╰ I'm beginning to wonder if these should have the same syntax as blocks. Maybe that's a too fine a distinction visually, but adding a colon would disambiguate the greater blocks from the normal ones. In other words #+BEGIN_CENTER: humdum … #+END_CENTER: would be a center block, while #+BEGIN_CENTER humdum … #+END_CENTER would be an export block for the center backend. 4.2 Blocks ── Like [greater blocks], pattern for blocks is: ╭ │ #+BEGIN_NAME DATA │ CONTENTS │ #+END_NAME ╰ […] DATA can contain any character but a new line. I'd keep with PARAMETERS here. If NAME is a string matching the name of any export back-end loaded, the block will be an “export block”. Conversely, blocks that are not having a recognizable name will simply insert their content as if the block markers were not there, e.g. it seems to treat these as parsed blocks. I don't think this should happen, instead Org should parse this as an unknown export backend and drop the content with a warning, not unlike a comment. This will be a major sticking point with external parsers: they'd otherwise need to know about the Org export backends to when to use the content of the block and when not. A portable Org document should be able to specify which export backends it expects to be available (and maybe what standard backend it is derived from) to elicit the correct behaviour. CONTENTS can contain any character, including new lines. Though it will only contain Org objects if the block is a verse block. Otherwise, contents will not be parsed. Would it make sense to make a general distinction between parsed and non-parsed blocks based on some configuration, even though this would produce the same issue as with export backends? I suggest to remove angle links. If one needs spaces in PATH, she can use standard link syntax instead. They are very ubiquitous on certain platforms, so copypaste would be made frustrating there if you'd need to re-format them each time around. Regards, Achim. -- +[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]+ SD adaptation for Waldorf Blofeld V1.15B11: http://Synth.Stromeko.net/Downloads.html#WaldorfSDada
Re: [O] [RFC] Org syntax (draft)
Hello,
Achim Gratz strom...@nexgo.de writes:
Do you mind if I fix some obvious typos directly on Worg or do you'd
rather want patches?
Please go ahead. This is on Worg so anyone can improve it.
Nicolas Goaziou writes:
A core concept in this syntax is that only headlines and sections are
context-free[1][2]. Every other syntactical part only exists within
specific environments.
Blank lines or empty lines are also context-free syntactical elements,
I'd think.
No, the aren't, as they belong to the broadest element ending before
them. So you need to know what this element is.
Three categories are used to classify these environments: “Greater
elements”, “elements”, and “objects”, from the broadest scope to the
narrowest.
It might be easier to talk about those things if Greater Element was
called Collection to perhaps keep with the thingies theme of naming
the syntax.
Collection could also be ambiguous as a paragraph may be seen as
a collection of objects.
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.
Here's my main contention with that model: I think there should be an
greater element, maybe named paragraph block that translates into a
paragraph at the backend level. Most backends will have a paragraph
model that is much less limited than what the current definition of an
Org paragraph is. This could be optionally be an implicit greater
block that is defined by the presence or absence of blank lines between
elements, I'd think.
I don't get it. What would be the exact definition of a paragraph
block? What limitations are you talking about?
3.1 Greater Blocks
──
The same naming confusion as with the various elements, for now I'd
link to think of these as Box.
This naming was for the org-syntax file only. Greater blocks means
nothing for org-element.el, but center block, quote block, special
block do.
Greater blocks consist in the following pattern:
╭
│ #+BEGIN_NAME PARAMETERS
│ CONTENTS
│ #+END_NAME
╰
I'm beginning to wonder if these should have the same syntax as blocks.
Maybe that's a too fine a distinction visually, but adding a colon would
disambiguate the greater blocks from the normal ones. In other words
#+BEGIN_CENTER: humdum
#+END_CENTER:
would be a center block, while
#+BEGIN_CENTER humdum
#+END_CENTER
would be an export block for the center backend.
I agree. More on that below.
4.2 Blocks
──
Like [greater blocks], pattern for blocks is:
╭
│ #+BEGIN_NAME DATA
│ CONTENTS
│ #+END_NAME
╰
[…]
DATA can contain any character but a new line.
I'd keep with PARAMETERS here.
Ok. Just fix it.
If NAME is a string matching the name of any export back-end loaded,
the block will be an “export block”.
Conversely, blocks that are not having a recognizable name will simply
insert their content as if the block markers were not there, e.g. it
seems to treat these as parsed blocks.
You are talking about special blocks, right? They have a special
purpose. In latex back-end,
#+begin_special
...
#+end_special
becomes
\begin{special}
...
\end{special}
IOW this is an Org feature.
I don't think this should happen, instead Org should parse this as an
unknown export backend and drop the content with a warning, not unlike
a comment.
This would remove special blocks.
This will be a major sticking point with external parsers: they'd
otherwise need to know about the Org export backends to when to use the
content of the block and when not. A portable Org document should be
able to specify which export backends it expects to be available (and
maybe what standard backend it is derived from) to elicit the correct
behaviour.
I agree, as notified above. If we want to separate Org /format/ from
Emacs, we need to separate special blocks from export blocks. The former
cannot be the fallback type when the latter isn't recognized.
In that case, a different syntax for export blocks would be needed.
Maybe the colons you suggested above. I think that something more
visible would be better, though.
CONTENTS can contain any character, including new lines. Though it
will only contain Org objects if the block is a verse block.
Otherwise, contents will not be parsed.
Would it make sense to make a general distinction between parsed and
non-parsed blocks based on some configuration, even though this would
produce the same issue as with export backends?
This is inherent from the block type. This mustn't be configurable.
There is no point in parsing a src-block, for example. On the other
hand, if you don't parse (partially) contents of a verse-block, you get
an example-block, and one of them
Re: [O] [RFC] Org syntax (draft)
Nicolas Do you mind if I fix some obvious typos directly on Worg or do you'd rather want patches? Please go ahead. This is on Worg so anyone can improve it. Please consider adding the Org spec (and also the exporter reference) document to the Org manual. This will be a good excuse for exercising the TexInfo exporter and see where it leads. Committing to Org or Worg has same load cycle. I feel there is more value if it is right within the Org manual (i.e, part of Emacs). Only reason you may want to have it on Worg is possibly because it is likely to be read by wider audience. People seem to like browsers. (You can consider building a standalone PDF/HTML document out of .texi sources and have people read it) --
Re: [O] [RFC] Org syntax (draft)
Hello, Jambunathan K kjambunat...@gmail.com writes: Please consider adding the Org spec (and also the exporter reference) document to the Org manual. This will be a good excuse for exercising the TexInfo exporter and see where it leads. Committing to Org or Worg has same load cycle. I feel there is more value if it is right within the Org manual (i.e, part of Emacs). Only reason you may want to have it on Worg is possibly because it is likely to be read by wider audience. People seem to like browsers. It is not ready to go into the manual in its current state. As specified in its title, it's nothing more than a draft. Some parts have to be rewritten, some information is missing, my notes have to be removed, etc. Once it becomes clear enough, Bastien may consider adding it to the manual. The same holds for the exporter document. Regards, -- Nicolas Goaziou
Re: [O] [RFC] Org syntax (draft)
Nicolas Goaziou n.goaz...@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. Thanks Nicolas -- yep, that's really *great*! -- Bastien
Re: [O] [RFC] Org syntax (draft)
Nicolas Goaziou n.goaz...@gmail.com writes: As discussed a few days ago, here is a document describing the complete Org syntax as read by the parser. Fantastique! :-) I'm preciously saving this! François
Re: [O] [RFC] Org syntax (draft)
Nicolas Goaziou n.goaz...@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. 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: snip, useful example 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
Re: [O] [RFC] Org syntax (draft)
Hello, Nicolas Richard theonewiththeevill...@yahoo.fr writes: Nicolas Goaziou n.goaz...@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:
[O] [RFC] Org syntax (draft)
Hello, 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. ORG SYNTAX (DRAFT) Table of Contents ─ 1 Headlines and Sections 2 Affiliated Keywords 3 Greater Elements .. 3.1 Greater Blocks .. 3.2 Drawers and Property Drawers .. 3.3 Dynamic Blocks .. 3.4 Footnote Definitions .. 3.5 Inlinetasks .. 3.6 Plain Lists and Items .. 3.7 Tables 4 Elements .. 4.1 Babel Call .. 4.2 Blocks .. 4.3 Clock, Diary Sexp and Planning .. 4.4 Comments .. 4.5 Fixed Width Areas .. 4.6 Horizontal Rules .. 4.7 Keywords .. 4.8 LaTeX Environments .. 4.9 Node Properties .. 4.10 Paragraphs .. 4.11 Table Rows 5 Objects .. 5.1 Entities and LaTeX Fragments .. 5.2 Export Snippets .. 5.3 Footnote References .. 5.4 Inline Babel Calls and Source Blocks .. 5.5 Line Breaks .. 5.6 Links .. 5.7 Macros .. 5.8 Targets and Radio Targets .. 5.9 Statistics Cookies .. 5.10 Subscript and Superscript .. 5.11 Table Cells .. 5.12 Timestamps .. 5.13 Text Markup This document describes and comments Org syntax as it is currently read by its parser (Org Elements) and, therefore, by the export framework. It also includes a few comments on that syntax. A core concept in this syntax is that only headlines and sections are context-free[1][2]. Every other syntactical part only exists within specific environments. Three categories are used to classify these environments: “Greater elements”, “elements”, and “objects”, from the broadest scope to the narrowest. 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. 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. Unless specified otherwise, case is not significant. 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. KEYWORD is a TODO keyword, which have to belong to the list defined in `org-todo-keywords'. Case is significant. PRIORITY is a priority cookie, i.e. a single letter preceded by a hash sign # and enclosed within square brackets. Case is significant. TITLE can be made of any character but a new line. Though, it will match after every other part have been matched. TAGS is made of words containing any alpha-numeric character, underscore, at sign, hash sign or percent sign, and separated with colons. Examples of valid headlines include: ╭ │ * │ │ ** DONE │ │ *** Some e-mail │ │ TODO [#A] COMMENT Title :tag:a2%: ╰ If the first word appearing in the title is `org-comment-keyword', the headline will be considered as “commented”. If that first word is `org-quote-string', it will be considered as “quoted”. In both situations, case is significant. If its title is `org-footnote-section', it will be considered as a “footnote section”. Case is significant. If `org-archive-tag' is one of its tags, it will be considered as “archived”. Case is significant. A headline contains directly at most one section, followed by any number of headlines. Only a section can contain another section. 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”. As an example, consider the following document: ╭ │ An introduction. │ │ * A Headline │ │ Some text. │ │ ** Sub-Topic 1 │ │ ** Sub-Topic 2 │ │ *** Additional entry │ │ ** QUOTE Another Sub-Topic │ │Some other text. ╰ Its internal structure could be summarized as: ╭ │ (document │ (section) │ (headline │ (section) │ (headline) │ (headline │(headline)) │ (headline │(quote-section ╰ 2 Affiliated Keywords ═ With the exception of [inlinetasks], [items], [planning], [clocks], [node properties] and [table rows], every other element type can be assigned attributes. This is done by adding specific keywords, named
Re: [O] [RFC] Org syntax (draft)
woow, this is awesome Nicolas, thank you! - Carsten On 7.3.2013, at 21:37, Nicolas Goaziou n.goaz...@gmail.com wrote: Hello, 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. ORG SYNTAX (DRAFT) Table of Contents ─ 1 Headlines and Sections 2 Affiliated Keywords 3 Greater Elements .. 3.1 Greater Blocks .. 3.2 Drawers and Property Drawers .. 3.3 Dynamic Blocks .. 3.4 Footnote Definitions .. 3.5 Inlinetasks .. 3.6 Plain Lists and Items .. 3.7 Tables 4 Elements .. 4.1 Babel Call .. 4.2 Blocks .. 4.3 Clock, Diary Sexp and Planning .. 4.4 Comments .. 4.5 Fixed Width Areas .. 4.6 Horizontal Rules .. 4.7 Keywords .. 4.8 LaTeX Environments .. 4.9 Node Properties .. 4.10 Paragraphs .. 4.11 Table Rows 5 Objects .. 5.1 Entities and LaTeX Fragments .. 5.2 Export Snippets .. 5.3 Footnote References .. 5.4 Inline Babel Calls and Source Blocks .. 5.5 Line Breaks .. 5.6 Links .. 5.7 Macros .. 5.8 Targets and Radio Targets .. 5.9 Statistics Cookies .. 5.10 Subscript and Superscript .. 5.11 Table Cells .. 5.12 Timestamps .. 5.13 Text Markup This document describes and comments Org syntax as it is currently read by its parser (Org Elements) and, therefore, by the export framework. It also includes a few comments on that syntax. A core concept in this syntax is that only headlines and sections are context-free[1][2]. Every other syntactical part only exists within specific environments. Three categories are used to classify these environments: “Greater elements”, “elements”, and “objects”, from the broadest scope to the narrowest. 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. 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. Unless specified otherwise, case is not significant. 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. KEYWORD is a TODO keyword, which have to belong to the list defined in `org-todo-keywords'. Case is significant. PRIORITY is a priority cookie, i.e. a single letter preceded by a hash sign # and enclosed within square brackets. Case is significant. TITLE can be made of any character but a new line. Though, it will match after every other part have been matched. TAGS is made of words containing any alpha-numeric character, underscore, at sign, hash sign or percent sign, and separated with colons. Examples of valid headlines include: ╭ │ * │ │ ** DONE │ │ *** Some e-mail │ │ TODO [#A] COMMENT Title :tag:a2%: ╰ If the first word appearing in the title is `org-comment-keyword', the headline will be considered as “commented”. If that first word is `org-quote-string', it will be considered as “quoted”. In both situations, case is significant. If its title is `org-footnote-section', it will be considered as a “footnote section”. Case is significant. If `org-archive-tag' is one of its tags, it will be considered as “archived”. Case is significant. A headline contains directly at most one section, followed by any number of headlines. Only a section can contain another section. 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”. As an example, consider the following document: ╭ │ An introduction. │ │ * A Headline │ │ Some text. │ │ ** Sub-Topic 1 │ │ ** Sub-Topic 2 │ │ *** Additional entry │ │ ** QUOTE Another Sub-Topic │ │Some other text. ╰ Its internal structure could be summarized as: ╭ │ (document │ (section) │ (headline │ (section) │ (headline) │ (headline │(headline)) │ (headline │(quote-section ╰ 2 Affiliated Keywords
Re: [O] [RFC] Org syntax (draft)
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. Wonderful. This will be really useful! Regards, Achim. -- +[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]+ Waldorf MIDI Implementation additional documentation: http://Synth.Stromeko.net/Downloads.html#WaldorfDocs
