[R-pkg-devel] Literal LaTeX Text in Function Arguments
biii m@iii@g oii de@@ey@ws
biii m@iii@g oii de@@ey@ws
Sat Aug 24 15:46:58 CEST 2019
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