* Classification of Org mode elements
@ 2013-06-16 22:50 Thomas S. Dye
2013-06-17 6:34 ` Thorsten Jolitz
0 siblings, 1 reply; 7+ messages in thread
From: Thomas S. Dye @ 2013-06-16 22:50 UTC (permalink / raw)
To: Org-mode
[-- 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Classification of Org mode elements
2013-06-16 22:50 Classification of Org mode elements Thomas S. Dye
@ 2013-06-17 6:34 ` Thorsten Jolitz
2013-06-17 6:50 ` Thorsten Jolitz
2013-06-18 7:08 ` Thomas S. Dye
0 siblings, 2 replies; 7+ messages in thread
From: Thorsten Jolitz @ 2013-06-17 6:34 UTC (permalink / raw)
To: emacs-orgmode
[-- 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Classification of Org mode elements
2013-06-17 6:34 ` Thorsten Jolitz
@ 2013-06-17 6:50 ` Thorsten Jolitz
2013-06-18 7:08 ` Thomas S. Dye
1 sibling, 0 replies; 7+ messages in thread
From: Thorsten Jolitz @ 2013-06-17 6:50 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: Classification of Org mode elements
2013-06-17 6:34 ` Thorsten Jolitz
2013-06-17 6:50 ` Thorsten Jolitz
@ 2013-06-18 7:08 ` Thomas S. Dye
2013-06-18 8:26 ` Suvayu Ali
2013-06-18 18:06 ` Nicolas Goaziou
1 sibling, 2 replies; 7+ messages in thread
From: Thomas S. Dye @ 2013-06-18 7:08 UTC (permalink / raw)
To: Thorsten Jolitz; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Classification of Org mode elements
2013-06-18 7:08 ` Thomas S. Dye
@ 2013-06-18 8:26 ` Suvayu Ali
2013-06-18 18:06 ` Nicolas Goaziou
1 sibling, 0 replies; 7+ messages in thread
From: Suvayu Ali @ 2013-06-18 8:26 UTC (permalink / raw)
To: emacs-orgmode
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Classification of Org mode elements
2013-06-18 7:08 ` Thomas S. Dye
2013-06-18 8:26 ` Suvayu Ali
@ 2013-06-18 18:06 ` Nicolas Goaziou
2013-06-18 18:24 ` Thomas S. Dye
1 sibling, 1 reply; 7+ messages in thread
From: Nicolas Goaziou @ 2013-06-18 18:06 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: emacs-orgmode, Thorsten Jolitz
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Classification of Org mode elements
2013-06-18 18:06 ` Nicolas Goaziou
@ 2013-06-18 18:24 ` Thomas S. Dye
0 siblings, 0 replies; 7+ messages in thread
From: Thomas S. Dye @ 2013-06-18 18:24 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Thorsten Jolitz, emacs-orgmode
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
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2013-06-18 18:25 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-06-16 22:50 Classification of Org mode elements Thomas S. Dye
2013-06-17 6:34 ` Thorsten Jolitz
2013-06-17 6:50 ` Thorsten Jolitz
2013-06-18 7:08 ` Thomas S. Dye
2013-06-18 8:26 ` Suvayu Ali
2013-06-18 18:06 ` Nicolas Goaziou
2013-06-18 18:24 ` Thomas S. Dye
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).