Re: [R-pkg-devel] Literal LaTeX Text in Function Arguments
Hi Georgi, Thank you for the detailed investigation! It looks like you've found the issue with the psub() call below. It looks like a more complex regexp, "(? gsub(pattern="(? Sent: Saturday, August 24, 2019 12:28 PM To: [email protected]; 'Duncan Murdoch' ; [email protected] Subject: RE: [R-pkg-devel] Literal LaTeX Text in Function Arguments 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 = "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: [email protected] [[email protected]] Sent: 24 August 2019 14:46 To: 'Duncan Murdoch'; Georgi Boshnakov; [email protected] 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_tab le_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 Sent: Saturday, August 24, 2019 8:37 AM To: [email protected]; 'Georgi Boshnakov' ; [email protected] 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., [email protected] 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 ne
Re: [R-pkg-devel] Literal LaTeX Text in Function Arguments
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 = "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: [email protected] [[email protected]]
Sent: 24 August 2019 14:46
To: 'Duncan Murdoch'; Georgi Boshnakov; [email protected]
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
Sent: Saturday, August 24, 2019 8:37 AM
To: [email protected]; 'Georgi Boshnakov' ;
[email protected]
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., [email protected] 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 par
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 Sent: Saturday, August 24, 2019 8:37 AM To: [email protected]; 'Georgi Boshnakov' ; [email protected] 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., [email protected] 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 >> Sent: Frida
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., [email protected] 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 Sent: Friday, August 23, 2019 11:27 AM To: [email protected]; [email protected] 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: [email protected] [mailto:[email protected]] Sent: 23 August 2019 15:27 To: Georgi Boshnakov; [email protected] 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,
Re: [R-pkg-devel] Literal LaTeX Text in Function Arguments
On 23/08/2019 1:33 p.m., [email protected] 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 Sent: Friday, August 23, 2019 11:27 AM To: [email protected]; [email protected] 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: [email protected] [mailto:[email protected]] Sent: 23 August 2019 15:27 To: Georgi Boshnakov; [email protected] 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'
Re: [R-pkg-devel] Literal LaTeX Text in Function Arguments
HI Bill,
I checked this as well, using the package you put on github for this purpose
(note that the link you gave didn't work for me).
I tried a few variants but the bottom line is that "\ldots" and "\dots" are
expanded even if the backslash is escaped.
It is a feature rather than a bug, see towards the bottom of p. 8 in parseRd
(https://developer.r-project.org/parseRd.pdf).
In R strings, macros starting with "\l" are expanded (this is how
\code{\link{sss}} works).
But '\dots' is also expanded and this seems undocumented. I now recall that I
have seen similar behaviour for "\dots" in R strings in the Examples section.
I tried some hacks, such as redefining the '\ldots' but they don't work, since
the Rd parser works recursively.
Georgi Boshnakov
From: [email protected] [[email protected]]
Sent: 23 August 2019 18:33
To: Georgi Boshnakov; [email protected]
Subject: RE: [R-pkg-devel] Literal LaTeX Text in Function Arguments
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.
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
Sent: Friday, August 23, 2019 11:27 AM
To: [email protected]; [email protected]
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: [email protected] [mailto:[email protected]]
Sent: 23 August 2019 15:27
To: Georgi Boshnakov; [email protected]
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 definiti
Re: [R-pkg-devel] Literal LaTeX Text in Function Arguments
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. 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 Sent: Friday, August 23, 2019 11:27 AM To: [email protected]; [email protected] 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: [email protected] [mailto:[email protected]] Sent: 23 August 2019 15:27 To: Georgi Boshnakov; [email protected] 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 Sent: Friday, August 23, 2019 9:52 AM To: [email protected]; [email protected] Subject: R
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: [email protected] [mailto:[email protected]] Sent: 23 August 2019 15:27 To: Georgi Boshnakov; [email protected] 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 Sent: Friday, August 23, 2019 9:52 AM To: [email protected]; [email protected] 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:[email protected]] On Behalf Of [email protected] Sent: 23 August 2019 04:15 To: [email protected] 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 ", below_col_names = "\\hline ", subsequent_page_notification = "\\ldots continued ", latex_header = NULL) Docs: function(x, col_names = NULL, above_col_names = "\\hline ", below_col_names = "\\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]] __ [email protected] mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel __ [email protected] mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
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
Sent: Friday, August 23, 2019 9:52 AM
To: [email protected]; [email protected]
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:[email protected]] On
Behalf Of [email protected]
Sent: 23 August 2019 04:15
To: [email protected]
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
",
below_col_names = "\\hline ",
subsequent_page_notification = "\\ldots continued
",
latex_header = NULL)
Docs: function(x, col_names = NULL, above_col_names = "\\hline
",
below_col_names = "\\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]]
__
[email protected] mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
__
[email protected] mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
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:[email protected]] On Behalf Of [email protected] Sent: 23 August 2019 04:15 To: [email protected] 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 ", below_col_names = "\\hline ", subsequent_page_notification = "\\ldots continued ", latex_header = NULL) Docs: function(x, col_names = NULL, above_col_names = "\\hline ", below_col_names = "\\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]] __ [email protected] mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel __ [email protected] mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
