From: John Hendy <jw.hendy@gmail.com>
To: Carsten Dominik <carsten.dominik@gmail.com>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>, "Thomas S. Dye" <tsd@tsdye.com>
Subject: Re: Proposal for new/updated exporter tutorials on Worg
Date: Thu, 28 Mar 2013 17:07:59 -0500 [thread overview]
Message-ID: <CA+M2ft8S0HCGbuikP5OrdvYmDqwEzsiN779pLoaa3s9bMAUddw@mail.gmail.com> (raw)
In-Reply-To: <CA+M2ft96VGVDtkYZfGC=W7KU+0jGxt5i1yJ49hO2C1VZBoqqmQ@mail.gmail.com>
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
next prev parent reply other threads:[~2013-03-28 22:08 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-03-28 4:51 Proposal for new/updated exporter tutorials on Worg John Hendy
2013-03-28 5:31 ` Thomas S. Dye
2013-03-28 10:37 ` Carsten Dominik
2013-03-28 12:35 ` John Hendy
2013-03-28 22:07 ` John Hendy [this message]
2013-03-30 13:45 ` Bastien
2013-04-01 4:58 ` John Hendy
2013-04-08 15:30 ` Bastien
2013-03-28 10:35 ` Carsten Dominik
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CA+M2ft8S0HCGbuikP5OrdvYmDqwEzsiN779pLoaa3s9bMAUddw@mail.gmail.com \
--to=jw.hendy@gmail.com \
--cc=carsten.dominik@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=tsd@tsdye.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).