Re: [O] Comment on Org Export Reference

[Marcin Borkowski]

On 2015-03-06, at 09:55, James Harkins <address@hidden> 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