* Tabular overview of org-element.el
@ 2013-04-20 15:18 Thorsten Jolitz
2013-04-20 16:34 ` Nicolas Goaziou
0 siblings, 1 reply; 7+ messages in thread
From: Thorsten Jolitz @ 2013-04-20 15:18 UTC (permalink / raw)
To: emacs-orgmode
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-block X
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-block X
src-block
table X
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
-----------------------------------------------------------------
bold X text-markup
code text-markup
entity latex-or-entity
export-snippet X
footnote-reference X :inline-definition
inline-babel-call X
inline-src-block X
italic X text-markup
line-break X
latex-fragment latex-or-entity
link X X
macro X
radio-target X 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
verbatim text-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-set link-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 X X X X X
footnote-reference X X X X
inline-babel-call X X X X
inline-src-block X X X X
latex-or-entity X X X X X X
line-break X X
link X X X X
macro X X X X X
plain-link X X
radio-target X X X X
statistics-cookie X X X X
sub/superscript X X X X X X
table-cell X X
target X X X X
text-markup X X X X X
timestamp X X X X
1.3.3 Objects restrictions
--------------------------
"CAR is an element or object type containing objects and
CDR is a list of successors that will be called within an
element or object of such type.
For example, in a `radio-target' object, one can only find
entities, latex-fragments, subscript and superscript.
This alist also applies to secondary string. For example,
an `headline' type element doesn't directly contain
objects, but still has an entry since one of its
properties (`:title') does."
object-restrictions obj/elem std-set std-set-nlb l-set tc-set tr-set rt-set
------------------------------------------------------------------------------------
bold obj X
footnote-reference obj X
headline elem X
inlinetast elem X
italic obj X
item elem X
keyword elem X
link obj X
paragraph elem X
radio-target obj X
strike-through obj X
subscript obj X
superscript obj X
table-cell obj X
table-row elem X
underline obj X
verse-block elem X
2 org-element: Keywords and Properties
======================================
2.1 Affiliated Keywords
~~~~~~~~~~~~~~~~~~~~~~~
"List of affiliated keywords as strings. By default, all
keywords setting attributes (i.e. \"ATTR_LATEX\") are
affiliated keywords and need not to be in this list."
"List of affiliated keywords that can occur more than once
in an element.
Their value will be consed into a list of strings, which
will be returned as the value of the property.
This list is checked after translations have been applied.
See `org-element-keyword-translation-alist'.
By default, all keywords setting attributes (i.e.
\"ATTR_LATEX\") allow multiple occurrences and need not to
be in this list."
"List of affiliated keywords whose value can be parsed.
Their value will be stored as a secondary string: a list
of strings and objects.
This list is checked after translations have been applied.
See `org-element-keyword-translation-alist'."
"List of affiliated keywords which can have a secondary
value.
In Org syntax, they can be written with optional square
brackets before the colons. For example, RESULTS keyword
can be associated to a hash value with the following:
This list is checked after translations have been applied.
See `org-element-keyword-translation-alist'."
"Alist of usual translations for keywords. The key is the
old name and the value the new one. The property holding
their value will be named after the translated name."
keyword (new) multiple? parsed? dual? translations (old)
------------------------------------------------------------------------
"CAPTION" X X X
"HEADER" X "HEADERS"
"NAME" "DATA" "LABEL" "RESNAME"
"SOURCE" "SRCNAME" "TBLNAME"
"PLOT"
"RESULTS" X "RESULT"
2.2 Document Properties
~~~~~~~~~~~~~~~~~~~~~~~
"List of properties associated to the whole document. Any
keyword in this list will have its value parsed and stored
as a secondary string."
property
----------
"AUTHOR"
"DATE"
"TITLE"
3 Left-over
===========
Not element, not object - what is it?
,-----------
plain-link
`-----------
--
cheers,
Thorsten
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: Tabular overview of org-element.el
2013-04-20 15:18 Tabular overview of org-element.el Thorsten Jolitz
@ 2013-04-20 16:34 ` Nicolas Goaziou
2013-04-20 17:15 ` Thorsten Jolitz
0 siblings, 1 reply; 7+ messages in thread
From: Nicolas Goaziou @ 2013-04-20 16:34 UTC (permalink / raw)
To: Thorsten Jolitz; +Cc: emacs-orgmode
Hello,
Thorsten Jolitz <tjolitz@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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Tabular overview of org-element.el
2013-04-20 16:34 ` Nicolas Goaziou
@ 2013-04-20 17:15 ` Thorsten Jolitz
2013-04-20 17:42 ` Nicolas Goaziou
0 siblings, 1 reply; 7+ messages in thread
From: Thorsten Jolitz @ 2013-04-20 17:15 UTC (permalink / raw)
To: emacs-orgmode
Nicolas Goaziou <n.goaziou@gmail.com> writes:
> Hello,
>
> Thorsten Jolitz <tjolitz@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
| -----------------------------------------------------------------
| bold X text-markup
| code text-markup
| entity latex-or-entity
| export-snippet X
| footnote-reference X :inline-definition
| inline-babel-call X
| inline-src-block X
| italic X text-markup
| line-break X
| latex-fragment latex-or-entity
| link X X
| macro X
| radio-target X 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
| verbatim text-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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Tabular overview of org-element.el
2013-04-20 17:15 ` Thorsten Jolitz
@ 2013-04-20 17:42 ` Nicolas Goaziou
2013-04-20 18:45 ` Thorsten Jolitz
0 siblings, 1 reply; 7+ messages in thread
From: Nicolas Goaziou @ 2013-04-20 17:42 UTC (permalink / raw)
To: Thorsten Jolitz; +Cc: emacs-orgmode
Thorsten Jolitz <tjolitz@gmail.com> writes:
> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
>> Hello,
>>
>> Thorsten Jolitz <tjolitz@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
> | -----------------------------------------------------------------
> | bold X text-markup
> | code text-markup
> | entity latex-or-entity
> | export-snippet X
> | footnote-reference X :inline-definition
> | inline-babel-call X
> | inline-src-block X
> | italic X text-markup
> | line-break X
> | latex-fragment latex-or-entity
> | link X X
> | macro X
> | radio-target X 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
> | verbatim text-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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Tabular overview of org-element.el
2013-04-20 17:42 ` Nicolas Goaziou
@ 2013-04-20 18:45 ` Thorsten Jolitz
2013-04-20 19:07 ` Nicolas Goaziou
0 siblings, 1 reply; 7+ messages in thread
From: Thorsten Jolitz @ 2013-04-20 18:45 UTC (permalink / raw)
To: emacs-orgmode
Nicolas Goaziou <n.goaziou@gmail.com> writes:
> Thorsten Jolitz <tjolitz@gmail.com> writes:
>
>> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>>
>>> Hello,
>>>
>>> Thorsten Jolitz <tjolitz@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
>> | -----------------------------------------------------------------
>> | bold X text-markup
>> | code text-markup
>> | entity latex-or-entity
>> | export-snippet X
>> | footnote-reference X :inline-definition
>> | inline-babel-call X
>> | inline-src-block X
>> | italic X text-markup
>> | line-break X
>> | latex-fragment latex-or-entity
>> | link X X
>> | macro X
>> | radio-target X 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
>> | verbatim text-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
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: Tabular overview of org-element.el
2013-04-20 18:45 ` Thorsten Jolitz
@ 2013-04-20 19:07 ` Nicolas Goaziou
2013-04-20 20:45 ` Thorsten Jolitz
0 siblings, 1 reply; 7+ messages in thread
From: Nicolas Goaziou @ 2013-04-20 19:07 UTC (permalink / raw)
To: Thorsten Jolitz; +Cc: emacs-orgmode
Thorsten Jolitz <tjolitz@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
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: Tabular overview of org-element.el
2013-04-20 19:07 ` Nicolas Goaziou
@ 2013-04-20 20:45 ` Thorsten Jolitz
0 siblings, 0 replies; 7+ messages in thread
From: Thorsten Jolitz @ 2013-04-20 20:45 UTC (permalink / raw)
To: emacs-orgmode
Nicolas Goaziou <n.goaziou@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
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2013-04-20 20:46 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-04-20 15:18 Tabular overview of org-element.el Thorsten Jolitz
2013-04-20 16:34 ` Nicolas Goaziou
2013-04-20 17:15 ` Thorsten Jolitz
2013-04-20 17:42 ` Nicolas Goaziou
2013-04-20 18:45 ` Thorsten Jolitz
2013-04-20 19:07 ` Nicolas Goaziou
2013-04-20 20:45 ` Thorsten Jolitz
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).