How can I retain the initial white space in a line when writing Rd documentation?

Question

In conjunction with trying to find a solution for myself in regards to this question, I find myself plunged into trying to write valid Rd markup. What I want is to add a section named Raw Function Code and put the code of the function under it. I've achieved limited success in this regard by writing a script to modify the Rd files to include

\section{Raw Function Code}{\code{
# some piece of R script will eventally provide this part of the text
}}

However, even if I manually properly spaced text into the .Rd file (using either spaces or tabs), the initial white space of each line seems to get stripped away leaving an undesirable looking function. I've noticed that if I provide a starting character before the white space the white space is retained. However, I did not want to provide a starting character because I'd like people to be able to copy and paste directly from the produced PDF.

I have reviewed parseRd and I know there are three types of text LaTeX- like, R-like, and verbatim. I have tried to put my function code in \code and in \verb and neither seemed to yield the desired results. What can I do to hold onto my initial white space?

Littlejohn

Did you try \begin{verbatim} ... \end{verbatim} – Ingleside

\begin and \end are unknown macros when using R CMD Rd2pdf. Maybe I have to use Rdconv and then add my extra code in latex rather than Rd. It just seems odd that there wouldn't be a way to add indents to code. – Littlejohn

Answer 1

The \section macro contains LaTeX type of text, but as you want to write code, you could use \synopsis macro, i.e.

\synopsis
# some piece of R script will eventally provide this part of the text
} 

There is one problem with this though; you cannot give name to this section, it is automatically named as another usage section. Same thing could be achieved by using \examples macro, but now the name of the section is Examples, which is probably even more dubious (not to mention that you probably already have Examples section).

Cardboard

Wow that is frustrating. The \examples and \usage macros are exactly what I want. They are in the R-like mode. \synopsis is in the verbatim mode which is workable but sub-par. It seems like \Sexpr should be able to provide what I want but section? == sometimes... so who knows what that means. – Littlejohn

It looks like '\Sexpr' could work inside section, and with options eval=FALSE,results=rd and echo=TRUE it would do exactly what you want, but I could get it working properly... – Cardboard

It should work in theory. In practice, I can't get it to work. I've stumbled through 'stage' and 'results' options but haven't found a reliable combination. I can't tell if you are saying you were or were not able to get it working. If you were, please share the .Rd code as an answer. – Littlejohn

Sorry, typo in bad place :) Unfortunately I couldn't get it work either. – Cardboard

Apparently it needs some text in the section before the \Sexpr and results need to be verbatim... and then the prompt characters have to be banished... and then... oops, still no line breaks etc. – Littlejohn

This doesn't retain whitespace at the beginning of the line. – Coneflower

Answer 2

It isn't possible without modifying the usage or examples sections of your Rd code. See Hemmo's answer for a usable workaround. It produces text in the verbatim mode which is sub-optimal, but far better than nothing.

(This answer is set community Wiki in case this state of affairs changes. This result is current as of R-2.15.1)

Littlejohn

Answer 3

If you want a super hacky way to do it, you can use \Sexpr to make zero width characters and add spaces between them:

#' first line \cr
#'\Sexpr{"\u200B"} \Sexpr{"\u200B"} \Sexpr{"\u200B"} \Sexpr{"\u200B"} indented line

A warning however - your package will build fine, but R CMD CHECK will throw a fit.

Flooded