[O] Tabular overview of org-element.el

[Thorsten Jolitz]

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