Re: Updating the Babel section of Worg

[tsd@tsdye.com (Thomas S. Dye)]

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

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


[-- Attachment #2: Language description template --]
[-- Type: text/plain, Size: 2650 bytes --]

#+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

[-- Attachment #3: Type: text/plain, Size: 10620 bytes --]



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

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