Re: Updating the Babel section of Worg

[Eric Schulte <eric.schulte@gmx.com>]

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

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/