Skip to content

HTML translation problem in R-2.10.1

5 messages · Duncan Murdoch, Jim Lemon

Duncan Murdoch
#
On 14/01/2010 11:20 AM, Jim Lemon wrote:
The help parsing is done in C now, and the conversion to output formats 
is done in R.  See the Rd2* functions in the tools package if you want 
to debug anything.

Duncan Murdoch
Jim Lemon
# 
Hi Core Team,
I received an email about a problem with the help on the plotrix 
package. Apparently the \link tags in the help pages were showing up as 
literal text. I couldn't see this problem, nor any problem with the Rd 
files. Since the plotrix package hasn't been built for a while, I 
rechecked, rebuilt and reinstalled it. Sure enough, the \link tags 
showed up as literal text in both text and HTML help. This may be 
peculiar to R-2.10.1 as I never installed 2.10.0. If it helps, the 
--no-latex tag wasn't recognized by the INSTALL command (although only 
the HTML help was apparently built).

As far as I can see, the previous behavior of translating \link{ into <a 
href="... and the following } into </a> has been lost. The \samp{ string 
is now translated to an HTML span tag whereas I think it used to be 
translated to a <code> tag and this may be where the problem lies.

I think this is all done in Perl, so I can't help with the debugging.

Jim

R version 2.10.1 (2009-12-14)
i686-pc-linux-gnu

locale:
  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
  [5] LC_MONETARY=C              LC_MESSAGES=en_US.UTF-8
  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
  [9] LC_ADDRESS=C               LC_TELEPHONE=C
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base

other attached packages:
[1] plotrix_2.7-2 prettyR_1.8

loaded via a namespace (and not attached):
[1] tools_2.10.1
Duncan Murdoch
#
On 15/01/2010 6:24 AM, Jim Lemon wrote:
The \samp{} macro is defined (in Writing R Extensions) as

\samp{text}
     Indicate text that is a literal example of a sequence of 
characters, entered verbatim. No wrapping or reformatting will occur. 
Displayed using typewriter font if possible.

In 2.8.x and 2.9.x, it said something similar, but was less explicit:

\samp{text}
     Indicate text that is a literal example of a sequence of characters.

The Perl converters in earlier versions may have processed \link macros 
within this, but I think that was an error.  This macro should be used 
to document things like Rd macros or other literal sequences of 
characters, without requiring escapes (or with minimal requirements for 
escapes).

Part of the problem with writing a grammar for Rd files is that usage 
was so irregular, so this looks like a case where I decided on something 
that was close to the documentation, but not so close to the existing 
implementation.
You don't want to use \code{} unless you are entering R code.  I don't 
think you've said exactly what your goal is:  is it just to get a 
typewriter font for text?  I'm not sure there's a way to do that, and it 
does seem like a reasonable thing to want to do, but the current styles 
don't support it.  We've got \emph, \bold, \strong, but no \texttt 
equivalent.  What would you use it for?

Duncan Murdoch
Jim Lemon
#
On 01/15/2010 12:13 AM, Duncan Murdoch wrote:
Thanks for the tip. You're talking my language now.

The problem is indeed with the \samp{} markup tag, as this is translated 
to define a <span> class "samp" that is supposed to change the font to 
"monospace" between the tags (it doesn't). I tried changing this to 
defining a style (not recommended, but...) and that didn't work, either. 
Fooled around with the R.css file, explicitly defining fontfamily as 
"Courier" doesn't work. None of the other classes defined as a font 
change to "monospace" work. <span> itself doesn't appear consider any 
text within it as literal, as manually entering the link within the 
<span> tags in the HTML page creates a valid link. As far as I can 
determine, the writeLink function doesn't get called for links within a 
\samp{} as there are no error messages but the link doesn't get written 
to the HTML file. My suspicion at the moment is that by the time the 
action reaches line 227 in Rd2HTML, the "\link" string is no longer 
there to recognize.

I can fix the problem by reverting to using \code{} _except_ where that 
markup includes a link. This gives the font change, but of course prints 
everything within the resulting <pre> tags literally. However, that 
produces an HTML page that looks okay and has the requested links. I 
suspect that this will not be a welcome fix, as I can still recall 
changing all the \code{} to \samp{} in my Rd files.

I wouldn't mind an opinion on a preferred direction before trying to 
find where the processing of \samp{} is going wrong.

Jim
Jim Lemon
# 
Hi everyone,
The "problem" was the result of my historical misbehavior of embedding 
links within certain font enhancements. This used to work, but no 
longer. Any of you package maintainers who find that your links are 
suddenly becoming literal text on the HTML help pages are likely to have 
the same problem. Solution - remove any \samp tags around the links. 
Thanks to Duncan who provided the necessary info.

New versions of the clinsig, crank, plotrix and prettyR packages will 
appear shortly.

Jim