[R] Rd file processing suggestion - % sign in examples

[Duncan Murdoch]

On 11-04-19 2:26 AM, Peter Langfelder wrote:
 > Hi folks,
 >
 > I have come across a simple quirk that took me a long time to figure
 > out. The gist is that if I write, in the example section of an Rd
 > file, the line
 >
 > c = a %*% b
 >
 > what R will see when running the example is
 >
 > c = a
 >
 > since the % signs are apparently considered comment signs even in the
 > \examples section. The change from c = a %*% b to c = a can easily
 > make the example code fail with an error further down the line. The
 > thing is, if you take the code and copy-paste it into a standard R
 > session, the code will run correctly (which is what happened to me and
 > it took me several hours to figure this mystery out). The solution is
 > to escape the % signs by a backslash, i.e. to write c = a \%*\% b
 >
 > The suggestion is (of course) to make the Rd processor/parser not
 > consider % sign a comment sign in the examples section. Hopefully that
 > wouldn't be too difficult...

Unfortunately that is too difficult.  Comment processing in .Rd files is 
messy, because they mix two languages:  R and LaTeX-like markup. We do 
need markup in example sections, and % keeps its LaTeX-like meaning.
If it didn't, there would be two problems:  it would be impossible to 
enter comments that don't display, and the example section would have to 
be parsed differently from other sections involving code, which would 
make the parser (and the rules it implements) even messier.

This is documented behaviour, in Writing R Extensions and elsewhere, but 
I agree it's not entirely obvious.

Duncan Murdoch