[Rd] Two minor escaping issues using \preformatted{....} in Rd format

[Mark.Bravington at csiro.au]

Hi Peter

I've recently run into very similar phenomena, not just in \preformatted. After extensive experimentation, I've found some ugly but effective workarounds. The Rd problems can occur *after* either a backslash or a left brace; that's a necessary but not sufficient condition, as they only occur with certain following characters or sequences. For (one) example, interesting things happen if you try to output the string "\code" in certain parts of your documentation, whereas "\dode" is fine; I speculate that Rdconv may use global searches for "\code" which ignore context.

My ugly workarounds are as follows:

In verbatim-like modes (eg \preformatted, USAGE, EXAMPLES, and \code fragments), insert \link{} after a backslash or left brace.

In text-like modes, insert \enc{}{} after the backslash or left brace.

This seems to work very generally. AFAICS the insertions leave no trace in the final help products, but they are not strictly necessary in all cases; it does depend on the following character(s), as you've noted. I'm not 100% sure what all the dangerous following characters are.

The only problem with the verbatim-mode fix is that it will trigger a "missing link:" warning during RCMD CHECK. The missing link in question is empty, but doesn't cause any problem in the final documentation (text, html, or pdf). Based on recent experience, this is probably OK with the CRAN maintainers if you explain why, but in the longer term I guess it would be good if the fundamental conversion issues were addressed.

The absolutely simplest way to get things to behave for now, might be (i) for writers to use the above fixes, and (ii) for RCMD CHECK to not issue warnings for missing links *iff* the link is empty. Presumably this would not appeal to the pure of heart, but it would save anyone having to crawl through the bowels of Rdconv...

HTH

Mark

--
Mark Bravington
CSIRO Mathematical & Information Sciences
Marine Laboratory
Castray Esplanade
Hobart 7001
TAS

ph (+61) 3 6232 5118
fax (+61) 3 6232 5012
mob (+61) 438 315 623

-----Original Message-----
From: r-devel-bounces at r-project.org [mailto:r-devel-bounces at r-project.org] On Behalf Of Peter Ruckdeschel
Sent: Friday, 7 November 2008 5:27 AM
To: r-devel at r-project.org
Subject: [Rd] Two minor escaping issues using \preformatted{....} in Rd format

Hi r-devels,

I have two minor problems with special characters in Rd files when
used within a  \preformatted{} markup command:

------------------------------------------------------
1. issue: backslash + single brace
------------------------------------------------------

I would like to write "\\\}" to produce \} on output (documenting
the need to escape the brace once again before TeX-ing it);
this fails if there is no space between the second and third
backslash, but works if there is a space, but this produces
\ } then....

------------------------------------------------------
2. issue: backslash + percent sign
------------------------------------------------------

I would like to write "\\\\\%" to give a string argument \\% on
output; this is needed for documenting how to register special
operators to TeX package 'listings'.
Again this fails, while "\\\\ \%" works.

In neither case 1 or 2 the standard TeX trick to produce a
linebreak in the source without producing a space on output
helps, i.e.

\\%
\}

resp.
\\\\%
\%

both produce valid code [the resp. first % is read as a comment
sign] but also insert a non-intended space in the output.

Any idea how to circumvent this?
Best, Peter

______________________________________________
R-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel