HTML translation problem in R-2.10.1

Thu, Jan 14, 2010 4:59 PM

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.

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

HTML translation problem in R-2.10.1

Thread (5 messages)