Proposal for new/updated exporter tutorials on Worg

Proposal for new/updated exporter tutorials on Worg

[John Hendy]

Greetings,


I just pushed a changed to the 8.0 upgrade guide (scroll all the way
to the bottom):
- http://orgmode.org/worg/org-8.0.html

It features a table similar to that of the Babel languages:
- http://orgmode.org/worg/org-contrib/babel/languages.html

It simply lists the exporters Org offers, their .el location with
respect to Org directory (either in ./lisp/ox-* or
./contrib/lisp/ox-*) and a column for what I hope will turn into links
to updated exporter tutorials/detailed documentation similar to what
exists for Org Babel. Currently, Org exporter tutorials are spread
between =worg.git/org-tutorials= and =worg.git/exporters=. It looks
like the most up to date have started settling in
=worg.git/exporters=; what does the list think about deciding to stick
with that as the home for all new ox-* related documentation on Worg?

I'd propose they simply be titled according to the new names,
=worg.git/exporters/ox-*=.

I'm happy to help with a template (probably just porting
ob-doc-template to ox-template or something like that). I think the
Babel table is great; perhaps after Org-8.0 actually launches, the new
exporters could receive a similar "landing page"
(=worg.git/exporters/ox-summary= or similar) where that table could
reside and be updated as the new platform grows.

Individuals could contribute and add links at the table they can. I
think getting placeholders created for each exporter in the very near
future (which I also volunteer to do) will be really helpful as the
official shift to 8.0 happens. It will lower the barrier to entry for
getting information out of the mailing list and into Worg (I
anticipate lots more questions as infrequent upgraders/non-git users
migrate over).


Thanks for any comments/suggestions!
John

Re: Proposal for new/updated exporter tutorials on Worg

[Thomas S. Dye]

Aloha John,

Nice work.  I look forward to contributing.

Another part is either getting rid of, or clearly labeling, all the Worg
pages that deal with the old exporters.  I can see them being a source
of real confusion when 8.0 is adopted by users.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Proposal for new/updated exporter tutorials on Worg

[Carsten Dominik]

Hi John,

these are all excellent ideas, thank you for making the start to a systematic way to put this kind of information onto Worg.  If you have time to make a template, I am sure this would be appreciated.

- Carsten

On 28 mrt. 2013, at 05:51, John Hendy <jw.hendy@gmail.com> wrote:

> Greetings,
> 
> 
> I just pushed a changed to the 8.0 upgrade guide (scroll all the way
> to the bottom):
> - http://orgmode.org/worg/org-8.0.html
> 
> It features a table similar to that of the Babel languages:
> - http://orgmode.org/worg/org-contrib/babel/languages.html
> 
> It simply lists the exporters Org offers, their .el location with
> respect to Org directory (either in ./lisp/ox-* or
> ./contrib/lisp/ox-*) and a column for what I hope will turn into links
> to updated exporter tutorials/detailed documentation similar to what
> exists for Org Babel. Currently, Org exporter tutorials are spread
> between =worg.git/org-tutorials= and =worg.git/exporters=. It looks
> like the most up to date have started settling in
> =worg.git/exporters=; what does the list think about deciding to stick
> with that as the home for all new ox-* related documentation on Worg?
> 
> I'd propose they simply be titled according to the new names,
> =worg.git/exporters/ox-*=.
> 
> I'm happy to help with a template (probably just porting
> ob-doc-template to ox-template or something like that). I think the
> Babel table is great; perhaps after Org-8.0 actually launches, the new
> exporters could receive a similar "landing page"
> (=worg.git/exporters/ox-summary= or similar) where that table could
> reside and be updated as the new platform grows.
> 
> Individuals could contribute and add links at the table they can. I
> think getting placeholders created for each exporter in the very near
> future (which I also volunteer to do) will be really helpful as the
> official shift to 8.0 happens. It will lower the barrier to entry for
> getting information out of the mailing list and into Worg (I
> anticipate lots more questions as infrequent upgraders/non-git users
> migrate over).
> 
> 
> Thanks for any comments/suggestions!
> John
> 

Re: Proposal for new/updated exporter tutorials on Worg

[Carsten Dominik]

