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