Usage of org-element api

[Dieter Van Eessen <dieter.van.eessen@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3370 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 4041 bytes --]