On 28 mrt. 2013, at 06:31, Thomas S. Dye <tsd@tsdye.com> wrote:

> Aloha John,
> 
> Nice work.  I look forward to contributing.
> 
> Another part is either getting rid of, or clearly labeling, all the Worg
> pages that deal with the old exporters.  I can see them being a source
> of real confusion when 8.0 is adopted by users.

Indeed.  Maybe start by adding an OUTDATED banner or something like this to the page.  Or we could move all these pages to a separate directory and keep it there for a while, until 8.0 has made it into an Emacs *release*.

- Carsten

> 
> All the best,
> Tom
> 
> -- 
> Thomas S. Dye
> http://www.tsdye.com
> 

Re: Proposal for new/updated exporter tutorials on Worg

[John Hendy]

[-- Attachment #1: Type: text/plain, Size: 958 bytes --]

On Mar 28, 2013 5:37 AM, "Carsten Dominik" <carsten.dominik@gmail.com>
wrote:
>
>
> On 28 mrt. 2013, at 06:31, Thomas S. Dye <tsd@tsdye.com> wrote:
>
> > Aloha John,
> >
> > Nice work.  I look forward to contributing.
>
> > Another part is either getting rid of, or clearly labeling, all the Worg
> > pages that deal with the old exporters.  I can see them being a source
> > of real confusion when 8.0 is adopted by users.
>
> Indeed.  Maybe start by adding an OUTDATED banner or something like this
to the page.  Or we could move all these pages to a separate directory and
keep it there for a while, until 8.0 has made it into an Emacs *release*.
>

I was thinking about that too. Someone already created a redirect page from
org-tutorials/beamer to exportets/beamer. Is this recommended to prevent
link rot?

I'll get on the templates shortly!

John
> - Carsten
>
> >
> > All the best,
> > Tom
> >
> > --
> > Thomas S. Dye
> > http://www.tsdye.com
> >
>

[-- Attachment #2: Type: text/html, Size: 1391 bytes --]

Re: Proposal for new/updated exporter tutorials on Worg

[John Hendy]

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

Re: Proposal for new/updated exporter tutorials on Worg

[Bastien]

Hi John,

thanks for the great work so far!  This is of huge help.

John Hendy <jw.hendy@gmail.com> 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?

-- 
 Bastien

Re: Proposal for new/updated exporter tutorials on Worg

[John Hendy]

On Sat, Mar 30, 2013 at 8:45 AM, Bastien <bzg@altern.org> 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 <jw.hendy@gmail.com> 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

Re: Proposal for new/updated exporter tutorials on Worg

[Bastien]

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

>> What do you think?
>
> Not sure how to implement this, but sounds reasonable. 

Thanks.  So basically the idea is just to use

#+PROPERTY: OrgCompat 8.0 

on top of Worg files that contain 8.0-only information, and 

  :PROPERTIES:
  :OrgCompat: 8.0
  :END:

in sections that are 8.0-only.

I started to do this with the new tutorial I just pushed about agenda
filtering/limiting:

  http://orgmode.org/worg/org-tutorials/agenda-filters.org

We don't need to update Worg systematically at this point, just keep
this property in mind when we write new stuff.

> I'd like to get
> everything export related into it's own directories, if possible.

Sounds reasonable.

> ox-template.org is now pushed as well. It's modified from
>ob-doc-template.org.

Thanks for all these updates!

> [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...

The manual is a trade-off between completeness and minimalism: it
reflects current fonctionalities and tries to give the minimal info
needed for the max number of features.

Worg is a trade-off between inclusiveness and precision: because it is
inclusive (contributors are welcome to write 10-pages tutorial about
an obscure feature), and because it's too hard to delete obsolete
information, it lacks accurateness sometimes -- hence the OrgCompat
trick, which will make things better.

As for where to add things first, contributors should first think
about fixing the manual, then contribute to Worg.  If fixing the
manual is possible (with the trade-off exposed above in mind), then
let's go for it.  If it's beyond this trade-off and falls into Worg's
one, let's go for Worg.

> 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!

Nicolas, Thomas and I are working on it -- sorry it takes so long.

-- 
 Bastien