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: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Peter Ruckdeschel
Sent: Friday, 7 November 2008 5:27 AM
To: r-devel@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
