From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Nicolas Richard" Subject: Re: [RFC] Org syntax (draft) Date: Wed, 13 Mar 2013 15:07:54 +0100 Message-ID: <877glb2y11.fsf@yahoo.fr> References: <8738w7c5fh.fsf@gmail.com> <87vc913oh5.fsf@yahoo.fr> <87y5dxzgvo.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([208.118.235.92]:40296) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UFmLa-00087e-Ru for emacs-orgmode@gnu.org; Wed, 13 Mar 2013 10:08:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UFmLQ-0006US-RJ for emacs-orgmode@gnu.org; Wed, 13 Mar 2013 10:08:02 -0400 Received: from plane.gmane.org ([80.91.229.3]:42217) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UFmLQ-0006UD-HB for emacs-orgmode@gnu.org; Wed, 13 Mar 2013 10:07:52 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1UFmLl-0000h3-AZ for emacs-orgmode@gnu.org; Wed, 13 Mar 2013 15:08:13 +0100 Received: from geodiff-mac3.ulb.ac.be ([164.15.131.113]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 13 Mar 2013 15:08:13 +0100 Received: from theonewiththeevillook by geodiff-mac3.ulb.ac.be with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 13 Mar 2013 15:08:13 +0100 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: emacs-orgmode@gnu.org 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 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". As an example, consider the following document: @@ -136,7 +138,8 @@ Unless specified otherwise, case is not significant. attributes. This is done by adding specific keywords, named "affiliated - keywords", just above the element considered, no blank line allowed. + keywords", just above the element considered, no blank line + allowed. Affiliated keywords are built upon one of the following patterns: "#+KEY: VALUE", "#+KEY[OPTIONAL]: VALUE" or "#+ATTR_BACKEND: VALUE". @@ -150,7 +153,7 @@ Unless specified otherwise, case is not significant. OPTIONAL and VALUE can contain any character but a new line. Only "CAPTION" and "RESULTS" keywords can have an optional value. - An affiliated keyword can appear on multiple lines if KEY is either + An affiliated keyword can appear more than once if KEY is either "CAPTION" or "HEADER" or if its pattern is "#+ATTR_BACKEND: VALUE". "CAPTION", "AUTHOR", "DATE" and "TITLE" keywords can contain objects @@ -183,7 +186,8 @@ Unless specified otherwise, case is not significant. NAME can contain any non-whitespace character. - PARAMETERS can contain any character, and can be omitted. + PARAMETERS can contain any character other than new line, and can + be omitted. If NAME is "CENTER", it will be a "center block". If it is "QUOTE", it will be a "quote block". @@ -191,8 +195,8 @@ Unless specified otherwise, case is not significant. If the block is neither a center block, a quote block or a [[#Blocks][block element]], it will be a "special block". - CONTENTS can contain any element, but another greater block of the - same type. + CONTENTS can contain any element, except : a line =#+END_NAME= on + its own and lines beginning with STARS must be quoted by a comma. ** Drawers and Property Drawers :PROPERTIES: -- 1.8.1.4