From mboxrd@z Thu Jan 1 00:00:00 1970 From: James Harkins Subject: Comment on Org Export Reference Date: Fri, 06 Mar 2015 16:55:26 +0800 Message-ID: <14bee4be430.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> References: <14bedd41838.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; format=flowed Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:57600) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YTo3B-0005s4-Dz for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 03:56:15 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YTo36-0001bQ-BD for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 03:56:05 -0500 Received: from smtpbgsg2.qq.com ([54.254.200.128]:49922) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YTo35-0001Ek-A8 for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 03:56:00 -0500 Received: from [10.49.252.104] (unknown [14.29.38.55]) by esmtp4.qq.com (ESMTP) with SMTP id 0 for ; Fri, 06 Mar 2015 16:55:26 +0800 (CST) In-Reply-To: <14bedd41838.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> 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: emacs-orgmode@gnu.org 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 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 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. hjh Sent with AquaMail for Android http://www.aqua-mail.com