Re: [R-pkg-devel] Note on winbuilder-develop
> Roy Mendelssohn
> on Tue, 23 Jul 2019 18:44:24 -0700 writes:
> Thanks, I was looking at the raw files, not the .Rd files.
> There are \keyword arguments in those file, will have to
> search to see why they are getting generated. -Roy
just to rub the obvious into everybody's face ;-) :-D
{ apology for any offence ! } :
If you'd use roxygen only initially and not anymore from then
on, but rather then would keep hand-editing nicely humanly
formatted man/*.Rd files,
you would never see this (and quite a few "similar") problems.
Martin Maechler
ETH Zurich and R Core
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Note on winbuilder-develop
On 24/07/2019 3:08 a.m., Martin Maechler wrote:
Roy Mendelssohn
on Tue, 23 Jul 2019 18:44:24 -0700 writes:
> Thanks, I was looking at the raw files, not the .Rd files.
> There are \keyword arguments in those file, will have to
> search to see why they are getting generated. -Roy
just to rub the obvious into everybody's face ;-) :-D
{ apology for any offence ! } :
If you'd use roxygen only initially and not anymore from then
on, but rather then would keep hand-editing nicely humanly
formatted man/*.Rd files,
you would never see this (and quite a few "similar") problems.
I don't think that's a great idea, unless the initial use is basically
no more than using prompt(). If you have comments in your source that
look like help text, and different help text in your Rd file, it's going
to lead to confusion. I don't think Roxygen is capable of updating your
source file comments when you edit your Rd file.
Duncan Murdoch
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Note on winbuilder-develop
> Duncan Murdoch
> on Wed, 24 Jul 2019 06:12:35 -0400 writes:
> On 24/07/2019 3:08 a.m., Martin Maechler wrote:
>>> Roy Mendelssohn
>>> on Tue, 23 Jul 2019 18:44:24 -0700 writes:
>>
>> > Thanks, I was looking at the raw files, not the .Rd files.
>> > There are \keyword arguments in those file, will have to
>> > search to see why they are getting generated. -Roy
>>
>> just to rub the obvious into everybody's face ;-) :-D
>> { apology for any offence ! } :
>>
>> If you'd use roxygen only initially and not anymore from then
>> on, but rather then would keep hand-editing nicely humanly
>> formatted man/*.Rd files,
>> you would never see this (and quite a few "similar") problems.
> I don't think that's a great idea, unless the initial use is basically
> no more than using prompt(). If you have comments in your source that
> look like help text, and different help text in your Rd file, it's going
> to lead to confusion. I don't think Roxygen is capable of updating your
> source file comments when you edit your Rd file.
> Duncan Murdoch
Ok, now you're triggering me ... probably I should have
refrained from that first e-mail ...
What I *meant* and failed to say more explicitly:
I would use roxygen comments for functions I write
"somewhere", possibly outside a package and I do *not* export (yet?)
when inside a package. Once I decide it should become an
exported function I use the roxygen stuff to create the very
first version of my help page *AND THEN* delete most of the
roxygen text comments (maybe leave 2 lines or so) and from then
on only use *.Rd files, which I keep nicely indented, and even *commented*
(is that possible at all inside roxygen?), add math
formula, add examples, enumeration lists, \describe{..} lists
etc in much more nicely readable form than wrapped inside the
"roxygen language" and never go back to using Roxygen there.
The same with the nicely human-annotated and sorted NAMESPACE
file.
As you know, R works from the NAMESPACE and man/*.Rd files
anyway, and so I don't add an extra translation layer .. and keep
*.Rd and NAMESPACE files that are both much nicer readable than
as part of roxygen comments blowing up the size of the *.R
source files.
By taking the *.Rd out of the source, I'm much less tempted to
keep the documentation minimal and almost unuseful, as I see it
in many packages built using Roxygen..
[... end of trigger]
Martin
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
[R-pkg-devel] devtools::check() shows a warning at the beginning, but not at the end
Hi, when I called check() on my package I got a warning at the beginning Updating plot.matrix documentation Warnung: roxygen2 requires Encoding: UTF-8 Warnung: @examples [/home/sigbert/syncthing/projekte/R/plot.matrix/R/as.cor.R#12]: mismatched braces or quotes but at the end it says ── R CMD check results ─── plot.matrix 1.3 Duration: 10.8s 0 errors ✔ | 0 warnings ✔ | 0 notes ✔ Is that okay? The warning actually was correct. Thanks Sigbert -- https://hu.berlin/sk https://hu.berlin/mmstat3 __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] devtools::check() shows a warning at the beginning, but not at the end
On 24/07/2019 5:30 a.m., Sigbert Klinke wrote: Hi, when I called check() on my package I got a warning at the beginning Updating plot.matrix documentation Warnung: roxygen2 requires Encoding: UTF-8 Warnung: @examples [/home/sigbert/syncthing/projekte/R/plot.matrix/R/as.cor.R#12]: mismatched braces or quotes but at the end it says ── R CMD check results ─── plot.matrix 1.3 Duration: 10.8s 0 errors ✔ | 0 warnings ✔ | 0 notes ✔ Is that okay? The warning actually was correct. Looks like a bug in devtools. It's probably looking for "Warning", and not recognizing the German translation. Duncan Murdoch __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] devtools::check() shows a warning at the beginning, but not at the end
Strictly speaking this is not a devtools bug, because the warning is not coming from `R CMD check`, but from `devtools::document()`, which rebuilds the documentation via roxygen2, before actually running `R CMD check`. Maybe `devtools::check()` should stop if `devtools::document()` throws a warning. Gabor On Wed, Jul 24, 2019 at 12:56 PM Duncan Murdoch wrote: > > On 24/07/2019 5:30 a.m., Sigbert Klinke wrote: > > Hi, > > > > when I called check() on my package I got a warning at the beginning > > > > Updating plot.matrix documentation > > Warnung: roxygen2 requires Encoding: UTF-8 > > Warnung: @examples > > [/home/sigbert/syncthing/projekte/R/plot.matrix/R/as.cor.R#12]: > > mismatched braces or quotes > > > > but at the end it says > > > > ── R CMD check results ─── plot.matrix 1.3 > > Duration: 10.8s > > > > 0 errors ✔ | 0 warnings ✔ | 0 notes ✔ > > > > Is that okay? The warning actually was correct. > > > > Looks like a bug in devtools. It's probably looking for "Warning", and > not recognizing the German translation. > > Duncan Murdoch > > __ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Note on winbuilder-develop
On 24/07/2019 6:54 a.m., Martin Maechler wrote:
Duncan Murdoch
on Wed, 24 Jul 2019 06:12:35 -0400 writes:
> On 24/07/2019 3:08 a.m., Martin Maechler wrote:
>>> Roy Mendelssohn
>>> on Tue, 23 Jul 2019 18:44:24 -0700 writes:
>>
>> > Thanks, I was looking at the raw files, not the .Rd files.
>> > There are \keyword arguments in those file, will have to
>> > search to see why they are getting generated. -Roy
>>
>> just to rub the obvious into everybody's face ;-) :-D
>> { apology for any offence ! } :
>>
>> If you'd use roxygen only initially and not anymore from then
>> on, but rather then would keep hand-editing nicely humanly
>> formatted man/*.Rd files,
>> you would never see this (and quite a few "similar") problems.
> I don't think that's a great idea, unless the initial use is basically
> no more than using prompt(). If you have comments in your source that
> look like help text, and different help text in your Rd file, it's going
> to lead to confusion. I don't think Roxygen is capable of updating your
> source file comments when you edit your Rd file.
> Duncan Murdoch
Ok, now you're triggering me ... probably I should have
refrained from that first e-mail ...
What I *meant* and failed to say more explicitly:
I would use roxygen comments for functions I write
"somewhere", possibly outside a package and I do *not* export (yet?)
when inside a package. Once I decide it should become an
exported function I use the roxygen stuff to create the very
first version of my help page *AND THEN* delete most of the
roxygen text comments (maybe leave 2 lines or so) and from then
on only use *.Rd files, which I keep nicely indented, and even *commented*
(is that possible at all inside roxygen?), add math
formula, add examples, enumeration lists, \describe{..} lists
etc in much more nicely readable form than wrapped inside the
"roxygen language" and never go back to using Roxygen there.
The same with the nicely human-annotated and sorted NAMESPACE
file.
To me that seems like too much work. If I'm writing something that
needs user comments, I would probably put it in a package, and use
prompt() to immediately start putting user documentation into an Rd
file. (There can also be programmer documentation that belongs in the
.R file.)
The disadvantage of my approach is that it's a little clunky to handle
changes to the function signatures. There's a function Rdpack::reprompt
that is supposed to update Rd files when the sources change; I should
probably adopt it as part of my workflow, but I haven't done so.
As you know, R works from the NAMESPACE and man/*.Rd files
anyway, and so I don't add an extra translation layer .. and keep
*.Rd and NAMESPACE files that are both much nicer readable than
as part of roxygen comments blowing up the size of the *.R
source files.
By taking the *.Rd out of the source, I'm much less tempted to
keep the documentation minimal and almost unuseful, as I see it
in many packages built using Roxygen..
I agree with you about the value of writing Rd files, and the cost (e.g.
incorrect Rd files with confusing error messages like Roy found) of
relying on Roxygen. But there are lots of people who disagree with us.
Duncan
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] devtools::check() shows a warning at the beginning, but not at the end
On 24/07/2019 8:00 a.m., Gábor Csárdi wrote: Strictly speaking this is not a devtools bug, because the warning is not coming from `R CMD check`, but from `devtools::document()`, which rebuilds the documentation via roxygen2, before actually running `R CMD check`. Maybe `devtools::check()` should stop if `devtools::document()` throws a warning. Or collect Roxygen issues and report on them at the end along with the R CMD check issues. Duncan Murdoch Gabor On Wed, Jul 24, 2019 at 12:56 PM Duncan Murdoch wrote: On 24/07/2019 5:30 a.m., Sigbert Klinke wrote: Hi, when I called check() on my package I got a warning at the beginning Updating plot.matrix documentation Warnung: roxygen2 requires Encoding: UTF-8 Warnung: @examples [/home/sigbert/syncthing/projekte/R/plot.matrix/R/as.cor.R#12]: mismatched braces or quotes but at the end it says ── R CMD check results ─── plot.matrix 1.3 Duration: 10.8s 0 errors ✔ | 0 warnings ✔ | 0 notes ✔ Is that okay? The warning actually was correct. Looks like a bug in devtools. It's probably looking for "Warning", and not recognizing the German translation. Duncan Murdoch __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] devtools::check() shows a warning at the beginning, but not at the end
The warning is from devtools::document() rather than R CMD check itself. You should still fix it though! On Wed, 24 Jul 2019 at 12:05, Sigbert Klinke wrote: > Hi, > > when I called check() on my package I got a warning at the beginning > > Updating plot.matrix documentation > Warnung: roxygen2 requires Encoding: UTF-8 > Warnung: @examples > [/home/sigbert/syncthing/projekte/R/plot.matrix/R/as.cor.R#12]: > mismatched braces or quotes > > but at the end it says > > ── R CMD check results ─── plot.matrix 1.3 > Duration: 10.8s > > 0 errors ✔ | 0 warnings ✔ | 0 notes ✔ > > Is that okay? The warning actually was correct. > > Thanks > > Sigbert > > -- > https://hu.berlin/sk > https://hu.berlin/mmstat3 > > __ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel > -- Sent from Gmail Mobile [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] devtools::check() shows a warning at the beginning, but not at the end
Oops! Sorry for the spam. On Wed, 24 Jul 2019 at 14:02, David Hugh-Jones wrote: > The warning is from devtools::document() rather than R CMD check itself. > You should still fix it though! > > > On Wed, 24 Jul 2019 at 12:05, Sigbert Klinke > wrote: > >> Hi, >> >> when I called check() on my package I got a warning at the beginning >> >> Updating plot.matrix documentation >> Warnung: roxygen2 requires Encoding: UTF-8 >> Warnung: @examples >> [/home/sigbert/syncthing/projekte/R/plot.matrix/R/as.cor.R#12]: >> mismatched braces or quotes >> >> but at the end it says >> >> ── R CMD check results ─── plot.matrix 1.3 >> Duration: 10.8s >> >> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔ >> >> Is that okay? The warning actually was correct. >> >> Thanks >> >> Sigbert >> >> -- >> https://hu.berlin/sk >> https://hu.berlin/mmstat3 >> >> __ >> R-package-devel@r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-package-devel >> > -- > Sent from Gmail Mobile > -- Sent from Gmail Mobile [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
