Hi Dieter,
Nicolas will probably reply at some point and he has much greater (∞ more)
insight in this topics. None the less, I hope the below message will
help a bit.
Dieter Van Eessen <dieter.van.ees...@gmail.com> writes:
> 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 ....)
Don't use org-element-<element>-parser directly.
Use org-element-at-point or org-element-contents. The former is for
elements, the latter is for contents, such as scripts, bold, etc. See the
head of org-element.el.
> 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)
Org-element is a parser and manipulation might not be super efficient with
org-element, but it can be done.
OTOH Org-syntax is great for manipulation. E.g. to insert a heading you
can do (insert (format "* %s" "my-heading")).
> b) Parse the region: Get TREE and CONTENT
> (Are they always separated for manipulation?)
See org-element-map for operating on a subset of the consents. You could
also use narrowing to operate only on a subset of the buffer.
> c) Manipulate tree AND/OR manipulate content
Manipulate whatever you have as you want. Org-elements are plists. Check
org-element-type, org-element-property, org-element-contents,
org-element-put-property, org-element-set-contents. See also
";;; Accessors and Setters" in org-element.el.
org-element-interpret-data is the way to go from an element to
org-syntax. Here's an example:
http://emacs.stackexchange.com/questions/2869/turn-a-list-or-data-structure-into-an-org-document/
> 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?)
Don't use org-element-<element>interpreters. Use
org-element-interpret-data for transforming org-element→org-syntax.
> e) See the manipulated stuff appear in the buffer.
There's insert for that.
> 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.
I don't get 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:
In Emacs-lisp typically "--" indicates that it's a private function.
Don't use it.
> 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)?
See above.
> 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),...).
So use org-element-map and org-element-parse-buffer.
Hope it helps,
Rasmus
--
The second rule of Fight Club is: You do not talk about Fight Club
