From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Hendy Subject: Re: Proposal for new/updated exporter tutorials on Worg Date: Sun, 31 Mar 2013 23:58:44 -0500 Message-ID: References: <9B43E6D4-7EF9-40BE-9AA4-E6236EB1793D@gmail.com> <87y5d5ypa6.fsf@bzg.ath.cx> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Return-path: Received: from eggs.gnu.org ([208.118.235.92]:59603) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UMWpV-0000qk-O2 for emacs-orgmode@gnu.org; Mon, 01 Apr 2013 00:58:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UMWpS-0005lL-3w for emacs-orgmode@gnu.org; Mon, 01 Apr 2013 00:58:49 -0400 Received: from mail-lb0-f180.google.com ([209.85.217.180]:58153) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UMWpR-0005lF-RM for emacs-orgmode@gnu.org; Mon, 01 Apr 2013 00:58:46 -0400 Received: by mail-lb0-f180.google.com with SMTP id t11so1642016lbi.11 for ; Sun, 31 Mar 2013 21:58:44 -0700 (PDT) In-Reply-To: <87y5d5ypa6.fsf@bzg.ath.cx> 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: Bastien Cc: emacs-orgmode , "Thomas S. Dye" , Carsten Dominik On Sat, Mar 30, 2013 at 8:45 AM, Bastien wrote: > Hi John, > > thanks for the great work so far! This is of huge help. No problem -- In the absence of lisp ability... the least I can do, in fact. > > John Hendy writes: > >> My thinking on this is that Org-8.0 is a significant step, however it >> would be nice to write documentation as it pertains to Org 8.0 and not >> constantly in reference to how it's different from Org-7.x. > > Agreed. If there is no indication on the Worg page, users should be > right in assuming this is for the latest stable version. > > Instead of an "OUTDATED" cookie, I suggest introducing > > #+PROPERTY: OrgCompat_ALL 8.0 7.9 7.8 7.7 > > (... using values from `customize-package-emacs-version-alist') > > in a setup file and > > #+PROPERTY: OrgCompatible 8.0 > > in files where instructions are relevant starting from 8.0. > > Then a macro could insert that compatible version. > > What do you think? > Not sure how to implement this, but sounds reasonable. I'd like to get everything export related into it's own directories, if possible. Right now, they're just in org-tutorials for the most part. I'll have to look more closely at what's actually in there. I see org-tutorials as related to Org in general (some of which covers export usage), and export-specific stuff to be in another category. These I'd like to see in their own bucket; if we're now separating pre-8.0 stuff and 8.0-forward things, perhaps another directory could be created. As for the outline above... I changed my mind a bit. I think it makes sense to leave your upgrade guide as the repository for... upgrade-specific information. I rearranged it a bit this evening to help with flow, and also listed out the two main changes users need to make to update: 1) Look for org-export-* options and change them to org-backend-* in config files 2) Specifically load backends in .emacs if they're using more than ASCII, HTML, and LaTeX I also pushed ox-overview, which will now serve as the primary reference for the new exporter and contains the list of exporters table. It's mostly blank, but contains a [non-exported] copy/pasted version of Nicolas' announcement on the mailing list which I think should be incorporated in there somehow. It will be good make sure Worg doesn't overlap the manual too much.[1] At the very least, it should have some explanation of the motivation behind the exporter and the features/advantages it provides (I think that would be of interest). I also made the call (could be reversed) that I think the new Worg exporter documentation should live in worg.git/exporters/backend directories. This can house: - ox-backend.org: overview, primary usage guide, tutorial, references - ox-backend-example.org: a standalone, reproducible example document - ox-backend-example.ext: a compiled/exported version of the tutorial These three will guide the user and allow him/her to download an org file and compile it locally to check their setup and/or results. I think a downloadable end result will also help give an idea of what the exporter is capable of. ox-template.org is now pushed as well. It's modified from ob-doc-template.org. Best regards, John [1] As an aside, is there a good reference for what Worg should/could contain and what should live in the manual? I've noticed recently on the list that, for example, :wrap was documented in the manual even though =:results output wrap= came up on the mailing list and was not in the Worg summary of header options. If too much is duplicated, it make for double the things to track... Where's the manual with respect to the new exporter? If it's ahead of Worg's state, the documentation on Worg can be used to supplement in reference to the manual vs. duplicating what's to come! > -- > Bastien