From: Marcin Borkowski <mbork@wmi.amu.edu.pl>
To: emacs-orgmode@gnu.org
Subject: Re: Comment on Org Export Reference
Date: Fri, 06 Mar 2015 14:40:11 +0100 [thread overview]
Message-ID: <877fuutfb8.fsf@wmi.amu.edu.pl> (raw)
In-Reply-To: <14bee4be430.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com>
On 2015-03-06, at 09:55, James Harkins <jamshark70@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
next prev parent reply other threads:[~2015-03-06 13:40 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <14bedd41838.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com>
2015-03-06 8:55 ` Comment on Org Export Reference James Harkins
2015-03-06 10:30 ` Rasmus
2015-03-06 11:22 ` Nicolas Goaziou
2015-03-07 3:18 ` James Harkins
2015-03-06 13:40 ` Marcin Borkowski [this message]
2015-03-06 17:23 ` Nicolas Goaziou
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=877fuutfb8.fsf@wmi.amu.edu.pl \
--to=mbork@wmi.amu.edu.pl \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).