[O] Tabular overview of org-element.el
Hi Nicolas, Hi List, I prepared a tabular overview of org-element.el to get a better understanding of how Nicolas modeled and Org file, and I thought it might be useful for others so I share it here. I did not know where to put 'plain-link', but maybe I simply overlooked it in one place. ___ ORG ELEMENTS - A TABULAR OVERVIEW Thorsten Jolitz ___ 2013-04-20 Sa Table of Contents _ 1 org-element: Elements, Objects and Successors .. 1.1 Elements . 1.1.1 Abbreviations . 1.1.2 Element List .. 1.2 Objects . 1.2.1 Object List . 1.2.2 Object Variables .. 1.3 Successors . 1.3.1 Abbreviations . 1.3.2 Sets of Successors . 1.3.3 Objects restrictions 2 org-element: Keywords and Properties .. 2.1 Affiliated Keywords .. 2.2 Document Properties 3 Left-over 1 org-element: Elements, Objects and Successors === 1.1 Elements 1.1.1 Abbreviations --- Abbrev Meaning --- GE? Greater Element? SecVal-Location Secondary Value Location Recur? Recursive? 1.1.2 Element List -- Complete list of element types. List of recursive element types aka Greater Elements. Alist between element types and location of secondary value. Element GE? SecVal-Location --- babel-call center-block X clock comment comment-block diary-sexp drawer X dynamic-blockX example-block export-block fixed-width footnote-definition X headline X:title horizontal-rule inlinetask X:title item X:tag keyword latex-environment node-property paragraph plain-list X planning property-drawer X quote-block X quote-section section X special-blockX src-block tableX table-row verse-block 1.2 Objects ~~~ 1.2.1 Object List - Complete list of object types. List of recursive object types. Alist of translations between object type and successor name. Sharing the same successor comes handy when, for example, the regexp matching one object can also match the other object. Alist between element types and location of secondary value. Object Recur? Successor(type) SecVal-Location - boldX text-markup codetext-markup entity latex-or-entity export-snippet X footnote-reference X:inline-definition inline-babel-call X inline-src-blockX italic X text-markup line-break X latex-fragment latex-or-entity linkX X macro X radio-targetX X statistics-cookie X strike-through X text-markup subscript X sub/superscript superscript X sub/superscript table-cell X X target X timestamp X underline X text-markup verbatimtext-markup 1.2.2 Object Variables -- List of buffer-local variables used when parsing objects. These variables are copied to the temporary buffer created by `org-export-secondary-string'. object-variables '(org-link-abbrev-alist-local) Example for `org-link-abbrev-alist-local' , | ((bib . ~/bibtex/literatur.bib::%s) | (notes . ~/git/org/notes.org::#%s) | (papers . ~/doc/papers/%s.pdf)) ` 1.3 Successors ~~ 1.3.1 Abbreviations --- abbrev meaning - all all successors std-set standard-set std-set-nlb standard-set-no-line-break l-setlink-set tc-set table-cell-set tr-set table-row-set rt-set radio-target-set 1.3.2 Sets of Successors Complete list of successors. members\set all std-set std-set-nlb l-set tc-set tr-set rt-set -- export-snippet XXXX X footnote-reference XXX X inline-babel-call XXXX inline-src-blockX
Re: [O] Tabular overview of org-element.el
Hello, Thorsten Jolitz tjol...@gmail.com writes: I prepared a tabular overview of org-element.el to get a better understanding of how Nicolas modeled and Org file, and I thought it might be useful for others so I share it here. I did not know where to put 'plain-link', but maybe I simply overlooked it in one place. It belongs to `org-element-all-successors', which means it is a successor. Actually, it is a dumbed down successor for links, as it only finds plain links, i.e. links with no markup at all. E.g., http://orgmode.org This is necessary as some contexts (i.e. link descriptions) can only contain such links. HTH, -- Nicolas Goaziou
Re: [O] Tabular overview of org-element.el
Nicolas Goaziou n.goaz...@gmail.com writes: Hello, Thorsten Jolitz tjol...@gmail.com writes: I prepared a tabular overview of org-element.el to get a better understanding of how Nicolas modeled and Org file, and I thought it might be useful for others so I share it here. I did not know where to put 'plain-link', but maybe I simply overlooked it in one place. It belongs to `org-element-all-successors', which means it is a successor. Actually, it is a dumbed down successor for links, as it only finds plain links, i.e. links with no markup at all. E.g., http://orgmode.org This is necessary as some contexts (i.e. link descriptions) can only contain such links. Whats kind of confusing for me is that all other successors are either 'atomic' objects or 'object-categories' containing 'atomic' objects: , | Object Recur? Successor(type) SecVal-Location | - |boldX text-markup |codetext-markup |entity latex-or-entity |export-snippet X |footnote-reference X:inline-definition |inline-babel-call X |inline-src-blockX |italic X text-markup |line-break X |latex-fragment latex-or-entity |linkX X |macro X |radio-targetX X |statistics-cookie X |strike-through X text-markup |subscript X sub/superscript |superscript X sub/superscript |table-cell X X |target X |timestamp X |underline X text-markup |verbatimtext-markup ` Only plain-link is an 'outlier' in this systematic. What is a link like ,--- | http://orgmode.org `--- then, when encountered in an Org document? If its not an object nor an element, then it is (anonymous) part of the String that forms a paragraph? Its easy to understand that some objects can be successors of other objects/elements, others not, and that its sometimes convenient to organize similar successor objects into successor-categories. Its not so easy to understand how something can be a successor but not an object. -- cheers, Thorsten
Re: [O] Tabular overview of org-element.el
Thorsten Jolitz tjol...@gmail.com writes: Nicolas Goaziou n.goaz...@gmail.com writes: Hello, Thorsten Jolitz tjol...@gmail.com writes: I prepared a tabular overview of org-element.el to get a better understanding of how Nicolas modeled and Org file, and I thought it might be useful for others so I share it here. I did not know where to put 'plain-link', but maybe I simply overlooked it in one place. It belongs to `org-element-all-successors', which means it is a successor. Actually, it is a dumbed down successor for links, as it only finds plain links, i.e. links with no markup at all. E.g., http://orgmode.org This is necessary as some contexts (i.e. link descriptions) can only contain such links. Whats kind of confusing for me is that all other successors are either 'atomic' objects or 'object-categories' containing 'atomic' objects: , | Object Recur? Successor(type) SecVal-Location | - |boldX text-markup |codetext-markup |entity latex-or-entity |export-snippet X |footnote-reference X:inline-definition |inline-babel-call X |inline-src-blockX |italic X text-markup |line-break X |latex-fragment latex-or-entity |linkX X |macro X |radio-targetX X |statistics-cookie X |strike-through X text-markup |subscript X sub/superscript |superscript X sub/superscript |table-cell X X |target X |timestamp X |underline X text-markup |verbatimtext-markup ` Only plain-link is an 'outlier' in this systematic. What is a link like ,--- | http://orgmode.org `--- then, when encountered in an Org document? If its not an object nor an element, then it is (anonymous) part of the String that forms a paragraph? Its easy to understand that some objects can be successors of other objects/elements, others not, and that its sometimes convenient to organize similar successor objects into successor-categories. Its not so easy to understand how something can be a successor but not an object. http://orgmode.org; _is_ a link object, like [[http://orgmode.org]]. There are two successors for the same object type, one being more selective than the other. This special successor was introduced (lately) because there was no image syntax in Org. So we needed to recognize: [[http://orgmode.org][./unicorn.jpg]] as an image pointing to an URL. In fact, we could separate `plain-link' objects from `link' objects, but the benefit is not obvious, so `plain-link' is just considered as a sub-type of `link'. Regards, -- Nicolas Goaziou
Re: [O] Tabular overview of org-element.el
Nicolas Goaziou n.goaz...@gmail.com writes:
Thorsten Jolitz tjol...@gmail.com writes:
Nicolas Goaziou n.goaz...@gmail.com writes:
Hello,
Thorsten Jolitz tjol...@gmail.com writes:
I prepared a tabular overview of org-element.el to get a better
understanding of how Nicolas modeled and Org file, and I thought it
might be useful for others so I share it here.
I did not know where to put 'plain-link', but maybe I simply overlooked
it in one place.
It belongs to `org-element-all-successors', which means it is
a successor. Actually, it is a dumbed down successor for links, as it
only finds plain links, i.e. links with no markup at all. E.g.,
http://orgmode.org
This is necessary as some contexts (i.e. link descriptions) can only
contain such links.
Whats kind of confusing for me is that all other successors are either
'atomic' objects or 'object-categories' containing 'atomic' objects:
,
| Object Recur? Successor(type) SecVal-Location
| -
|boldX text-markup
|codetext-markup
|entity latex-or-entity
|export-snippet X
|footnote-reference X:inline-definition
|inline-babel-call X
|inline-src-blockX
|italic X text-markup
|line-break X
|latex-fragment latex-or-entity
|linkX X
|macro X
|radio-targetX X
|statistics-cookie X
|strike-through X text-markup
|subscript X sub/superscript
|superscript X sub/superscript
|table-cell X X
|target X
|timestamp X
|underline X text-markup
|verbatimtext-markup
`
Only plain-link is an 'outlier' in this systematic. What is a link like
,---
| http://orgmode.org
`---
then, when encountered in an Org document? If its not an object nor an
element, then it is (anonymous) part of the String that forms a paragraph?
Its easy to understand that some objects can be successors of other
objects/elements, others not, and that its sometimes convenient to
organize similar successor objects into successor-categories.
Its not so easy to understand how something can be a successor but not
an object.
http://orgmode.org; _is_ a link object, like [[http://orgmode.org]].
There are two successors for the same object type, one being more
selective than the other.
This special successor was introduced (lately) because there was no
image syntax in Org. So we needed to recognize:
[[http://orgmode.org][./unicorn.jpg]]
as an image pointing to an URL. In fact, we could separate `plain-link'
objects from `link' objects, but the benefit is not obvious, so
`plain-link' is just considered as a sub-type of `link'.
So in fact there are link objects that might belong to 'decorated-link'
or 'plain-link', but this has not been made explicit because there is
only one special case where its not sufficient to simply use super-type
'link'.
Maybe its worth to notice that wrt 'plain-link' there are some hidden
implicit things going on in the background. First of all, there are no
other subtypes of object-types - object 'link' would be the only
object-type with two subtypes ('plain-link' and 'decorated-link' or
whatever). And the object 'link' is used as successor but does not fit
all situations where a link can be used.
I know this might be of no practical relevance at the moment, and might
seem like a case of excessive pea-counting, but now that Org-mode has
such a wonderful parsing and exporting framework, there might well be a
trend towards more formalization in the future - and this will cause
hiccups for anyone who tries such formalization.
To keep the system consistent, there should be two types of link objects
('plain-link' and 'decorated-link') that are both successors too, and
maybe additionally a successor category 'link' that can be applied when
distinction between the two link object-types does not matter.
--
cheers,
Thorsten
Re: [O] Tabular overview of org-element.el
Thorsten Jolitz tjol...@gmail.com writes:
So in fact there are link objects that might belong to 'decorated-link'
or 'plain-link', but this has not been made explicit because there is
only one special case where its not sufficient to simply use super-type
'link'.
That and the fact that it was introduced very recently.
Maybe its worth to notice that wrt 'plain-link' there are some hidden
implicit things going on in the background. First of all, there are no
other subtypes of object-types - object 'link' would be the only
object-type with two subtypes ('plain-link' and 'decorated-link' or
whatever). And the object 'link' is used as successor but does not fit
all situations where a link can be used.
Actually there is also `radio-link' sub-type. But it doesn't need its
own successor function so far.
I know this might be of no practical relevance at the moment, and might
seem like a case of excessive pea-counting, but now that Org-mode has
such a wonderful parsing and exporting framework, there might well be a
trend towards more formalization in the future - and this will cause
hiccups for anyone who tries such formalization.
To be honest, I hope that Org will grow a proper syntax for images
instead (i.e. without overloading link syntax). Many (most?) text markup
languages have one (e.g. Markdown). If it does, the `plain-link'
successor becomes useless and the case is closed.
To keep the system consistent, there should be two types of link objects
('plain-link' and 'decorated-link') that are both successors too, and
maybe additionally a successor category 'link' that can be applied when
distinction between the two link object-types does not matter.
That's what I talked about indeed, but besides consistency, there's not
much benefit to do that. I'd rather have images as full-fledged objects,
something like:
[img:]
which could possibly be extended with properties for export:
[img: :prop1 val1 :prop2 val2]
Regards,
--
Nicolas Goaziou
Re: [O] Tabular overview of org-element.el
Nicolas Goaziou n.goaz...@gmail.com writes:
To keep the system consistent, there should be two types of link objects
('plain-link' and 'decorated-link') that are both successors too, and
maybe additionally a successor category 'link' that can be applied when
distinction between the two link object-types does not matter.
That's what I talked about indeed, but besides consistency, there's not
much benefit to do that. I'd rather have images as full-fledged objects,
something like:
[img:]
which could possibly be extended with properties for export:
[img: :prop1 val1 :prop2 val2]
That sounds like a very good idea to me, from the point of view of a
user, and from the point of view of somebody who tries to understand the
system you used for modeling Org files. And consistency can turn out
very beneficial in the long run, even if the benefits are not so obvious
at the moment.
--
cheers,
Thorsten
