[R-pkg-devel] Literal LaTeX Text in Function Arguments

[Duncan Murdoch]

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.

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/1338116767d90e8211533cb6e
> 7db5ef30368dc33/R/topic_long_table_header_footer.R#L20
> 
>   
> 
> Which yields:
> 
> https://github.com/billdenney/TopicLongTableR/blob/1338116767d90e8211533cb6e
> 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
>