From xie at yihui.name  Wed Jan 31 16:43:53 2018
From: xie at yihui.name (Yihui Xie)
Date: Wed, 31 Jan 2018 09:43:53 -0600
Subject: [Rd] Best practices in developing package: From a single file
In-Reply-To: <FCD9A33C859ACC469587CB09DD5C6C7132024B84@GBLONXMB13.corp.amvescap.net>
References: <CAPtbhHwLXvdCX+1PJvEAyjWtcaVf=k4kL2fgXNhxLqfBhoJg-Q@mail.gmail.com>
 <1517329742.15543.15.camel@braverock.com>
 <aef83954-b118-6f8f-6d4f-d2a9758121cc@gmail.com>
 <CAO1zAVaHnOthsFc9DGbC2+otAhHJ7qRi4hUZrqk67NFwpr6osA@mail.gmail.com>
 <2d6d82a8-0dc3-0fbe-5b25-8c86c74a1aad@gmail.com>
 <CAO1zAVZGG33AUWUQ0Sbjaaqf2FSZ3JNsxzvdNHn9sBcYYDL7LQ@mail.gmail.com>
 <FCD9A33C859ACC469587CB09DD5C6C7132024B84@GBLONXMB13.corp.amvescap.net>
Message-ID: <CANROs4e4yHzjW4oDXFimYomSSchcCfLZjHFiUvMXTLakj-JQrQ@mail.gmail.com>

Similarly, I created this example a couple of years ago:
https://github.com/yihui/rlp which shows that you can create a package
from R Markdown documents (or any documents that knitr supports).
Basically you can start with an R Markdown document, and after
clicking a button in RStudio, you will get a full R package, with R
code, vignettes, and Rd (killing three birds with one stone). The
reason that you can get Rd is because of roxygen2.

I'm not interested in convincing Duncan of using roxygen (or
GIT/Github). It is fine that one loves or hates a tool. Just use tools
that make yourself comfortable. To me as a package developer, roxygen2
is indispensable (so are GIT/Github), and I use it in all my packages.
I had almost lost interest in developing R packages about 8 years ago
just because I found writing raw Rd extremely frustrating. Then
fortunately, roxygen was born, just in time.

Personally, it doesn't bother me if Duncan thinks roxygen-based
package documentations are typically of poor quality. I care a lot of
about documentation, and sometimes spend months after months on
documentation (Rd, vignettes, websites, and books). I'd very much like
to volunteer to have Duncan use any of my packages as examples of
"poor-quality roxygen-based documentation", and let's figure out why
they are poor (i.e., do we blame it on roxygen2 or myself?).

Regards,
Yihui
--
https://yihui.name


On Wed, Jan 31, 2018 at 8:51 AM, Pfaff, Bernhard Dr.
<Bernhard_Pfaff at fra.invesco.com> wrote:
> Dear All:
>
> stepping in late, but @Joris, if you would like to take 'from a single file' literally,
> have a look at:
>
>         https://github.com/bpfaff/lp4rp
>
> (lp4rp: literate programming for R packages);
>
> Cheers,
> Bernhard
>
> ps:  incidentally, within the noweb-file roxygen is employed.
>
> -----Urspr?ngliche Nachricht-----
> Von: R-devel [mailto:r-devel-bounces at r-project.org] Im Auftrag von Joris Meys
> Gesendet: Mittwoch, 31. Januar 2018 14:02
> An: Duncan Murdoch
> Cc: r-devel
> Betreff: [EXT] Re: [Rd] Best practices in developing package: From a single file
>
> On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <murdoch.duncan at gmail.com>
> wrote:
>
>> On 31/01/2018 6:33 AM, Joris Meys wrote:
>>
>> 3. given your criticism, I'd like your opinion on where I can improve
>> the
>>> documentation of https://github.com/CenterForStatistics-UGent/pim.
>>> I'm currently busy updating the help files for a next release on
>>> CRAN, so your input is more than welcome.
>>>
>>
>> After this invitation I sent some private comments to Joris.  I would
>> say his package does a pretty good job of documentation; it isn't the
>> kind of Roxygen-using package that I was complaining about.  So I will
>> say I have received an example of a Roxygen-using package that has
>> good help pages.
>>
>
> Thank you for the nice compliment and the valuable tips.
>
> --
> Joris Meys
> Statistical consultant
>
> Department of Data Analysis and Mathematical Modelling Ghent University Coupure Links 653, B-9000 Gent (Belgium) <https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>
>
> -----------
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> -------------------------------
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> *****************************************************************
> Confidentiality Note: The information contained in this ...{{dropped:10}}
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel



[Rd] Best practices in developing package: From a single file
Yihui Xie