On 2015-03-06, at 09:55, James Harkins <jamshar...@qq.com> wrote: > I've been working on an export backend for personal use, and I find the > documentation on worg to be... not quite what I need. In the spirit of
In fact, studying the sources for existing exporters seems to be the best way to learn that stuff. > suggesting an avenue for improvement, then: > > 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, nor details of these functions' inputs, nor recommendations for > handling elements that aren't obvious (tags, links, footnotes...). In my > first attempt, I even left out ox-*-template -- I had no idea what the > template was or its importance! (It is actually sort of covered on worg, > but it's buried in a quoted docstring with nothing to highlight its rather > crucial nature.) > > 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. I know what you feel. I'm about two thirds into ox-latex;-). I don't treat it exactly like I wasted that time. I hear that reading other people's code is a good way to learn. (It was also not /that/ time-consuming, either; studying ox-latex has taken me less than 5 hours so far over the course of about three weeks (I had some breaks). Hooray for clocking;-)!) > 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! > > At the very least, another section needs to be added, listing the elements > that need to be transcoded. 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)? > > 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 -- it's > just that the entry point involves too much puzzling over source code and > not enough well-organized explanation. Again, I know what you feel. Writing a custom exporter is in fact easier than one might think. I'd love to see a tutorial for writing custom exporters. (I did write one such exporter, a modification of the HTML one: https://github.com/mbork/org-edu-html . I'm planning to write at least two more.) I might start such a tutorial, but I don't feel competent enough to make it comprehensive. Also, I'm not sure whether I'll be able to handle this spare-time-wise. But I'll think about it and I'll try to try that (no mistake here). What I find especially missing is: documenting the underlying data structures (and overall architecture – in fact, I was thinking today about writing a blog post about the main entry points to the exporter, but this will probably have to wait a week or two), and a way to debug it. While generating a data structure for an element is easy (org-element-at-point), the `info' parameter is rather mysterious for me (yet). I guess I'll have to run a few exporter functions through edebug or something... [After a while, thinking.] OK, to be more constructive: I think I will be able to reserve some time for studying for and writing such a tutorial. What form would be reasonable? Is a github repo with an org file a good idea? I guess that when (or rather `if'?) it gets in a reasonable shape, transferring it to worg might be useful, but this might not happen to soon. > hjh Best, -- Marcin Borkowski http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski Faculty of Mathematics and Computer Science Adam Mickiewicz University