emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* 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 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).