[Accepted] Re: Manual does not list :results output graphics as babel header arg

[Bastien Guerry <bzg@altern.org>]

Patch 1363 (http://patchwork.newartisans.com/patch/1363/) is now "Accepted".

Maintainer comment: none

This relates to the following submission:

http://mid.gmane.org/%3Cm1obnnk036.fsf_-_%40tsdye.com%3E

Here is the original message containing the patch:

> Content-Type: text/plain; charset="utf-8"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Subject: [O] Re: Manual does not list :results output graphics as babel header
> 	arg
> Date: Tue, 10 Jul 2012 22:17:01 -0000
> From: Thomas S. Dye <tsd@tsdye.com>
> X-Patchwork-Id: 1363
> Message-Id: <m1obnnk036.fsf_-_@tsdye.com>
> To: John Hendy <jw.hendy@gmail.com>
> Cc: emacs-orgmode <emacs-orgmode@gnu.org>
> 
> Aloha all,
> 
> The attached patch changes the link to the languages supported by babel
> from a directory listing to the Worg page that uses a table to link to
> the language-specific documentation pages.  It was suggested by John
> Hendy.
> 
> All the best,
> Tom
> John Hendy <jw.hendy@gmail.com> writes:
> 
> > On Tue, Jul 10, 2012 at 10:19 AM, Thomas S. Dye <tsd@tsdye.com> wrote:
> >> John Hendy <jw.hendy@gmail.com> writes:
> >>
> >>> On Mon, Jul 9, 2012 at 7:35 PM, Thomas S. Dye <tsd@tsdye.com> wrote:
> >>>> John Hendy <jw.hendy@gmail.com> writes:
> >>>>
> >>>>> I have typically outputted graphics from R via tikzDevice manually,
> >>>>> but gave my first whirl to just including things via the :file
> >>>>> argument in my block header. In the process, I was trying to get this
> >>>>> to work and found I needed to use:
> >>>>>
> >>>>> -----
> >>>>> :results output graphics
> >>>>> -----
> >>>>>
> >>>>> This is listed on Worg ob-R-doc:
> >>>>> - http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-R.html#sec-4-3
> >>>>>
> >>>>> But I didn't originally know about it, as it's not a listed header
> >>>>> argument in the manual, which is where I check since they're all
> >>>>> listed in one place:
> >>>>> - http://orgmode.org/manual/results.html#results
> >>>>>
> >>>>> Does the manual only list universal babel header arguments and R is in
> >>>>> a subset of ones using =:results output graphics= or should it be
> >>>>> there?
> >>>>>
> >>>>
> >>>> Hi John,
> >>>>
> >>>> The babel header arguments are implemented at two levels.
> >>>>
> >>>> There are general babel arguments that apply to all the supported
> >>>> languages.  These are described in the manual.
> >>>>
> >>>> It is also possible for the individual language implementations to
> >>>> define their own header arguments.  R is a good example, where the very
> >>>> many arguments to the various R output devices are built into ob-R.el.
> >>>> These language specific header arguments are not described in the
> >>>> manual, but instead appear in the language specific documentation on
> >>>> Worg.
> >>>>
> >>>> Re: your specific question about :results output graphics.  I believe
> >>>> this is an R specific header argument and that it is described in the
> >>>> appropriate place in the documentation on Worg (see lines 68 and 230
> >>>> of ob-R.el).
> >>>>
> >>>> The manual is not a one-stop source for answers to all Babel questions.
> >>>> Recourse to the language specific documentation is typically necessary,
> >>>> which is why it would be great if someone could find time to work up
> >>>> documentation for the 20 or so languages that still lack it :)
> >>>
> >>> Thanks for the clarification and that answers the question. This was a
> >>> specific header argument for R. Perhaps the manual could link to this
> >>> page?
> >>> - http://orgmode.org/worg/org-contrib/babel/languages.html
> >>>
> >>> Maybe with a diddy: "Some languages feature their own unique header
> >>> arguments. The above document only universal, system wide Babel header
> >>> arguments and one should consult the specific language page on Worg
> >>> for additional features."
> >>>
> >>> Just a thought.
> >>
> >> Hi John,
> >>
> >> Thanks for this thought, which is indeed reasonable.  I thought the
> >> manual might lack this structure, but when I went back to the
> >> manual I found that
> >> http://orgmode.org/manual/Specific-header-arguments.html#Specific-header-arguments
> >> has this at the bottom of the page: "Additional header arguments are
> >> defined on a language-specific basis, see Languages", where "Languages"
> >> is a link to another manual page, one with a table of supported
> >> languages and a link to the Worg page you cite.
> >>
> >
> > Wow. You see only what you look for. :embarrassed:
> >
> >> The language is a bit different than your proposal, but the path seems
> >> clear enough to me.
> >
> > Technically the path points to
> > http://orgmode.org/worg/org-contrib/babel/languages/; I'd point it to
> > http://orgmode.org/worg/org-contrib/babel/languages.html as it looks
> > cleaner vs. just looking at the directory of .html files. Either
> > way... the manual totally does it's job and I missed it!
> >
> > Thanks for bearing with me!
> > John
> >
> >>
> >> Of course, there is still the issue of the languages that lack
> >> language-specific documentation :)
> >>
> >> All the best,
> >> Tom
> >>
> >> --
> >> T.S. Dye & Colleagues, Archaeologists
> >> 735 Bishop St, Suite 315, Honolulu, HI 96813
> >> Tel: 808-529-0866, Fax: 808-529-0884
> >> http://www.tsdye.com
> 
> 
> >From 0438f0ae1e23321dbacd0666119205985959433e Mon Sep 17 00:00:00 2001
> From: Thomas Dye <tsd@tsdye.com>
> Date: Tue, 10 Jul 2012 07:12:13 -1000
> Subject: [PATCH] Changed babel languages link following a suggestion by John
>  Hendy
> 
> ---
>  doc/org.texi |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/doc/org.texi b/doc/org.texi
> index 922cbfb..c48242d 100644
> --- a/doc/org.texi
> +++ b/doc/org.texi
> @@ -12940,7 +12940,7 @@ Code blocks in the following languages are supported.
>  
>  Language-specific documentation is available for some languages.  If
>  available, it can be found at
> -@uref{http://orgmode.org/worg/org-contrib/babel/languages}.
> +@uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
>  
>  The @code{org-babel-load-languages} controls which languages are enabled for
>  evaluation (by default only @code{emacs-lisp} is enabled).  This variable can
> -- 
> 1.7.5.4
> 
>