From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Hendy Subject: Re: Proposal for new/updated exporter tutorials on Worg Date: Thu, 28 Mar 2013 17:07:59 -0500 Message-ID: References: <9B43E6D4-7EF9-40BE-9AA4-E6236EB1793D@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Return-path: Received: from eggs.gnu.org ([208.118.235.92]:32786) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ULKzL-00020U-GI for emacs-orgmode@gnu.org; Thu, 28 Mar 2013 18:08:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ULKzK-0008MT-1d for emacs-orgmode@gnu.org; Thu, 28 Mar 2013 18:08:03 -0400 Received: from mail-la0-x22b.google.com ([2a00:1450:4010:c03::22b]:64608) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ULKzJ-0008L9-PC for emacs-orgmode@gnu.org; Thu, 28 Mar 2013 18:08:01 -0400 Received: by mail-la0-f43.google.com with SMTP id ek20so23659lab.2 for ; Thu, 28 Mar 2013 15:08:00 -0700 (PDT) In-Reply-To: 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: Carsten Dominik Cc: emacs-orgmode , "Thomas S. Dye" Started restructuring a bit. Here's what I have: |-- beamer | |-- index.org | |-- ox-beamer.org | |-- presentation.org | `-- tutorial.org |-- filter-markup.org |-- freemind.org |-- index.org |-- ox-overview.org |-- ox-template.org |-- taskjuggler.org `-- xoxo.org Prior to seeing index.org, I created ox-overview.org... seems like some index.org is similar to the exporter summary table I created. If there's no syntactical reason to have an index.org file, would the summary table replace this? I transformed the ob-doc-template file into ox-template.org and inserted some suggestions/hints on how to fill it in. It includes a "Reference" section suggesting that the creator add links to other tutorials and reference information as well as to the ox-*.el file itself. Most of the above is "as-is" (how I found it). If others want, each exporter could have it's own dir containing: - ox-*.org: documentation for language - ox-*-example.org: reproducible example for users to download and export - ox-*-compiled.*: end result file so users can compare their export to the "right" output, or simply see what they might achieve with the export backend. I'd like to do away with a dedicated tutorial and simply have this as part of ox-*.org. If the list wants, I could see leaving the names as =backend.org= or going with my original thought, which was =ox-backend.org=. I also plan to implement the following: - worg/org-8.0 will become an overview of general changes in Org-mode version 8.0 - General stuff - Some files moved from A to B - Lots of syntax changed - The exporter pertinent change information will be moved to worg.git/exporters/ox-overview.org (or ox-summary if that's preferred) - General information (I added a section to be filled in by Nicolas or someone else about reasons for the change and advantages) - File locations, naming conventions, etc. - .emacs setup syntax - Instruction for users to refer to the backend-specific documentation for proper syntax - The table like ob-languages that can be updated with links to Worg documentation as it is created - I also added links to the manual sections for each exporter where it exists - For everything else that's just about universal .org file options and setup, I propose ox-setup.org - #+TOC syntax - #+options syntax - Etc. - For anything else, it should live in it's backend-specific page 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. Thus, current syntax can simply be written without having to worry about constantly referencing the older syntax. Make users well aware on the upgrade guide that there were significant changes, and then point them to the actual documentation, not documentation that is constantly written in the shadow of what it no longer is (if that makes sense). Let me know if there are any concerns with this approach! I haven't pushed the changes yet. Not sure on the ballpark release date for Org-8.0, but I'd like to at least clean up and finalize org-8.0.org, ox-overview.org, and ox-setup.org. I also plan to migrate stuff in org-tutorials over to worg.git/exporters. Thanks for any feedback! John