Re: Comment on Org Export Reference

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

James Harkins <jamshark70@qq.com> writes:

> The page covers a lot of details, but less in the way of context. For
> instance, the toolbox is documented extensively, but I didn't see
> a comprehensive list of the transcoding functions that a backend
> should implement

There is no rule about what a back-end should implement (besides
template). Anyway full list of supported elements and objects, along
with all associated properties is in "Org Element API" document[fn:1].

> nor details of these functions' inputs, nor recommendations for
> handling elements that aren't obvious (tags, links, footnotes...).

I'm not sure there's a general rule to handle them. However I tried to
give real examples on how to use some tools in 

> I've had to infer these from ox-ascii.el, which also covers a lot of
> cases that aren't relevant to this exporter, making it hard to guess
> what is strictly necessary. The result for me has been rather
> remarkable amounts of wasted time.

At some point, I wanted to write a tutorial on how to create a back-end
from scratch. I even chose Markdown to do it. Unfortunately, I wrote
"ox-md.el" and, for various reasons, skipped the tutorial.

Anyway, such a tutorial is more than welcome, if you want to write one.

> I also wonder about documenting functions without documenting their
> arguments. Like, yesterday I was trying to use org-export-get-parent:
> first, find out that the function exists on worg, then switch to emacs
> and C-h f it to find out *really* how to use it. Why C-h f? Because
> the worg page says *nothing* about the arguments!

Tools section could indeed list arguments required for each tool.
However, I expect users to use Emacs internal documentation first.

Anyway, patch welcome.

> At the very least, another section needs to be added, listing the
> elements that need to be transcoded.

See above.

> Also some common cases might be nice, e.g., what's the canonical way
> to access tags? Properties? Typical cases for links that you wouldn't
> think of unless you already know what you're doing (but if you already
> knew what you're doing, you wouldn't be scouring the reference)?

There's a tool named `org-export-get-tags' with an example on how to use
it already. Likewise, there's a tool named
`org-export-get-node-property'. However, it doesn't contain an example.

> I'll add that, despite some painful false starts, I've got a shocking
> amount of the elements working already. Some, that I might have
> expected to be hard (e.g., plain lists) were close to trivially easy!
> So I'd say the exporter design is a thing of beauty -- serious
> applause for this --

Thank you.

> it's just that the entry point involves too much puzzling over source
> code and not enough well-organized explanation.

Help welcome.

Also, do not hesitate to ask questions on the ML.


Regards,

[fn:1] http://orgmode.org/worg/dev/org-element-api.html

-- 
Nicolas Goaziou