R devel - Nov 2008 - 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

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

On 06/11/2008 1:26 PM, Peter Ruckdeschel wrote:
> 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....
We have started some work on overhauling Rd processing.  Your comments 
on the early work would be welcome.  These might appear in 2.9.0, or 
maybe later, or maybe not at all.  You can read about them on 
developer.r-project.org.

In this case, what you want to write would be supported.  Mark's 
workaround would no longer work, because \link{} wouldn't be recognized 
within \preformatted.

> ------------------------------------------------------
> 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.
Those would probably still insert spaces under the proposed changes.

Duncan Murdoch
> Any idea how to circumvent this?
> Best, Peter
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel