Hello,

New to the list. Got some questions regarding the use of the org-element api. I've already learned alot by reading the emacs help and org-developers section. and the online org-element-docstrings have been very helpful. I'm not a highly skilled lisp-programmer, but got good grip on the basics and I learn fast :)

Still a few questions remain:

1) How to use org-element-content? Returns nil when used on elements parsed by org-element-<element>-parser (because they operate locally)  When used globally, it only seems to remove the car of the list (org-data ....)

2) What is actually a normal workflow if you wish to interactive manipulate only some of the elements? Is it something like:
 a)  Define the region in which you wish to manipulate things (using :begin and :extract from  org-element-at-point)
 b) Parse the region: Get TREE and CONTENT
     (Are they always separated for manipulation?)
 c) Manipulate tree AND/OR manipulate content
 d) Interpret (the org-element-<element>interpreters seem to require <element> and content whilst the org-element-interpret-data only requires a single 'data'. Why?)
 e) See the manipulated stuff appear in the buffer.

3) How can the output of (org-element-parse-secondary-string ...) be used. When I give a heading and bit of text as input (output of buffer-substring), it looks like it returns the 'content' of the region. Though I can't seem to use it anyway as 'CONTENT' for the functions  requiring this.

4) How to use org-element--parse-elements? Whilst it is running i notice that it uses (org-element--current-element) and some of the  (org-element-<element>-parser) functions. Thought it could be nice to use this one, but no matter how use it, all I get is nil. For example:
    
 (setq element-parse (org-element--parse-elements (org-element-property ':begin (org-element-at-point)) (org-element-property ':end (org-element-at-point)) 'section nil 'headline nil nil))
   
When I try such this ANYWHERE in the following text, i get nil.
* boe
* argh
** lol
    Something funny
** woot
   
5) What is org-element--current-element for? It also seems to be called by org-element--parse-element.The properties :begin, :end and :title  seem different than when parsing with org-element-at-point. Org-element-contents also nill when applied on the output. Why can't I use    
    this function (org-element--current-element) on plainlists/items (returns error with point within a plain-list/item)?


I know the basic answer to most of these question is: Why don't you use (org-element-parse-buffer). Well simply because I don't need everything. in first implementation I only need:
OR HEADLINE under point and it's subtree
  (HEADLINE (plainlist (item,item,item)),(subheadline),...)
OR the headline of an ITEM under point and subtree
 (headline (plainlist (item, ITEM,item)),(subheadline),...).

Manipulating these trees won't be too hard. I don't neccesarily need the contents, I can (buffer-substring) them using the :contents-begin and :contents-end properties.
BUT I think I will need them to write back to the buffer after having manipulated some things in the tree. Haven't investigated (org-element-interpret-data) yet, nor all the (org-element-<element>-interpreters) it calls.


It's a long mail, please don't yell at me if I overlooked stuff on the web, it's quite a huge pool of information...

Dieter Van Eessen