From mboxrd@z Thu Jan 1 00:00:00 1970 From: Marcin Borkowski Subject: Re: Comment on Org Export Reference Date: Fri, 06 Mar 2015 14:40:11 +0100 Message-ID: <877fuutfb8.fsf@wmi.amu.edu.pl> References: <14bedd41838.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> <14bee4be430.27cd.0bb60a3c7e492ea180363c67eb170725@qq.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:33031) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YTsUR-0006VA-5a for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 08:40:32 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YTsUM-0005Vo-Dg for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 08:40:31 -0500 Received: from msg.wmi.amu.edu.pl ([2001:808:114:2::50]:42718) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YTsUM-0005VV-2u for emacs-orgmode@gnu.org; Fri, 06 Mar 2015 08:40:26 -0500 Received: from localhost (localhost [127.0.0.1]) by msg.wmi.amu.edu.pl (Postfix) with ESMTP id 7F13657B1F for ; Fri, 6 Mar 2015 14:40:23 +0100 (CET) Received: from msg.wmi.amu.edu.pl ([127.0.0.1]) by localhost (msg.wmi.amu.edu.pl [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id lG9To296RBc9 for ; Fri, 6 Mar 2015 14:40:23 +0100 (CET) Received: from localhost (unknown [150.254.83.220]) by msg.wmi.amu.edu.pl (Postfix) with ESMTPSA id 5832B57B14 for ; Fri, 6 Mar 2015 14:40:23 +0100 (CET) In-reply-to: <14bee4be430.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 On 2015-03-06, at 09:55, James Harkins wrote: > I've been working on an export backend for personal use, and I find the= =20 > documentation on worg to be... not quite what I need. In the spirit of=20 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=20 > instance, the toolbox is documented extensively, but I didn't see a=20 > comprehensive list of the transcoding functions that a backend should=20 > implement, nor details of these functions' inputs, nor recommendations = for=20 > handling elements that aren't obvious (tags, links, footnotes...). In m= y=20 > first attempt, I even left out ox-*-template -- I had no idea what the=20 > template was or its importance! (It is actually sort of covered on worg= ,=20 > but it's buried in a quoted docstring with nothing to highlight its rat= her=20 > crucial nature.) > > I've had to infer these from ox-ascii.el, which also covers a lot of ca= ses=20 > that aren't relevant to this exporter, making it hard to guess what is=20 > strictly necessary. The result for me has been rather remarkable amount= s of=20 > 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=20 > arguments. Like, yesterday I was trying to use org-export-get-parent:=20 > first, find out that the function exists on worg, then switch to emacs = and=20 > C-h f it to find out *really* how to use it. Why C-h f? Because the wor= g=20 > page says *nothing* about the arguments! > > At the very least, another section needs to be added, listing the eleme= nts=20 > that need to be transcoded. Also some common cases might be nice, e.g.,= =20 > what's the canonical way to access tags? Properties? Typical cases for=20 > links that you wouldn't think of unless you already know what you're do= ing=20 > (but if you already knew what you're doing, you wouldn't be scouring th= e=20 > reference)? > > I'll add that, despite some painful false starts, I've got a shocking=20 > amount of the elements working already. Some, that I might have expecte= d to=20 > be hard (e.g., plain lists) were close to trivially easy! So I'd say th= e=20 > exporter design is a thing of beauty -- serious applause for this -- it= 's=20 > just that the entry point involves too much puzzling over source code a= nd=20 > 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 =E2=80=93 in fact, I was thinking to= day 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, --=20 Marcin Borkowski http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski Faculty of Mathematics and Computer Science Adam Mickiewicz University