* Proposal for new/updated exporter tutorials on Worg @ 2013-03-28 4:51 John Hendy 2013-03-28 5:31 ` Thomas S. Dye 2013-03-28 10:35 ` Carsten Dominik 0 siblings, 2 replies; 9+ messages in thread From: John Hendy @ 2013-03-28 4:51 UTC (permalink / raw) To: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 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 10:35 ` Carsten Dominik 1 sibling, 1 reply; 9+ messages in thread From: Thomas S. Dye @ 2013-03-28 5:31 UTC (permalink / raw) To: John Hendy; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 2013-03-28 5:31 ` Thomas S. Dye @ 2013-03-28 10:37 ` Carsten Dominik 2013-03-28 12:35 ` John Hendy 0 siblings, 1 reply; 9+ messages in thread From: Carsten Dominik @ 2013-03-28 10:37 UTC (permalink / raw) To: Thomas S. Dye; +Cc: emacs-orgmode 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 > ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 2013-03-28 10:37 ` Carsten Dominik @ 2013-03-28 12:35 ` John Hendy 2013-03-28 22:07 ` John Hendy 0 siblings, 1 reply; 9+ messages in thread From: John Hendy @ 2013-03-28 12:35 UTC (permalink / raw) To: Carsten Dominik; +Cc: emacs-orgmode, Thomas S. Dye [-- 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 --] ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 2013-03-28 12:35 ` John Hendy @ 2013-03-28 22:07 ` John Hendy 2013-03-30 13:45 ` Bastien 0 siblings, 1 reply; 9+ messages in thread From: John Hendy @ 2013-03-28 22:07 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 2013-03-28 22:07 ` John Hendy @ 2013-03-30 13:45 ` Bastien 2013-04-01 4:58 ` John Hendy 0 siblings, 1 reply; 9+ messages in thread From: Bastien @ 2013-03-30 13:45 UTC (permalink / raw) To: John Hendy; +Cc: emacs-orgmode, Thomas S. Dye, Carsten Dominik 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 2013-03-30 13:45 ` Bastien @ 2013-04-01 4:58 ` John Hendy 2013-04-08 15:30 ` Bastien 0 siblings, 1 reply; 9+ messages in thread From: John Hendy @ 2013-04-01 4:58 UTC (permalink / raw) To: Bastien; +Cc: emacs-orgmode, Thomas S. Dye, Carsten Dominik 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 2013-04-01 4:58 ` John Hendy @ 2013-04-08 15:30 ` Bastien 0 siblings, 0 replies; 9+ messages in thread From: Bastien @ 2013-04-08 15:30 UTC (permalink / raw) To: John Hendy; +Cc: emacs-orgmode, Thomas S. Dye, Carsten Dominik 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Proposal for new/updated exporter tutorials on Worg 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:35 ` Carsten Dominik 1 sibling, 0 replies; 9+ messages in thread From: Carsten Dominik @ 2013-03-28 10:35 UTC (permalink / raw) To: John Hendy; +Cc: emacs-orgmode 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 > ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2013-04-08 17:45 UTC | newest] Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 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 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
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).