[R] HTML translation problem in R-2.10.1

[Duncan Murdoch]

On 15/01/2010 6:24 AM, Jim Lemon wrote:
> On 01/15/2010 12:13 AM, Duncan Murdoch wrote:
>> On 14/01/2010 11:20 AM, Jim Lemon wrote:
>>> 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.
>> 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.
> 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.

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.

> 
> 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.

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

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