Guidance for preparing document with code

Guidance for preparing document with code

[SabreWolfy]

I'm using Org ~7.8 and would like to prepare a document for export to HTML
to make available to others to read. This document will contain heading,
text, etc., R code (for my reference) and the output of the R code. Where
should I look to learn how to do this in R? Org-babel? Is this literate
programming? I've read much about Org over the years, and I think I've
probably tried this already once before, but I'd like to know where to start
looking.

Re: Guidance for preparing document with code

[Thomas S. Dye]

Aloha SabreWolfy,

SabreWolfy <sabrewolfy@gmail.com> writes:

> I'm using Org ~7.8 and would like to prepare a document for export to HTML
> to make available to others to read. This document will contain heading,
> text, etc., R code (for my reference) and the output of the R code. Where
> should I look to learn how to do this in R? Org-babel? 

Org mode should do what you want pretty much out of the box.  Note that
the exporters all changed with Org 8, so you'll want to distinguish
between the old and new exporters if you look for information on line.

> Is this literate
> programming? 

I don't think so.  The end result of literate programming is typically a
computer program rather than a document.

> I've read much about Org over the years, and I think I've
> probably tried this already once before, but I'd like to know where to start
> looking.

For your R code blocks, see the :exports header argument.  It sounds
like you'll want to set that to :exports both so you can see both your R
code and its output in the html document.

Good luck!

hth,
Tom

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

Re: Guidance for preparing document with code

[Sebastien Vauban]

Hello,

Thomas S. Dye wrote:
> SabreWolfy <sabrewolfy-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>
>> I'm using Org ~7.8 and would like to prepare a document for export to HTML
>> to make available to others to read. This document will contain heading,
>> text, etc., R code (for my reference) and the output of the R code. Where
>> should I look to learn how to do this in R? Org-babel? 
>
> Org mode should do what you want pretty much out of the box.  Note that
> the exporters all changed with Org 8, so you'll want to distinguish
> between the old and new exporters if you look for information on line.
>
>> Is this literate programming?
>
> I don't think so.  The end result of literate programming is typically a
> computer program rather than a document.

Just for the sake of accuracy, I'd say that "the end result of literate
programming is typically both a computer program *and* its documentation".

Getting the code out of the mixed source is called "tangling", while
generating the documentation (which shows both the code and explains it at the
same time) is called "weaving".

For the rest, you've received all the needed information so far, I guess.

Little starter for your R code:

#+BEGIN_SRC R :results graphics :file testout.png
plot(1:10, (1:10)^2)
#+END_SRC

produces (when evaluated in the buffer):

#+results:
[[file:testout.png]]

Up to you to see whether you want to export (when generating the HTML
document) the code, its results, both or none, by setting correctly the
":exports" header argument.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Guidance for preparing document with code

[SabreWolfy]

Hi Sebastien,

Thanks for the explanation and the example, which I'm going to use to get me
started.

Re: Guidance for preparing document with code

[SabreWolfy]

Sebastien Vauban <sva-news@...> writes:

> Little starter for your R code:
> 
> #+BEGIN_SRC R :results graphics :file testout.png
> plot(1:10, (1:10)^2)
> #+END_SRC

<snip>

w00t! I exported a quick structured document, with text, code and the "png"
file as an HTML document. This is super-cool :) I should have figured out
how to this ages ago. Thanks for the example. And thanks to Carsten, /et
al./ too ;)

Re: Guidance for preparing document with code

[SabreWolfy]

Hi :)

Thomas S. Dye <tsd <at> tsdye.com> writes:

> Org mode should do what you want pretty much out of the box.  Note that
> the exporters all changed with Org 8, so you'll want to distinguish
> between the old and new exporters if you look for information on line.

I haven't upgraded to Org 8 yet, but I see a later reply in this threads
mentions that it's quite easy, so I might try that first, to benefit from
the new exporter.

> For your R code blocks, see the :exports header argument.  It sounds
> like you'll want to set that to :exports both so you can see both your R
> code and its output in the html document.

Noted; thanks.

