Re: [O] Proposal for new/updated exporter tutorials on Worg

[John Hendy]

On Sat, Mar 30, 2013 at 8:45 AM, Bastien <address@hidden> 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 <address@hidden> 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