From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: Comment on Org Export Reference Date: Fri, 06 Mar 2015 12:22:57 +0100 Message-ID: <87twxy8j5a.fsf@nicolasgoaziou.fr> References: <14bedd41838.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> <14bee4be430.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:37732) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YTqKE-0005B4-A9 for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 06:21:51 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YTqKB-0001os-2I for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 06:21:50 -0500 Received: from relay3-d.mail.gandi.net ([2001:4b98:c:538::195]:52931) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YTqKA-0001oj-P5 for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 06:21:46 -0500 In-Reply-To: <14bee4be430.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> (James Harkins's message of "Fri, 06 Mar 2015 16:55:26 +0800") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: James Harkins Cc: emacs-orgmode@gnu.org Hello, James Harkins 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