From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: James Harkins <jamshark70@qq.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: Comment on Org Export Reference
Date: Fri, 06 Mar 2015 12:22:57 +0100 [thread overview]
Message-ID: <87twxy8j5a.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <14bee4be430.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> (James Harkins's message of "Fri, 06 Mar 2015 16:55:26 +0800")
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
next prev parent reply other threads:[~2015-03-06 11:21 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 [this message]
2015-03-07 3:18 ` James Harkins
2015-03-06 13:40 ` Marcin Borkowski
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=87twxy8j5a.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=emacs-orgmode@gnu.org \
--cc=jamshark70@qq.com \
/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).