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
______________________________________________
R-help@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
