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
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
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
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
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
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
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