Re: Guidance for preparing document with code

[Thorsten Jolitz]

SabreWolfy <sabrewolfy@gmail.com> writes:

> I'm using Org ~7.8 and would like to prepare a document for export to HTML
> to make available to others to read. This document will contain heading,
> text, etc., R code (for my reference) and the output of the R code. Where
> should I look to learn how to do this in R? Org-babel? Is this literate
> programming? I've read much about Org over the years, and I think I've
> probably tried this already once before, but I'd like to know where to start
> looking.

,----------------------------------------------------------------------------------------------------
| http://stackoverflow.com/questions/11931385/emacs-bernt-hansens-life-in-a-plaintext-sample-git-repo
`----------------------------------------------------------------------------------------------------

gives links to the html version and the org-file of a document that
demonstrates a lot of the fundamental stuff that can be done with
Org-mode, with very good explanations.

The Org manual:

,--------------------------------------------------------
| http://orgmode.org/manual/Working-With-Source-Code.html
`--------------------------------------------------------

and tutorials on Worg:

,----------------------------------------------------
| http://orgmode.org/worg/org-contrib/babel/uses.html
`----------------------------------------------------

give more explanations ..

-- 
cheers,
Thorsten

Re: Guidance for preparing document with code

[SabreWolfy]

Hi Thorsten,

Thanks for the links.

Re: Guidance for preparing document with code

[Nick Dokos]

SabreWolfy <sabrewolfy@gmail.com> writes:

> I'm using Org ~7.8 and would like to prepare a document for export to HTML
> to make available to others to read. This document will contain heading,
> text, etc., R code (for my reference) and the output of the R code. Where
> should I look to learn how to do this in R? Org-babel? Is this literate
> programming? I've read much about Org over the years, and I think I've
> probably tried this already once before, but I'd like to know where to start
> looking.
>

org-babel is the right tool. Getting the headers right might involve
some fiddling: there have been many question on the ML about those so
you can try searching, but if after some effort you are still running
into a wall, just post what you have, what you want to accomplish and
how your purported solution fails: there are lots of people able and
willing to help. The only thing to keep in mind is that the shorter the
example, the better: don't post your 100-page org file; extract the
example(s) that you want help with.

These are all "obvious" but I find that repetition of this sort (although
it might irk the lifers on the list) is useful.

If you are using the R code for your reference, and only presenting the
results, that's *not* literate programming: you don't have to worry
about the noweb stuff.

-- 
Nick

Re: Guidance for preparing document with code

[SabreWolfy]

Nick Dokos <ndokos <at> gmail.com> writes:

> org-babel is the right tool. Getting the headers right might involve
> some fiddling: there have been many question on the ML about those so
> you can try searching, but if after some effort you are still running
> into a wall, just post what you have, what you want to accomplish and
> how your purported solution fails: there are lots of people able and
> willing to help. The only thing to keep in mind is that the shorter the
> example, the better: don't post your 100-page org file; extract the
> example(s) that you want help with.

Thanks. Apologies -- I meant *headers* (ie: a structured/outline-type
document), not *headings*.

> If you are using the R code for your reference, and only presenting the
> results, that's *not* literate programming: you don't have to worry
> about the noweb stuff.
> 

I wanted to include explanatory text, the R code, then the output of the
code, all in the same document. The R code will not be relevant to the
reader, but I'd like it included and executed to produce output.

Re: Guidance for preparing document with code

[Nick Dokos]

SabreWolfy <sabrewolfy@gmail.com> writes:

> Nick Dokos <ndokos <at> gmail.com> writes:
>
>> org-babel is the right tool. Getting the headers right might involve
>> some fiddling: there have been many question on the ML about those so
>> you can try searching, but if after some effort you are still running
>> into a wall, just post what you have, what you want to accomplish and
>> how your purported solution fails: there are lots of people able and
>> willing to help. The only thing to keep in mind is that the shorter the
>> example, the better: don't post your 100-page org file; extract the
>> example(s) that you want help with.
>
> Thanks. Apologies -- I meant *headers* (ie: a structured/outline-type
> document), not *headings*.
>

I think you used the right terminology the first time: those are usually
referred to as ``headings''.

The ``headers'' I was referring to are the header arguments in a code
block. I should have said ``header arguments'' explicitly - see e.g.

(info "(org) Working with source code")

>> If you are using the R code for your reference, and only presenting the
>> results, that's *not* literate programming: you don't have to worry
>> about the noweb stuff.
>> 
>
> I wanted to include explanatory text, the R code, then the output of the
> code, all in the same document. The R code will not be relevant to the
> reader, but I'd like it included and executed to produce output.
>

You can do that with babel: the ":exports both" header argument allows
both code and results to be exported.

We can argue whether this is literate programming but it's probably not
a useful argument: it's not black and white, there is a continuous
spectrum. As Seb explained, literate programming is (usually) about
presenting a program (usually a *large* program) in logical pieces,
interleaving the explanations with program fragments and depending on
the system to a) "tangle" all the program fragments into a program that
can actually be run without any modifications and b) "weave" the code
fragments and explanations into a document (e.g. a book).

-- 
Nick

Re: Guidance for preparing document with code

[Marcin Borkowski]

Dnia 2013-05-29, o godz. 15:33:51
SabreWolfy <sabrewolfy@gmail.com> napisał(a):

> I'm using Org ~7.8 and would like to prepare a document for export to
> HTML to make available to others to read. This document will contain
> heading, text, etc., R code (for my reference) and the output of the
> R code. Where should I look to learn how to do this in R? Org-babel?
> Is this literate programming? I've read much about Org over the
> years, and I think I've probably tried this already once before, but
> I'd like to know where to start looking.
> 
> 

Just my two cents: some time ago I had a problem with Org (not the
exporter, it was MobileOrg), and I was advised to install the newest
Org (8.0).  I was a bit afraid, but it turned out that the installation
went /very/ smoothly.  And since the 8.0 has the new exporter, I'd
suggest you switch, too.  (I used Elpa, but I was told that installing
from git repo is as easy as that, too.)

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Guidance for preparing document with code

[SabreWolfy]

Hi Marcin,

Marcin Borkowski <mbork <at> wmi.amu.edu.pl> writes:

> Just my two cents: some time ago I had a problem with Org (not the
> exporter, it was MobileOrg), and I was advised to install the newest
> Org (8.0).  I was a bit afraid, but it turned out that the installation
> went /very/ smoothly.  And since the 8.0 has the new exporter, I'd
> suggest you switch, too.  (I used Elpa, but I was told that installing
> from git repo is as easy as that, too.)

I was holding off updating to Org 8, but I might do that first, as your
experience was a good one. My concern regarding updating was more related to
the long list of "gotchas" on the website about version 8 and functionality
changes.

Re: Guidance for preparing document with code

[Marcin Borkowski]

Dnia 2013-05-29, o godz. 17:30:23
SabreWolfy <sabrewolfy@gmail.com> napisał(a):

> Hi Marcin,
> 
> Marcin Borkowski <mbork <at> wmi.amu.edu.pl> writes:
> 
> > Just my two cents: some time ago I had a problem with Org (not the
> > exporter, it was MobileOrg), and I was advised to install the newest
> > Org (8.0).  I was a bit afraid, but it turned out that the
> > installation went /very/ smoothly.  And since the 8.0 has the new
> > exporter, I'd suggest you switch, too.  (I used Elpa, but I was
> > told that installing from git repo is as easy as that, too.)
> 
> I was holding off updating to Org 8, but I might do that first, as
> your experience was a good one. My concern regarding updating was
> more related to the long list of "gotchas" on the website about
> version 8 and functionality changes.

Well, there might be a few rough edges, but I guess that the quality of
the new exporter might overweigh them (I don't know for sure, I don't
use Org exporter /at all/).

Also, I started with updating my Emacs to 24.3, though it was probably
not strictly necessary - but it made using Elpa easier than with v23
(it was possible then, but in v24 it Just Works™ out of the box).

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University