[R-pkg-devel] Literal LaTeX Text in Function Arguments
Georgi Boshnakov
georg|@bo@hn@kov @end|ng |rom m@nche@ter@@c@uk
Sat Aug 24 18:28:20 CEST 2019
It seems that expansion of \ldots occurs in two different circumstances.
1) The Rd2XXX converters treat specially \ldots and \dots but in different ways. tools::Rd2latex() defines in its body texify(), which, when called with a piece of R code, starts by replacing \ldots and \dots with
x <- psub("\\\\[l]{0,1}dots", "...", as.character(x))
Similarly, Rd2ex(), defines a function remap() which does a similar thing. The 'html' and 'txt' renderers also treat specially \dots and \ldots but only in more restricted cases. I didn't find what 'R CMD check' does.
This might explain the differences between 'html' and 'text' on the one hand, and 'pdf' output on the other hand.
(as Duncan pointed out, he didn't see this in html).
But macros starting with '\l' seem to be expanded in R code in all formats, if the backslash is not escaped, example a) below illustrates this. I redefined '\ldots' to demonstrate that this is not due to the special treatment that literally replaces \ldots with '...' as above. I think this follows from the specification of Rd format p. 8 of the 'parseRd' document referenced in my previous email.
For illiustration, I added the following lines before the Usage section in Bill's file topic_long_table_header.Rd.
\renewcommand{\ldots}{Aaaargh }
\renewcommand{\lmydots}{Uuugh }
\renewcommand{\mydots}{this is mydots }
Here the Usage entry for the shown argument only is modified (with 3 backslashes)
topic_long_table_header(x, col_names = NULL,
(not changed)
subsequent_page_notification = "\\\ldots continued \\\lmydots \\\mydots",
(not changed)
)
In the pdf file we see
subsequent_page_notification = "\Aaaargh continued \Uuugh \\mydots"
\ldots and \lmydots are expanded but \mydots is not. I believe that \lmydots is expanded since it starts with 'l', see my previous email. In this case, 'R CMD check' gives an additional warning about the unescaped backslash:
...
subsequent_page_notification = "<unescaped bksl>Aaaargh continued \Uuugh \\mydots"
This seems to happen since an attempt is made later to parse \Aaaargh and \Uuugh. If the Rd entry in the Usage section contaiin only one backslash, as in
subsequent_page_notification = "\ldots continued \lmydots \\\mydots",
then we get in all renderings:
subsequent_page_notification = "Aaaargh continued Uuugh \\mydots"
'R CMD check' also shows this text (and complains, since it obviously is not as in the function deifnition,
b) With proper escaping (using 4, instead of 3 backslashes above) we get (in the pdf rendering):
subsequent_page_notification = "\... continued \\lmydots \\mydots"
\ldots is expanded but the other macros are not. Note that the expansion of \ldots here is due is due to the specific rendering for LaTeX, which replaces \\ldots by three dots (...), and doesn't use my Rd definition for \ldots, suggesting that this occurs at a different place.
Georgi Boshnakov
________________________________________
From: bill using denney.ws [bill using denney.ws]
Sent: 24 August 2019 14:46
To: 'Duncan Murdoch'; Georgi Boshnakov; r-package-devel using r-project.org
Subject: RE: [R-pkg-devel] Literal LaTeX Text in Function Arguments
Hi Duncan,
The original Rd generated by roxygen2 had 4 backslashes:
https://github.com/billdenney/TopicLongTableR/blob/master/man/topic_long_table_header.Rd#L9
That generated a similar issue but check showed "\..." (backslash then 3 dots) instead of what is shown in the 2 backslashes case when check showed just "...".
So, while I agree that 4 backslashes would make the most sense for the .Rd file, there is still an issue somewhere with that 4 backslashes case.
Thanks,
Bill
-----Original Message-----
From: Duncan Murdoch <murdoch.duncan using gmail.com>
Sent: Saturday, August 24, 2019 8:37 AM
To: bill using denney.ws; 'Georgi Boshnakov' <georgi.boshnakov using manchester.ac.uk>; r-package-devel using r-project.org
Subject: Re: [R-pkg-devel] Literal LaTeX Text in Function Arguments
On 24/08/2019 7:35 a.m., Duncan Murdoch wrote:
> On 23/08/2019 1:33 p.m., bill using denney.ws wrote:
>> Hi Georgi,
>>
>> Thanks for this pointer. My guess at this point is that I've found a
>> bug (or maybe a couple of bugs with 'utils::prompt()' and with the Rd
>> to help conversion), but let me know if you think otherwise.
>
> It's certainly not a bug in utils:prompt: that's never called except
> by the user.
Actually, that's wrong. utils::prompt() is generating bad code: you need to have 4 backslashes in order to display 2. It is just showing the string as it would be deparsed for display, it isn't modifying it so that it is appropriate as Rd source.
Duncan Murdoch
>
> It might be a bug in the .Rd parsing, but I don't think so, because
> I'm not seeing it when I write the .Rd file manually and view it in HTML.
>
> It's most likely a bug in the check code, because I am seeing the same
> "Codoc mismatches" error as you are. I'm also seeing it in the pdf
> display of the help page, but not in the HTML or text displays.
>
> Duncan Murdoch
>
>>
>> I just did that way, and the usage lines that were generated by
>> 'utils::prompt()' and copied into the docs are:
>>
>> topic_long_table_header(x, col_names = NULL,
>> above_col_names = "\\hline", below_col_names = "\\hline",
>> subsequent_page_notification = "\\ldots continued",
>> latex_header = NULL, verbatim = NULL)
>>
>> topic_long_table_footer(x, bottom_border = "\\hline",
>> bottom_all_pages = NULL, bottom_last_page = NULL,
>> subsequent_page_notification = "continued \\ldots",
>> verbatim = NULL)
>>
>> It is giving a very similar error with 'R CMD check' (outside devtools).
>> The escape of the backslashes appears to be needed, but "\\ldots"
>> continues to be translated into "...":
>>
>> Codoc mismatches from documentation object 'topic_long_table_header':
>> topic_long_table_header
>> Code: function(x, col_names = NULL, above_col_names = "\\hline",
>> below_col_names = "\\hline",
>> subsequent_page_notification = "\\ldots continued",
>> latex_header = NULL, verbatim = NULL)
>> Docs: function(x, col_names = NULL, above_col_names = "\hline",
>> below_col_names = "\hline",
>> subsequent_page_notification = "... continued",
>> latex_header = NULL, verbatim = NULL)
>> Mismatches in argument default values:
>> Name: 'above_col_names' Code: "\\hline" Docs: "\hline"
>> Name: 'below_col_names' Code: "\\hline" Docs: "\hline"
>> Name: 'subsequent_page_notification' Code: "\\ldots continued" Docs:
>> "... continued"
>> topic_long_table_footer
>> Code: function(x, bottom_border = "\\hline", bottom_all_pages = NULL,
>> bottom_last_page = NULL, subsequent_page_notification
>> = "continued \\ldots", verbatim = NULL)
>> Docs: function(x, bottom_border = "\hline", bottom_all_pages = NULL,
>> bottom_last_page = NULL, subsequent_page_notification
>> = "continued ...", verbatim = NULL)
>> Mismatches in argument default values:
>> Name: 'bottom_border' Code: "\\hline" Docs: "\hline"
>> Name: 'subsequent_page_notification' Code: "continued \\ldots" Docs:
>> "continued ..."
>>
>> Thanks,
>>
>> Bill
>>
>> -----Original Message-----
>> From: Georgi Boshnakov <georgi.boshnakov using manchester.ac.uk>
>> Sent: Friday, August 23, 2019 11:27 AM
>> To: bill using denney.ws; r-package-devel using r-project.org
>> Subject: RE: [R-pkg-devel] Literal LaTeX Text in Function Arguments
>>
>> Hi Bill,
>>
>> Sorry, I misunderstood the question.
>>
>> To check if the problem is with R's tools, run
>> 'utils::prompt(topic_long_table_header)" and see the usage section of
>> the generated file. Presumably, this should be the 'canonical way' to
>> write the usage entry for the function.
>> You can copy and paste it in the Rd file generated by roxygen2, then
>> run 'R CMD build' and 'R CMD check' (outside devtools).
>>
>> Georgi
>>
>>
>> -----Original Message-----
>> From: bill using denney.ws [mailto:bill using denney.ws]
>> Sent: 23 August 2019 15:27
>> To: Georgi Boshnakov; r-package-devel using r-project.org
>> Subject: RE: [R-pkg-devel] Literal LaTeX Text in Function Arguments
>>
>> Hi Georgi,
>>
>> I'm not trying to use it as part of my documentation, it is one of my
>> function arguments. I want the function argument to be displayed
>> correctly in the help, but it is not. I'm curious how I should
>> document the "subsequent_page_notification" function argument in Rd.
>>
>> Specifically, the actual function definition (R code) looks like:
>>
>> R code:
>> --------------
>> topic_long_table_header <- function(x,
>> col_names=NULL,
>> above_col_names="\\hline",
>> below_col_names="\\hline",
>>
>> subsequent_page_notification="\\ldots
>> continued",
>> latex_header=NULL) {
>> # The function body
>> }
>> --------------
>>
>> So, I'm not trying to use LaTeX in the .Rd file; I'm trying to use it
>> in R, and I'm then copying it into the .Rd with extra escaping for
>> the backslashes (well, roxygen2 is doing the extra escaping).
>>
>> Rd text
>> --------------
>> topic_long_table_header(x, col_names = NULL,
>> above_col_names = "\\\\hline", below_col_names = "\\\\hline",
>> subsequent_page_notification = "\\\\ldots continued",
>> latex_header = NULL)
>> --------------
>>
>> Thanks,
>>
>> Bill
>>
>> -----Original Message-----
>> From: Georgi Boshnakov <georgi.boshnakov using manchester.ac.uk>
>> Sent: Friday, August 23, 2019 9:52 AM
>> To: bill using denney.ws; r-package-devel using r-project.org
>> Subject: RE: [R-pkg-devel] Literal LaTeX Text in Function Arguments
>>
>> Rd is not LaTeX, although it resembles it. You should use only
>> markup described in WRE.
>> For example, \dots is for the use case you mention.
>>
>> Georgi Boshnakov
>>
>>
>>
>>
>>
>> -----Original Message-----
>> From: R-package-devel [mailto:r-package-devel-bounces using r-project.org]
>> On Behalf Of bill using denney.ws
>> Sent: 23 August 2019 04:15
>> To: r-package-devel using r-project.org
>> Subject: [R-pkg-devel] Literal LaTeX Text in Function Arguments
>>
>> Hello,
>>
>>
>>
>> Does anyone know how to include verbatim \ldots (and maybe other
>> LaTeX) in an .Rd file correctly?
>>
>>
>>
>> When LaTeX is in the default arguments for a function, the code is
>> interpreted which makes the documentation not match the default
>> formal arguments.
>>
>>
>>
>> An example is:
>>
>> https://github.com/billdenney/TopicLongTableR/blob/1338116767d90e8211
>> 533cb6e
>> 7db5ef30368dc33/R/topic_long_table_header_footer.R#L20
>>
>>
>>
>> Which yields:
>>
>> https://github.com/billdenney/TopicLongTableR/blob/1338116767d90e8211
>> 533cb6e
>> 7db5ef30368dc33/man/topic_long_table_header.Rd#L10
>>
>>
>>
>> Which gives the following warning with `devtools::check()`:
>>
>> ```
>>
>> checking for code/documentation mismatches ... WARNING
>>
>> Codoc mismatches from documentation object 'topic_long_table_header':
>>
>> topic_long_table_header
>>
>> Code: function(x, col_names = NULL, above_col_names = "\\hline
>> <file://hline> ",
>>
>> below_col_names = "\\hline <file://hline> ",
>>
>> subsequent_page_notification = "\\ldots continued
>> <file://ldots%20continued> ",
>>
>> latex_header = NULL)
>>
>> Docs: function(x, col_names = NULL, above_col_names = "\\hline
>> <file://hline> ",
>>
>> below_col_names = "\\hline <file://hline> ",
>>
>> subsequent_page_notification = "\... continued",
>>
>> latex_header = NULL)
>>
>> ```
>>
>>
>>
>> I'm not sure, but I think that the solution is to add more protection
>> to the \s when generating the roxygen or perhaps wrapping the
>> arguments in some form of verbatim block (if it's available).
>>
>>
>>
>> Thanks,
>>
>>
>>
>> Bill
>>
>>
>>
>> P.S. This is also discussed in
>> https://github.com/r-lib/roxygen2/issues/837
>> where it appears to be related to the conversion of .Rd to help files
>> not the roxygen step.
>>
>>
>>
>>
>> [[alternative HTML version deleted]]
>>
>> ______________________________________________
>> R-package-devel using r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
>> ______________________________________________
>> R-package-devel using r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
>
More information about the R-package-devel
mailing list