R devel - Mar 2009 - documentation questions

You've answered my question 2 about why the manual was in odd
order
> R CMD check was more of a check of the latex version of the files, not
> the final manual.
I was looking at the result of R CMD check, and it was in random order
(perhaps file date?), not just a different collation choice. Very odd.
I will cease worrying about what I might have "done wrong".

I omitted the important version information: R version 2.7.1 (2008-06-23)
on Linux.  

My other question was apparently unclear.  
  looking at the pdf output (because it is nicest to read) 
  I refer to it as "printed" because that's what I very often do
for any
substantial chunk of reading (>2 pages).  Easier on my eyes.  
  Talking only about the example section
  The question is what the result of \dontrun should be when producing a
product that is meant to be read by a human, and I will assume that this is
the primary target of the latex process.  I oject to the comment that it adds.

  I would much prefer that it not add extraneous comments to my examples.  I
do want the items bracketed by \dontrun to appear -- if I didn't think the
lines were useful I wouldn't have put them there.  Perhaps because I like
printed versions I like examples to show not just legal input, but give
feedback on what the code does; thus make it to the extent possible look
like a shapshot of a session and not just a set of legal input.  It is most
often output that I will have bracketed.  (wrt Gabor's comment, I would
rather
not turn it into a comment block; it would not look at all like that on
the screen).  
  There will be two levels to the response: argue that I really shouldn't
want to do this, and suggestions on how or how not to accomplish it.  Wrt
the first -- I need to consider this more.  You may convince me.  Wrt th
second:
   I don't know perl, but looked at Rdconv.pm.  It looks like changing the
line
to $text= undefine_command($text, "dontrun") would do what I want; but
that's
a guess, and it would only change the local behavior
   I'll have to pull down R-devel to understand the tools::: comment.
   Yes, verbatim sections in Tex are subtle.

  Thanks for the input.

I read
> For printing \dontrun should be a no-op.
to mean that it should produce no output, but I suspect you meant you 
wanted it to pass its argument through verbatim.

If we were continuing with the Rdconv.pm I would be suggesting adding 
some markup for that job (e.g. \verbdontrun), but as we are 
transitioning to another system adding anything right now is a lot of 
extra work.

To change Rdconv.pm for latex, the line is (in code2latex, l.2639 in 
R-devel)

     $text = replace_addnl_command($text, "dontrun",
 				  "## Not run: ", "## End(Not run)");

and AFAICS it would need to be

     $text = undefine_command($text, "dontrun");



On Thu, 5 Mar 2009, Terry Therneau wrote:
>
> You've answered my question 2 about why the manual was in odd order
>> R CMD check was more of a check of the latex version of the files, not
>> the final manual.
>
> I was looking at the result of R CMD check, and it was in random order
> (perhaps file date?), not just a different collation choice. Very odd.
> I will cease worrying about what I might have "done wrong".
>
> I omitted the important version information: R version 2.7.1 (2008-06-23)
> on Linux.
Looking more closely, it all depends how Perl lists directories: that 
could be in almost any order but I am seeing collated orders.
> My other question was apparently unclear.
>  looking at the pdf output (because it is nicest to read)
>  I refer to it as "printed" because that's what I very often
do for any
> substantial chunk of reading (>2 pages).  Easier on my eyes.
>  Talking only about the example section
>  The question is what the result of \dontrun should be when producing a
> product that is meant to be read by a human, and I will assume that this is
> the primary target of the latex process.  I oject to the comment that it
adds.
>
>  I would much prefer that it not add extraneous comments to my examples.  I
> do want the items bracketed by \dontrun to appear -- if I didn't think
the
> lines were useful I wouldn't have put them there.  Perhaps because I
like
> printed versions I like examples to show not just legal input, but give
> feedback on what the code does; thus make it to the extent possible look
> like a shapshot of a session and not just a set of legal input.  It is most
> often output that I will have bracketed.  (wrt Gabor's comment, I would
rather
> not turn it into a comment block; it would not look at all like that on
> the screen).
>  There will be two levels to the response: argue that I really
shouldn't
> want to do this, and suggestions on how or how not to accomplish it.  Wrt
> the first -- I need to consider this more.  You may convince me.  Wrt th
> second:
>   I don't know perl, but looked at Rdconv.pm.  It looks like changing
the line
> to $text= undefine_command($text, "dontrun") would do what I
want; but that's
> a guess, and it would only change the local behavior
>   I'll have to pull down R-devel to understand the tools::: comment.
>   Yes, verbatim sections in Tex are subtle.
>
>  Thanks for the input.
>
-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595