Classification of Org mode elements

Classification of Org mode elements

[Thomas S. Dye]

[-- Attachment #1: Type: text/plain, Size: 549 bytes --]

Aloha all,

The attached Org mode document contains some notes on the classification
of Org mode elements that might be a useful addition to Nicolas
Goaziou's draft Org syntax document
(http://orgmode.org/worg/dev/org-syntax.org).

It distinguishes nine classes of element and proposes names for them.  

I'm hoping for some comments.  The classification stuff makes sense to
me, given my anthropology and archaeology background, but I'm not
certain if it will be sensible to the Org mode community, which is
mostly programmers.

All the best,
Tom


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Notes on the classification of Org mode elements --]
[-- Type: text/x-org, Size: 7195 bytes --]

#+TITLE: org-syntax-element-table
#+DATE: <2013-06-16 Sun>
#+AUTHOR: Thomas Dye
#+EMAIL: tsd@tsdye.com
#+OPTIONS: ':nil *:t -:t ::t <:t H:3 \n:nil ^:t arch:headline
#+OPTIONS: author:t c:nil creator:comment d:(not LOGBOOK) date:t e:t
#+OPTIONS: email:nil f:t inline:t num:t p:nil pri:nil stat:t tags:t
#+OPTIONS: tasks:t tex:t timestamp:t toc:t todo:t |:t
#+CREATOR: Emacs 24.3.1 (Org mode 8.0.2)
#+DESCRIPTION:
#+EXCLUDE_TAGS: noexport
#+KEYWORDS:
#+LANGUAGE: en
#+SELECT_TAGS: export

* Org mode document

An Org mode document contains headlines and sections.  A section
contains one or more elements, which are either paragraphs or are
recognized by the parser as one of 28 Org mode constructs.  Org mode
does not distinguish different classes of headline.

* Element table

There are 26 different elements that can be classified according to
four boolean properties:
  - greater :: an element that can contain another element
  - restricted :: an element that must be contained by another element
  - attributable :: an element that can have an affiliated keyword
  - direct object :: an element that can directly contain an object

The four boolean properties describe a paradigmatic classification
with 16 (2^4) classes, only nine of which are realized (table
[[element-table]]). Five of the nine classes---2, 3, 4, 8, and 9---each
comprise a single instance. These are referred to as "singleton
classes." Two classes---6 and 7---comprise two instances. Class 1
comprises six instances and Class 5 comprises eleven instances.

Nicolas Goaziou's draft [[http://orgmode.org/worg/dev/org-syntax.org][Org Syntax description]] classified the elements
on the greater property, distinguishing Greater elements from
Elements.  The proposed class names in table [[element-table]] build on
this distinction, keeping the name Greater element and substituting
Lesser element for Element.  Singleton classes are named after the
element they comprise.  Lesser elements that don't take an affiliated
keyword are called Unattributable lesser elements, and lesser
elements that can directly contain an object are called Direct object
lesser elements.

#+name: element-table
| Element             | Greater | Restricted | Attributable | Direct object | Class | NGZ             | Proposed class names          |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Drawer              | true    | false      | true         | false         |     1 | Greater element | Greater element               |
| Dynamic block       | true    | false      | true         | false         |     1 | Greater element | Greater element               |
| Footnote definition | true    | false      | true         | false         |     1 | Greater element | Greater element               |
| Greater block       | true    | false      | true         | false         |     1 | Greater element | Greater element               |
| Plain list          | true    | false      | true         | false         |     1 | Greater element | Greater element               |
| Table               | true    | false      | true         | false         |     1 | Greater element | Greater element               |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Inline task         | true    | false      | false        | false         |     2 | Greater element | Inline task                   |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Property drawer     | true    | true       | true         | false         |     3 | Greater element | Property drawer               |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Item                | true    | true       | false        | false         |     4 | Greater element | List item                     |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Babel call          | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Comment             | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Comment block       | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Diary               | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Example block       | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Fixed width area    | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Horizontal rule     | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Keyword             | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| LaTeX environment   | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Sexp                | false   | false      | true         | false         |     5 | Element         | Lesser element                |
| Source block        | false   | false      | true         | false         |     5 | Element         | Lesser element                |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Paragraph           | false   | false      | true         | true          |     6 | Element         | Direct object lesser element  |
| Verse block         | false   | false      | true         | true          |     6 | Element         | Direct object lesser element  |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Clock               | false   | false      | false        | false         |     7 | Element         | Unattributable lesser element |
| Planning (Plan?)    | false   | false      | false        | false         |     7 | Element         | Unattributable lesser element |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Node property       | false   | true       | false        | false         |     8 | Element         | Node property                 |
|---------------------+---------+------------+--------------+---------------+-------+-----------------+-------------------------------|
| Table row           | false   | true       | false        | true          |     9 | Element         | Table row                     |

[-- Attachment #3: Type: text/plain, Size: 40 bytes --]


-- 
Thomas S. Dye
http://www.tsdye.com

Re: Classification of Org mode elements

[Thorsten Jolitz]

[-- Attachment #1: Type: text/plain, Size: 1063 bytes --]

tsd@tsdye.com (Thomas S. Dye) writes:

Hi Thomas,

> The attached Org mode document contains some notes on the classification
> of Org mode elements that might be a useful addition to Nicolas
> Goaziou's draft Org syntax document
> (http://orgmode.org/worg/dev/org-syntax.org).
>
> It distinguishes nine classes of element and proposes names for them.  

I really like the idea to make Nicolas decisions when modelling Org
syntax more explicit and write them down as a quick reference overview.

I compressed your table a bit to make it fit on a screen/page, and added
a subtree for each element to the file that could contain a short
(man-page like) descripton of syntax and semantics of that element (see
my attempts for 'Property drawer' as an example). This should not
compete with the manual or the cheat sheet, but rather serve as a
minimal overview of the Org 8+ syntax elements.

Right now I don't have the time to fill the other subtrees, but I might
add to this the next days, maybe others can add to it too and then this
file can be uploaded to Worg?


[-- Attachment #2: org-mode-synatx-table.org --]
[-- Type: application/vnd.lotus-organizer, Size: 4281 bytes --]

[-- Attachment #3: Type: text/plain, Size: 22 bytes --]


-- 
cheers,
Thorsten

Re: Classification of Org mode elements

[Thorsten Jolitz]

Thorsten Jolitz <tjolitz@gmail.com> writes:

[here is the attachment from my last post inline]

* Element Table

#+name: element-table
| Element             | g? | r? | a? | do? | C | N  | pN   |
|---------------------+----+----+----+-----+---+----+------|
| Drawer              | X  |    | X  |     | 1 | GE | GE   |
| Dynamic block       | X  |    | X  |     | 1 | GE | GE   |
| Footnote definition | X  |    | X  |     | 1 | GE | GE   |
| Greater block       | X  |    | X  |     | 1 | GE | GE   |
| Plain list          | X  |    | X  |     | 1 | GE | GE   |
| Table               | X  |    | X  |     | 1 | GE | GE   |
|---------------------+----+----+----+-----+---+----+------|
| Inline task         | X  |    |    |     | 2 | GE | IT   |
|---------------------+----+----+----+-----+---+----+------|
| Property drawer     | X  | X  | X  |     | 3 | GE | PD   |
|---------------------+----+----+----+-----+---+----+------|
| Item                | X  | X  |    |     | 4 | GE | LI   |
|---------------------+----+----+----+-----+---+----+------|
| Babel call          |    |    | X  |     | 5 | E  | LE   |
| Comment             |    |    | X  |     | 5 | E  | LE   |
| Comment block       |    |    | X  |     | 5 | E  | LE   |
| Diary               |    |    | X  |     | 5 | E  | LE   |
| Example block       |    |    | X  |     | 5 | E  | LE   |
| Fixed width area    |    |    | X  |     | 5 | E  | LE   |
| Horizontal rule     |    |    | X  |     | 5 | E  | LE   |
| Keyword             |    |    | X  |     | 5 | E  | LE   |
| LaTeX environment   |    |    | X  |     | 5 | E  | LE   |
| Sexp                |    |    | X  |     | 5 | E  | LE   |
| Source block        |    |    | X  |     | 5 | E  | LE   |
|---------------------+----+----+----+-----+---+----+------|
| Paragraph           |    |    | X  | X   | 6 | E  | doLE |
| Verse block         |    |    | X  | X   | 6 | E  | doLE |
|---------------------+----+----+----+-----+---+----+------|
| Clock               |    |    |    |     | 7 | E  | uLE  |
| Planning (Plan?)    |    |    |    |     | 7 | E  | uLE  |
|---------------------+----+----+----+-----+---+----+------|
| Node property       |    | X  |    |     | 8 | E  | NP   |
|---------------------+----+----+----+-----+---+----+------|
| Table row           |    | X  |    | X   | 9 | E  | TR   |


#+name: element-table-abbrevs
| abbrev | meaning                       |
|--------+-------------------------------|
| g?     | Greater                       |
| r?     | Restricted                    |
| a?     | Attributable                  |
| do?    | Direct Object                 |
| C      | Class                         |
| N      | (original) Name               |
| pN     | (proposed) Name               |
| GE     | Greater element               |
| E      | Element                       |
| LE     | Lesser element                |
| uLE    | Unattributable lesser element |
| doLE   | Direct object lesser element  |
| IT     | Inline task                   |
| PD     | Property drawer               |
| LI     | List item                     |
| NP     | Node property                 |

* Elements
** Drawer
** Dynamic block
** Footnote definition
** Greater block
** Plain list
** Table
** Inline task
** Property drawer
*** Syntax

#+name:property-drawer-example
#+begin_src org
    :PROPERTIES:
    :CATEGORY: office
    :END:
#+end_src

#+name:property-drawer-regexp
#+begin_src emacs-lisp
"^[ \t]*:PROPERTIES:[ \t]*$"
#+end_src

*** Semantics

Store meta-data and implement simple databases

*** Insertion

M-x org-insert-property-drawer

#+name: property-drawers-insertion-keys
| keys      | action                                                |
|-----------+-------------------------------------------------------|
| M-TAB     | After initial colon in a line, comlete property keys  |
| C-c C-x p | Set a property (if necessary, create property drawer) |

*** Export
#+name: property-drawers-export-backends
| backend | exports to |
|---------+------------|
| ascii   | ---        |
| latex   |            |
| html    |            |
|         |            |

** Item
** Babel call
** Comment
** Comment block
** Diary
** Example block
** Fixed width area
** Horizontal rule
** Keyword
** LaTeX environment
** Sexp
** Source block
** Paragraph
** Verse block
** Clock
** Planning (Plan?)
** Node property
** Table row


-- 
cheers,
Thorsten

Re: Classification of Org mode elements

[Thomas S. Dye]

Aloha Thorsten,

Thorsten Jolitz <tjolitz@gmail.com> writes:

> tsd@tsdye.com (Thomas S. Dye) writes:
>
> Hi Thomas,
>
>> The attached Org mode document contains some notes on the classification
>> of Org mode elements that might be a useful addition to Nicolas
>> Goaziou's draft Org syntax document
>> (http://orgmode.org/worg/dev/org-syntax.org).
>>
>> It distinguishes nine classes of element and proposes names for them.  
>
> I really like the idea to make Nicolas decisions when modelling Org
> syntax more explicit and write them down as a quick reference overview.

Well, I'm just summarizing Nicolas' draft Org Syntax document.  I don't
think I've made anything more explicit than he does in that fine
document.  I'm glad you like the table. 
>
> I compressed your table a bit to make it fit on a screen/page

Much better, a real improvement.  Thanks!

> , and added
> a subtree for each element to the file that could contain a short
> (man-page like) descripton of syntax and semantics of that element (see
> my attempts for 'Property drawer' as an example). This should not
> compete with the manual or the cheat sheet, but rather serve as a
> minimal overview of the Org 8+ syntax elements.

My idea is to add the table to Nicolas' draft Org Syntax document, and
use the classes as the basis for editing and restructuring the document
a bit. Perhaps your subtrees would fit in, too?

>
> Right now I don't have the time to fill the other subtrees, but I might
> add to this the next days, maybe others can add to it too and then this
> file can be uploaded to Worg?

Yes, perhaps we could do that if Nicolas doesn't like the changes I have
in mind for the draft Org Syntax document.

Also, I'd like to see the Org Syntax document become an appendix to the
manual. I know some think that it is too developer-ish to be a part of
the manual, but it has helped me see Org Mode documents more clearly and
I think it might benefit others, as well.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Classification of Org mode elements

[Suvayu Ali]

On Mon, Jun 17, 2013 at 09:08:38PM -1000, Thomas S. Dye wrote:
> 
> Also, I'd like to see the Org Syntax document become an appendix to the
> manual. I know some think that it is too developer-ish to be a part of
> the manual, but it has helped me see Org Mode documents more clearly and
> I think it might benefit others, as well.

Not to mention having access to it as an info page!  At the moment I
have an info version exported with the texinfo exporter (I think
Jambunathan posted this sometime back); I installed it manually.

-- 
Suvayu

Open source is the future. It sets us free.

Re: Classification of Org mode elements

[Nicolas Goaziou]

Hello,

tsd@tsdye.com (Thomas S. Dye) writes:

> My idea is to add the table to Nicolas' draft Org Syntax document, and
> use the classes as the basis for editing and restructuring the document
> a bit.

Please go ahead, as long as the document stays faithful to the
implementation.


[...]

> Also, I'd like to see the Org Syntax document become an appendix to the
> manual. I know some think that it is too developer-ish to be a part of
> the manual, but it has helped me see Org Mode documents more clearly and
> I think it might benefit others, as well.

I also think that, once it is finalized (i.e. readable), it deserves to
be added to appendix.

Though, some parts of Org do not rely on org-element and may slightly
differ in their interpretation of the Org syntax.


Regards,

-- 
Nicolas Goaziou

Re: Classification of Org mode elements

[Thomas S. Dye]

Aloha Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Hello,
>
> tsd@tsdye.com (Thomas S. Dye) writes:
>
>> My idea is to add the table to Nicolas' draft Org Syntax document, and
>> use the classes as the basis for editing and restructuring the document
>> a bit.
>
> Please go ahead, as long as the document stays faithful to the
> implementation.

Yes, this is the editor's challenge.  The author need's to keep a sharp
eye, too.

>
>
> [...]
>
>> Also, I'd like to see the Org Syntax document become an appendix to the
>> manual. I know some think that it is too developer-ish to be a part of
>> the manual, but it has helped me see Org Mode documents more clearly and
>> I think it might benefit others, as well.
>
> I also think that, once it is finalized (i.e. readable), it deserves to
> be added to appendix.

Great.  Unless others object let's set this as a goal.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com