Re: Updating the Babel section of Worg

[Martyn Jago <martyn.jago@btinternet.com>]

Hi Thomas and Eric

Love it. I will try to help!

Worg is a great resource that is getting better and better.

The template looks good (Babel wise) and should be up there as a
check-sheet, although maybe not as a requirement.

Eric - perhaps mark good pages as good rather than bad pages. They're
not necessarily bad?

It would be cool to say  [Tested 2 days ago] at the top of the page
(in a nice green) or something like that. (or validation link in green /
yellow / red)

I also think that [Under development] should be removed from
index.html. Worg is always under development, that's what it is?

For anybody that is not that familiar with Worg, you can contribute to
it right now - it's pure community.

 Best, Martyn

tsd@tsdye.com (Thomas S. Dye) writes:

> Hi Eric,
>
> I've attached a first draft of a template for review and revision.  It
> is heavily influenced by John Hendy's terrific gnuplot page.  I
> believe it incorporates the points in your outline.  Feel free to
> edit as appropriate.
>
> All the best,
> Tom
>
>
> #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
> #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
> #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
> #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
> #+TITLE:      Language Source Code Blocks in Org Mode
> #+AUTHOR:     Your name
> #+EMAIL:      you[at]email[dot]org
> #+LANGUAGE:   en
> #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
> #+LINK_UP:    ../languages.php
> #+LINK_HOME:  http://orgmode.org/worg/
> #+EXPORT_EXCLUDE_TAGS: noexport
>
> #+name: banner
> #+begin_html
>   <div id="subtitle" style="float: center; text-align: center;">
>   <p>
>   Org Mode support for <a href="http://language-site/">Language</a>
>   </p>
>   <p>
>   <a href="http://language-site/">
>   <img src="http://language-site/graphic.file"/>
>   </a>
>   </p>
>   </div>
> #+end_html
>
> * Template Checklist [0/13]                                        :noexport:
>   - [ ] Revise #+TITLE:
>   - [ ] Indicate #+AUTHOR:
>   - [ ] Add #+EMAIL:
>   - [ ] Revise banner source block [0/3]
>     - [ ] Add link to a useful language web site
>     - [ ] Replace "Language" with language name
>     - [ ] Find a suitable graphic and use it to link to the language
>       web site
>   - [ ] Write an [[Introduction]]
>   - [ ] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
>   - [ ] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
>   - [ ] Specify [[Org%20Mode%20Configuration][Org Mode Configuration]]
>   - [ ] Describe [[Header%20Arguments][Header Arguments]]
>   - [ ] Describe support for [[Sessions]]
>   - [ ] Describe [[Result%20Types][Result Types]]
>   - [ ] Describe [[Other]] differences from supported languages
>   - [ ] Provide brief [[Examples%20of%20Use][Examples of Use]]
> * Introduction
>   - Brief description of language.
>   - Range of typical uses within Org Mode.
>   - Link to this Org Mode file.
> * Requirements and Setup
>   - Installation and configuration of language software
>   - Emacs configuration
> * Org Mode Features for Language Source Code Blocks
> ** Org Mode Configuration
>    - org-babel-do-load-languages
> ** Header Arguments
>    - Language-specific default values
>    - Language-specific header arguments
> ** Sessions
>    - Support or not
>    - Typical use for sessions
> ** Result Types
>    - Which result types are supported?
> ** Other
>    - Differences from other supported languages
> * Examples of Use
>   - Hello World!
>   - Common uses
>   - Links to tutorials and other resources
>
>
> Eric Schulte <eric.schulte@gmx.com> writes:
>
>> Hi Tom,
>>
>> tsd@tsdye.com (Thomas S. Dye) writes:
>>
>>> Hi Eric,
>>>
>>> Yes, this is overdue.  I think your plan is a good one.
>>>
>>> Perhaps a few of the individual use cases could be moved to FIXME,
>>> instead?  I'm thinking here of Feiming Chen's R setup and some of my
>>> contributions when I was experimenting writing LaTeX inside source
>>> code blocks.  The authors could resurrect these as they see fit.
>>>
>>
>> I don't know what FIXME is, but if there is a way to keep the page in
>> the worg git repository but remove it from the exported HTML then that
>> sounds ideal.
>>
>>>
>>> Hopefully, others will contribute use examples.  My sense from reading
>>> the list is there are many interesting ones.
>>>
>>> I'd like it if Org mode users designed a template for the language
>>> specific pages.  Currently, these seem to me a mixed bag and it would be
>>> good to regularize them.
>>
>> The below is a modified version of a template which can be found in a
>> couple of the existing language tutorials, I think it serves as a good
>> starting point.
>>
>> - Install and Setup
>>   - Instillation and configuration of software (e.g., the language itself)
>>   - Configuration of Emacs (e.g., activate language, set command path)
>> - Examples
>>   - Common ways to use the language in an Org-mode document
>> - Special cases
>>   - are there any language-specific header arguments
>>   - does the language support session evaluation
>>   - does the language support all result types
>>   - is the language different from most babel languages
>>     (e.g., C is compiled before execution, ditaa returns files, etc...)
>>
>>> It would also be nice to have one for each of the supported languages.
>>> There are 11 language specific pages now, which leaves quite a few
>>> languages under-documented.
>>
>> (length org-babel-load-languages) ;; => 27
>>
>> ls org-contrib/babel/languages/ob-doc-*|wc -l # => 11
>>
>> It looks like we have at least 16 more to go before we hit full language
>> coverage.  Perhaps we should use the empty cells in the "documentation"
>> column in the languages table at [1] as a sign up space for volunteers
>> who would be willing to write a brief tutorial demonstrating usage of
>> Org-mode with their favorite language.
>>
>> Moving forward this is likely something we could request of the
>> contributors of new languages.
>>
>> Also, once the template above is finalized it should be posted on worg
>> and linked to through the languages page.
>>
>>>
>>> I'll be happy to work on this as I can.
>>>
>>
>> Great, I don't anticipate having time to put towards this, although I'll
>> be happy to help troubleshoot where I can.
>>
>> Cheers,
>>
>>>
>>> All the best,
>>> Tom
>>>
>>>
>>> Eric Schulte <eric.schulte@gmx.com> writes:
>>>
>>>> Thanks for raising this point.  The bulk of the content in the Babel
>>>> portion of worg is fairly old, predating the syntax standardization
>>>> efforts this fall.  I've just pushed some minor updates to the main
>>>> babel pages, but updating the language-specific tutorials and the
>>>> individual use cases will be a much larger effort.
>>>>
>>>> I'm not sure how to proceed.  One option would be to go through and add
>>>> a [uses deprecated syntax] tag to the top of each such page, which could
>>>> be removed after the page has been checked and possibly updated to
>>>> ensure consistency with the latest syntax.
>>>>
>>>> Given that the Babel syntax will not be changing significantly moving
>>>> forward now would be a good time to do such a review.  Ideally this
>>>> could be completed before the release of Emacs 24 in a couple of months.
>>>>
>>>> Any other ideas for update/reorganization or volunteers?
>>>>
>>>> Cheers,
>>>>
>>>> tsd@tsdye.com (Thomas S. Dye) writes:
>>>>
>>>>> Hi Riccardo,
>>>>>
>>>>> Thanks for the URL.  Org mode has evolved since this article was
>>>>> written.  It should probably be revised or taken off Worg.  I've copied
>>>>> Eric Schulte, who is better able than me to determine the correct course
>>>>> of action here.
>>>>>
>>>>> In the meantime, an up-to-date description of how Org mode can be used
>>>>> to write literate programs has appeared in the Journal of Statistical
>>>>> Software.  You can find it here: http://www.jstatsoft.org/v46/i03
>>>>>
>>>>> Perhaps you could use the examples in the JSS article to get started?
>>>>> If these don't work for you, or if they raise questions that are difficult
>>>>> to answer, please do come back to the list with your queries.
>>>>>
>>>>> All the best,
>>>>> Tom
>>>>>
>>>>> Riccardo Romoli <ric.romoli@gmail.com> writes:
>>>>>
>>>>>> Hi, this is the URL:
>>>>>>
>>>>>> http://orgmode.org/worg/org-contrib/babel/how-to-use-Org-Babel-for-R.html
>>>>>>
>>>>>> Best
>>>>>> R
>>>>>>
>>>>>> 2012/2/5 Thomas S. Dye <tsd@tsdye.com>
>>>>>>
>>>>>>> Hi Riccardo,
>>>>>>>
>>>>>>> This code appears to be outdated.  I don't recall this code on the org
>>>>>>> site.  Could you send a URL?
>>>>>>>
>>>>>>> All the best,
>>>>>>> Tom
>>>>>>>
>>>>>>> Riccardo Romoli <ric.romoli@gmail.com> writes:
>>>>>>>
>>>>>>> > Hi, I'm trying to generate some figure with R, into an org session.
>>>>>>> Firstly
>>>>>>> > I use the code in the org site. The problem is that the code do not
>>>>>>> > generate any figure.
>>>>>>> >
>>>>>>> > This is the code:
>>>>>>> >
>>>>>>> > #+TITLE:Test
>>>>>>> > #+AUTHOR: Your Name
>>>>>>> > #+EMAIL: your-email@server.com
>>>>>>> > #+BABEL: :session *R* :cache yes :results output graphics :exports
>>>>>>> > both :tangle yes
>>>>>>> >
>>>>>>> > * Example of Org-Babel for R Literate Programming
>>>>>>> > ** R text output
>>>>>>> > A simple summary.
>>>>>>> > #+begin_src R
>>>>>>> >   x <- rnorm(10)
>>>>>>> >   summary(x)
>>>>>>> > #+end_src
>>>>>>> >
>>>>>>> > ** R graphics output
>>>>>>> > Note we use the object =x= generated in previous code block, thanks to
>>>>>>> > the header option =:session *R*=.  The output graphics file is
>>>>>>> > =a.png=.
>>>>>>> >
>>>>>>> > #+begin_src R  :file a.png
>>>>>>> >   y <- rnorm(10)
>>>>>>> >   plot(x, y)
>>>>>>> > #+end_src
>>>>>>> >
>>>>>>> > Same plot with larger dimension:
>>>>>>> >
>>>>>>> > #+begin_src R  :file b.png :width 800 :height 800
>>>>>>> >   plot(x, y)
>>>>>>> > #+end_src
>>>>>>> >
>>>>>>> >
>>>>>>> > Where do I wrong?
>>>>>>> >
>>>>>>> > Best
>>>>>>> > Riccardo
>>>>>>> > Hi, I&#39;m trying to generate some figure with R, into an org session.
>>>>>>> Firstly I use the code in the org site. The problem is that the code do not
>>>>>>> generate any figure. This is the code:
>>>>>>> > #+TITLE:Test
>>>>>>> > #+AUTHOR: Your Name
>>>>>>> > #+EMAIL: mailto:your-email@server.com
>>>>>>> > #+BABEL: :session *R* :cache yes :results output graphics :exports both
>>>>>>> :tangle yes
>>>>>>> >
>>>>>>> > * Example of Org-Babel for R Literate Programming
>>>>>>> > ** R text output
>>>>>>> > A simple summary.
>>>>>>> > #+begin_src R
>>>>>>> >   x <- rnorm(10)
>>>>>>> >   summary(x)
>>>>>>> > #+end_src
>>>>>>> >
>>>>>>> > ** R graphics output
>>>>>>> > Note we use the object =x= generated in previous code block, thanks to
>>>>>>> > the header option =:session *R*=.  The output graphics file is
>>>>>>> > =a.png=.
>>>>>>> >
>>>>>>> > #+begin_src R  :file a.png
>>>>>>> >   y <- rnorm(10)
>>>>>>> >   plot(x, y)
>>>>>>> > #+end_src
>>>>>>> >
>>>>>>> > Same plot with larger dimension:
>>>>>>> >
>>>>>>> > #+begin_src R  :file b.png :width 800 :height 800
>>>>>>> >   plot(x, y)
>>>>>>> > #+end_src
>>>>>>> > Where do I wrong?BestRiccardo
>>>>>>>
>>>>>>> --
>>>>>>> Thomas S. Dye
>>>>>>> http://www.tsdye.com
>>>>>>>
>>>>>> Hi, this is the URL:http://orgmode.org/worg/org-contrib/babel/how-to-use-Org-Babel-for-R.htmlBestR
>>>>>> 2012/2/5 Thomas S. Dye <span dir="ltr"><mailto:tsd@tsdye.com></span>Hi Riccardo,
>>>>>>
>>>>>>
>>>>>> This code appears to be outdated.  I don&#39;t recall this code on the org
>>>>>> site.  Could you send a URL?
>>>>>>
>>>>>> All the best,
>>>>>> Tom
>>>>>>
>>>>>> Riccardo Romoli <mailto:ric.romoli@gmail.com> writes:
>>>>>>
>>>>>>> Hi, I&#39;m trying to generate some figure with R, into an org session. Firstly
>>>>>>> I use the code in the org site. The problem is that the code do not
>>>>>>> generate any figure.
>>>>>>>
>>>>>>> This is the code:
>>>>>>>
>>>>>>> #+TITLE:Test
>>>>>>> #+AUTHOR: Your Name
>>>>>>> #+EMAIL: mailto:your-email@server.com
>>>>>>> #+BABEL: :session *R* :cache yes :results output graphics :exports
>>>>>>> both :tangle yes
>>>>>>>
>>>>>>> * Example of Org-Babel for R Literate Programming
>>>>>>> ** R text output
>>>>>>> A simple summary.
>>>>>>> #+begin_src R
>>>>>>>   x <- rnorm(10)
>>>>>>>   summary(x)
>>>>>>> #+end_src
>>>>>>>
>>>>>>> ** R graphics output
>>>>>>> Note we use the object =x= generated in previous code block, thanks to
>>>>>>> the header option =:session *R*=.  The output graphics file is
>>>>>>> =a.png=.
>>>>>>>
>>>>>>> #+begin_src R  :file a.png
>>>>>>>   y <- rnorm(10)
>>>>>>>   plot(x, y)
>>>>>>> #+end_src
>>>>>>>
>>>>>>> Same plot with larger dimension:
>>>>>>>
>>>>>>> #+begin_src R  :file b.png :width 800 :height 800
>>>>>>>   plot(x, y)
>>>>>>> #+end_src
>>>>>>>
>>>>>>>
>>>>>>> Where do I wrong?
>>>>>>>
>>>>>>> Best
>>>>>>> Riccardo
>>>>>>> Hi, I&#39;m trying to generate some figure with R, into an org
>>>>>>> session. Firstly I use the code in the org site. The problem is
>>>>>>> that the code do not generate any figure. This is the code:
>>>>>>> #+TITLE:Test
>>>>>>> #+AUTHOR: Your Name
>>>>>>> #+EMAIL: mailto:mailto:your-email@server.com
>>>>>>> #+BABEL: :session *R* :cache yes :results output graphics :exports both :tangle yes
>>>>>>>
>>>>>>> * Example of Org-Babel for R Literate Programming
>>>>>>> ** R text output
>>>>>>> A simple summary.
>>>>>>> #+begin_src R
>>>>>>>   x <- rnorm(10)
>>>>>>>   summary(x)
>>>>>>> #+end_src
>>>>>>>
>>>>>>> ** R graphics output
>>>>>>> Note we use the object =x= generated in previous code block, thanks to
>>>>>>> the header option =:session *R*=.  The output graphics file is
>>>>>>> =a.png=.
>>>>>>>
>>>>>>> #+begin_src R  :file a.png
>>>>>>>   y <- rnorm(10)
>>>>>>>   plot(x, y)
>>>>>>> #+end_src
>>>>>>>
>>>>>>> Same plot with larger dimension:
>>>>>>>
>>>>>>> #+begin_src R  :file b.png :width 800 :height 800
>>>>>>>   plot(x, y)
>>>>>>> #+end_src
>>>>>>> Where do I wrong?BestRiccardo
>>>>>>
>>>>>> <span class="HOEnZb">--
>>>>>> Thomas S. Dye
>>>>>> http://www.tsdye.com
>>>>>> </span>
>>
>>
>> Footnotes: 
>> [1]  http://orgmode.org/worg/org-contrib/babel/languages.html