Hello, James Harkins <jamshar...@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
