a small suggestion for improving the building of packages

classic Classic list List threaded Threaded
18 messages Options
Reply | Threaded
Open this post in threaded view
|

a small suggestion for improving the building of packages

Kyle Matoba-3
All,

I just finished the process of build a package for the first time and found
it characteristically (for R) very straightforward and well documented.

Whenever I deal with open source software I always endeavor to finish the
task I have in mind, and upon completing this, I then revisit all of the
configurations, customizing as necessary to achieve my goals more fully.
 The ability to achieve some minimal level of functionality without the need
for much filling in of configuration files, etc., is, I feel, important to
not scaring off the less technically inclined such as myself.

Based on this heuristic, it is my understanding that a few small suggestions
could make building a warning-free package as easy as running
package.skeleton(), then R CMD check, R CMD build:

- Fill in default titles for each of the '*.Rd' files in /man
- Take out the tildes in the 'examples' section of the '*-package.Rd' main
documentation file for the package (it seems to confuse the latex compiler)
- Put the lines '~~ Optionally other standard keywords, one per line, from
file KEYWORDS in ~~
~~ the R documentation directory ~~' into the \references{} section, there
is presently a warning about all text needing to be in a section.

Thanks, as always, to everyone for their hard work to keep my statistical
computing free and easy.

Best,

Kyle

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Uwe Ligges-3


On 29.08.2010 22:34, Kyle Matoba wrote:

> All,
>
> I just finished the process of build a package for the first time and found
> it characteristically (for R) very straightforward and well documented.
>
> Whenever I deal with open source software I always endeavor to finish the
> task I have in mind, and upon completing this, I then revisit all of the
> configurations, customizing as necessary to achieve my goals more fully.
>   The ability to achieve some minimal level of functionality without the need
> for much filling in of configuration files, etc., is, I feel, important to
> not scaring off the less technically inclined such as myself.
>
> Based on this heuristic, it is my understanding that a few small suggestions
> could make building a warning-free package as easy as running
> package.skeleton(), then R CMD check, R CMD build:
>
> - Fill in default titles for each of the '*.Rd' files in /man
> - Take out the tildes in the 'examples' section of the '*-package.Rd' main
> documentation file for the package (it seems to confuse the latex compiler)
> - Put the lines '~~ Optionally other standard keywords, one per line, from
> file KEYWORDS in ~~
> ~~ the R documentation directory ~~' into the \references{} section, there
> is presently a warning about all text needing to be in a section.


Dear Kyle,

thanks for the suggestions. Actually, it is intended to generate
warnings / Errors in R CMD check: We want to force package developers to
document their packages probably. This way, package maintainers /
developers have to touch each Rd file and cannot use them as is in order
to pass the checks.

Best wishes,
uwe




> Thanks, as always, to everyone for their hard work to keep my statistical
> computing free and easy.
>
> Best,
>
> Kyle
>
> [[alternative HTML version deleted]]
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Liaw, Andy
From: Uwe Ligges

>
>
> On 29.08.2010 22:34, Kyle Matoba wrote:
> > All,
> >
> > I just finished the process of build a package for the
> first time and found
> > it characteristically (for R) very straightforward and well
> documented.
> >
> > Whenever I deal with open source software I always endeavor
> to finish the
> > task I have in mind, and upon completing this, I then
> revisit all of the
> > configurations, customizing as necessary to achieve my
> goals more fully.
> >   The ability to achieve some minimal level of
> functionality without the need
> > for much filling in of configuration files, etc., is, I
> feel, important to
> > not scaring off the less technically inclined such as myself.
> >
> > Based on this heuristic, it is my understanding that a few
> small suggestions
> > could make building a warning-free package as easy as running
> > package.skeleton(), then R CMD check, R CMD build:
> >
> > - Fill in default titles for each of the '*.Rd' files in /man
> > - Take out the tildes in the 'examples' section of the
> '*-package.Rd' main
> > documentation file for the package (it seems to confuse the
> latex compiler)
> > - Put the lines '~~ Optionally other standard keywords, one
> per line, from
> > file KEYWORDS in ~~
> > ~~ the R documentation directory ~~' into the \references{}
> section, there
> > is presently a warning about all text needing to be in a section.
>
>
> Dear Kyle,
>
> thanks for the suggestions. Actually, it is intended to generate
> warnings / Errors in R CMD check: We want to force package
> developers to
> document their packages probably. This way, package maintainers /
> developers have to touch each Rd file and cannot use them as
> is in order
> to pass the checks.

Or else it may be possible to have some malicious person write a script
that
automagically generate some large number of bogus packages and submit
them to CRAN...

Andy

 

> Best wishes,
> uwe
>
>
>
>
> > Thanks, as always, to everyone for their hard work to keep
> my statistical
> > computing free and easy.
> >
> > Best,
> >
> > Kyle
> >
> > [[alternative HTML version deleted]]
> >
> > ______________________________________________
> > [hidden email] mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
Notice:  This e-mail message, together with any attachme...{{dropped:11}}

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Peter Dalgaard-2

On Sep 15, 2010, at 17:01 , Liaw, Andy wrote:
>
> Or else it may be possible to have some malicious person write a script
> that
> automagically generate some large number of bogus packages and submit
> them to CRAN...
>
> Andy
>


Douglas Adams -
- There is a theory which states that if ever anybody discovers exactly what the Universe is for and why it is here, it will instantly disappear and be replaced by something even more bizarre and inexplicable. There is another theory which states that this has already happened.

--
Peter Dalgaard
Center for Statistics, Copenhagen Business School
Solbjerg Plads 3, 2000 Frederiksberg, Denmark
Phone: (+45)38153501
Email: [hidden email]  Priv: [hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Kyle Matoba-3
In reply to this post by Uwe Ligges-3
Uwe,

Yes, this makes good sense.  All I am saying is that it is somewhat out of
the "open-source, the user is smart and we should not _artificially force_
him or her to jump through some hoop".  I do not contend that packages
destined for CRAN should have anything but the fullest documentation
possible: somewhat in the spirit of other open-source projects R should
impose quite stringent requirements for potential contributors, but make it
as easy as possible for someone to play around on their own isolated
projects.

Keep up the good work.

Best,

Kyle


2010/9/15 Uwe Ligges <[hidden email]>

>
>
> On 29.08.2010 22:34, Kyle Matoba wrote:
>
>> All,
>>
>> I just finished the process of build a package for the first time and
>> found
>> it characteristically (for R) very straightforward and well documented.
>>
>> Whenever I deal with open source software I always endeavor to finish the
>> task I have in mind, and upon completing this, I then revisit all of the
>> configurations, customizing as necessary to achieve my goals more fully.
>>  The ability to achieve some minimal level of functionality without the
>> need
>> for much filling in of configuration files, etc., is, I feel, important to
>> not scaring off the less technically inclined such as myself.
>>
>> Based on this heuristic, it is my understanding that a few small
>> suggestions
>> could make building a warning-free package as easy as running
>> package.skeleton(), then R CMD check, R CMD build:
>>
>> - Fill in default titles for each of the '*.Rd' files in /man
>> - Take out the tildes in the 'examples' section of the '*-package.Rd' main
>> documentation file for the package (it seems to confuse the latex
>> compiler)
>> - Put the lines '~~ Optionally other standard keywords, one per line, from
>> file KEYWORDS in ~~
>> ~~ the R documentation directory ~~' into the \references{} section, there
>> is presently a warning about all text needing to be in a section.
>>
>
>
> Dear Kyle,
>
> thanks for the suggestions. Actually, it is intended to generate warnings /
> Errors in R CMD check: We want to force package developers to document their
> packages probably. This way, package maintainers / developers have to touch
> each Rd file and cannot use them as is in order to pass the checks.
>
> Best wishes,
> uwe
>
>
>
>
>  Thanks, as always, to everyone for their hard work to keep my statistical
>> computing free and easy.
>>
>> Best,
>>
>> Kyle
>>
>>        [[alternative HTML version deleted]]
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Kyle Matoba-3
In reply to this post by Liaw, Andy
Yes, well, anyone clever enough to do this will not be stopped by
automatically manipulating some text to fill in the minimal documentation
necessary to pass checks.


On Wed, Sep 15, 2010 at 8:01 AM, Liaw, Andy <[hidden email]> wrote:

> From: Uwe Ligges
>
> >
> >
> > On 29.08.2010 22:34, Kyle Matoba wrote:
> > > All,
> > >
> > > I just finished the process of build a package for the
> > first time and found
> > > it characteristically (for R) very straightforward and well
> > documented.
> > >
> > > Whenever I deal with open source software I always endeavor
> > to finish the
> > > task I have in mind, and upon completing this, I then
> > revisit all of the
> > > configurations, customizing as necessary to achieve my
> > goals more fully.
> > >   The ability to achieve some minimal level of
> > functionality without the need
> > > for much filling in of configuration files, etc., is, I
> > feel, important to
> > > not scaring off the less technically inclined such as myself.
> > >
> > > Based on this heuristic, it is my understanding that a few
> > small suggestions
> > > could make building a warning-free package as easy as running
> > > package.skeleton(), then R CMD check, R CMD build:
> > >
> > > - Fill in default titles for each of the '*.Rd' files in /man
> > > - Take out the tildes in the 'examples' section of the
> > '*-package.Rd' main
> > > documentation file for the package (it seems to confuse the
> > latex compiler)
> > > - Put the lines '~~ Optionally other standard keywords, one
> > per line, from
> > > file KEYWORDS in ~~
> > > ~~ the R documentation directory ~~' into the \references{}
> > section, there
> > > is presently a warning about all text needing to be in a section.
> >
> >
> > Dear Kyle,
> >
> > thanks for the suggestions. Actually, it is intended to generate
> > warnings / Errors in R CMD check: We want to force package
> > developers to
> > document their packages probably. This way, package maintainers /
> > developers have to touch each Rd file and cannot use them as
> > is in order
> > to pass the checks.
>
> Or else it may be possible to have some malicious person write a script
> that
> automagically generate some large number of bogus packages and submit
> them to CRAN...
>
> Andy
>
>
> > Best wishes,
> > uwe
> >
> >
> >
> >
> > > Thanks, as always, to everyone for their hard work to keep
> > my statistical
> > > computing free and easy.
> > >
> > > Best,
> > >
> > > Kyle
> > >
> > >     [[alternative HTML version deleted]]
> > >
> > > ______________________________________________
> > > [hidden email] mailing list
> > > https://stat.ethz.ch/mailman/listinfo/r-devel
> >
> > ______________________________________________
> > [hidden email] mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
> >
> Notice:  This e-mail message, together with any attach...{{dropped:16}}

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Marc Schwartz-3
In reply to this post by Peter Dalgaard-2
On Sep 15, 2010, at 10:14 AM, peter dalgaard wrote:

>
> On Sep 15, 2010, at 17:01 , Liaw, Andy wrote:
>>
>> Or else it may be possible to have some malicious person write a script
>> that
>> automagically generate some large number of bogus packages and submit
>> them to CRAN...
>>
>> Andy
>>
>
>
> Douglas Adams -
> - There is a theory which states that if ever anybody discovers exactly what the Universe is for and why it is here, it will instantly disappear and be replaced by something even more bizarre and inexplicable. There is another theory which states that this has already happened.


BTW, that "other" theory helps to explain some local politicians...  ;-)

Regards,

Marc Schwartz
http://www.wolframalpha.com/input/?i=what+is+the+meaning+of+life%3F

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Janko Thyson
In reply to this post by Kyle Matoba-3
> From: Uwe Ligges <ligges_at_statistik.tu-dortmund.de>
> Date: Wed, 15 Sep 2010 15:23:01 +0200
> On 29.08.2010 22:34, Kyle Matoba wrote:
> > All,
> >
> > I just finished the process of build a package for the first time and
> found
> > it characteristically (for R) very straightforward and well
> documented.
> >
> > Whenever I deal with open source software I always endeavor to finish
> the
> > task I have in mind, and upon completing this, I then revisit all of
> the
> > configurations, customizing as necessary to achieve my goals more
> fully.
> > The ability to achieve some minimal level of functionality without
> the
> need
> > for much filling in of configuration files, etc., is, I feel,
> important to
>
> > not scaring off the less technically inclined such as myself.
> >
> > Based on this heuristic, it is my understanding that a few small
> suggestions
> > could make building a warning-free package as easy as running
> > package.skeleton(), then R CMD check, R CMD build:
> >
> > - Fill in default titles for each of the '*.Rd' files in /man
> > - Take out the tildes in the 'examples' section of the '*-package.Rd'
> main
>
> > documentation file for the package (it seems to confuse the latex
> compiler)
> > - Put the lines '~~ Optionally other standard keywords, one per line,
> from
>
> > file KEYWORDS in ~~
> > ~~ the R documentation directory ~~' into the \references{} section,
> there
>
> > is presently a warning about all text needing to be in a section.
> Dear Kyle,
> thanks for the suggestions. Actually, it is intended to generate
> warnings /
> Errors in R CMD check: We want to force package developers to document
> their
> packages probably. This way, package maintainers / developers have to
> touch
> each Rd file and cannot use them as is in order to pass the checks.
> Best wishes,
> uwe

Dear Uwe,
in principle, I totally agree with your point of politely forcing developers
to write well documented packages. However, when you're trying to put
together a package, you (or at least I) never get it completely right on the
first, say, 20 tries ;-) Yet, by running package.skelleton() over and over
to keep track of changes you made during the process, you overwrite all Rd
files each time - including the ones that you might already have put a lot
of effort into. And delaying documentation to the very end of the process is
probably not the best idea either ;-) IMHO the community should favor the
approaches taken by packages such as roxygen or inlinedocs as at least it
provides some sort of direct synchronization between code and documentation.
Maybe one could agree on rejecting code that is missing roxygen or inlinedoc
code, which would ensure that code is documented properly. In fact, isn't
programming all about automating unnecessary manual procedures? I would
count starting from scratch with all help files time and time again to be
one of those unnecessary procedures. This time could better be invested in
increasing the package's functionality.

Best regards, my thanks go out to everyone as well,
Janko

> > Thanks, as always, to everyone for their hard work to keep my
> statistical
> > computing free and easy.
> >
> > Best,
> >
> > Kyle
> >
> > [[alternative HTML version deleted]]
> >
> > ______________________________________________
> > R-devel_at_r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Uwe Ligges-3


On 16.09.2010 20:18, Janko Thyson wrote:

>> From: Uwe Ligges<ligges_at_statistik.tu-dortmund.de>
>> Date: Wed, 15 Sep 2010 15:23:01 +0200
>> On 29.08.2010 22:34, Kyle Matoba wrote:
>>> All,
>>>
>>> I just finished the process of build a package for the first time and
>> found
>>> it characteristically (for R) very straightforward and well
>> documented.
>>>
>>> Whenever I deal with open source software I always endeavor to finish
>> the
>>> task I have in mind, and upon completing this, I then revisit all of
>> the
>>> configurations, customizing as necessary to achieve my goals more
>> fully.
>>> The ability to achieve some minimal level of functionality without
>> the
>> need
>>> for much filling in of configuration files, etc., is, I feel,
>> important to
>>
>>> not scaring off the less technically inclined such as myself.
>>>
>>> Based on this heuristic, it is my understanding that a few small
>> suggestions
>>> could make building a warning-free package as easy as running
>>> package.skeleton(), then R CMD check, R CMD build:
>>>
>>> - Fill in default titles for each of the '*.Rd' files in /man
>>> - Take out the tildes in the 'examples' section of the '*-package.Rd'
>> main
>>
>>> documentation file for the package (it seems to confuse the latex
>> compiler)
>>> - Put the lines '~~ Optionally other standard keywords, one per line,
>> from
>>
>>> file KEYWORDS in ~~
>>> ~~ the R documentation directory ~~' into the \references{} section,
>> there
>>
>>> is presently a warning about all text needing to be in a section.
>> Dear Kyle,
>> thanks for the suggestions. Actually, it is intended to generate
>> warnings /
>> Errors in R CMD check: We want to force package developers to document
>> their
>> packages probably. This way, package maintainers / developers have to
>> touch
>> each Rd file and cannot use them as is in order to pass the checks.
>> Best wishes,
>> uwe
>
> Dear Uwe,
> in principle, I totally agree with your point of politely forcing developers
> to write well documented packages. However, when you're trying to put
> together a package, you (or at least I) never get it completely right on the
> first, say, 20 tries ;-) Yet, by running package.skelleton() over and over
> to keep track of changes you made during the process, you overwrite all Rd
> files each time - including the ones that you might already have put a lot
> of effort into. And delaying documentation to the very end of the process is
> probably not the best idea either ;-) IMHO the community should favor the
> approaches taken by packages such as roxygen or inlinedocs as at least it
> provides some sort of direct synchronization between code and documentation.
> Maybe one could agree on rejecting code that is missing roxygen or inlinedoc
> code, which would ensure that code is documented properly. In fact, isn't
> programming all about automating unnecessary manual procedures? I would
> count starting from scratch with all help files time and time again to be
> one of those unnecessary procedures. This time could better be invested in
> increasing the package's functionality.

- I don't think package.skeleton overwrites files unless you ask for it.

- I think once you got started with your package, it is not required to
call package skeleton again. I tend to add files manually since I am
working on the package hierarchy itself using some editor...

- Last time I used package.skeleton is probably more than 2 years ago
(except for presentations in courses about package creation).

Best,
Uwe





>
> Best regards, my thanks go out to everyone as well,
> Janko
>
>>> Thanks, as always, to everyone for their hard work to keep my
>> statistical
>>> computing free and easy.
>>>
>>> Best,
>>>
>>> Kyle
>>>
>>> [[alternative HTML version deleted]]
>>>
>>> ______________________________________________
>>> R-devel_at_r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

William Dunlap
In reply to this post by Janko Thyson
> From: [hidden email]
> [mailto:[hidden email]] On Behalf Of Janko Thyson
> Sent: Thursday, September 16, 2010 11:19 AM
> To: r-devel@r-project. org
> Subject: Re: [Rd] a small suggestion for improving the
> building of packages
...

> Dear Uwe,
> in principle, I totally agree with your point of politely
> forcing developers
> to write well documented packages. However, when you're trying to put
> together a package, you (or at least I) never get it
> completely right on the
> first, say, 20 tries ;-) Yet, by running package.skelleton()
> over and over
> to keep track of changes you made during the process, you
> overwrite all Rd
> files each time - including the ones that you might already
> have put a lot
> of effort into.

Running package.skeleton more than once is destructive.
Perhaps it needs an update=TRUE/FALSE sort of option
to let you add functions and Rd templates.

When I start a package I don't use package.skeleton,
mainly because it won't make all the usual directories
that I expect to eventually use: src, data, inst, test
(or it is tests?), etc.  I'd rather that it made all
the usual directories (with the proper spelling) so
I could delete them if they ended up being empty.
Do other package writers use package.skeleton routinely?

I copy a template package directory, edit the template
DESCRIPTION file, copy my code into the appropriate
subdirectories, and run prompt(func, filename="pkg/man/func.Rd")
on each function or dataset.   The last step is a pain:
it would be nice if prompt had a dir= or destdir= argument
so that
   prompt(func, destdir="pkg/man")
would make the file "pkg/man/func.Rd".

Bill Dunlap
Spotfire, TIBCO Software
wdunlap tibco.com

> And delaying documentation to the very end of
> the process is
> probably not the best idea either ;-) IMHO the community
> should favor the
> approaches taken by packages such as roxygen or inlinedocs as
> at least it
> provides some sort of direct synchronization between code and
> documentation.
> Maybe one could agree on rejecting code that is missing
> roxygen or inlinedoc
> code, which would ensure that code is documented properly. In
> fact, isn't
> programming all about automating unnecessary manual
> procedures? I would
> count starting from scratch with all help files time and time
> again to be
> one of those unnecessary procedures. This time could better
> be invested in
> increasing the package's functionality.
>
> Best regards, my thanks go out to everyone as well,
> Janko
>
> > > Thanks, as always, to everyone for their hard work to keep my
> > statistical
> > > computing free and easy.
> > >
> > > Best,
> > >
> > > Kyle
> > >
> > > [[alternative HTML version deleted]]
> > >
> > > ______________________________________________
> > > R-devel_at_r-project.org mailing list
> > > https://stat.ethz.ch/mailman/listinfo/r-devel
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Duncan Murdoch-2
In reply to this post by Uwe Ligges-3
  On 16/09/2010 2:43 PM, Uwe Ligges wrote:

>
> On 16.09.2010 20:18, Janko Thyson wrote:
> >>  From: Uwe Ligges<ligges_at_statistik.tu-dortmund.de>
> >>  Date: Wed, 15 Sep 2010 15:23:01 +0200
> >>  On 29.08.2010 22:34, Kyle Matoba wrote:
> >>>  All,
> >>>
> >>>  I just finished the process of build a package for the first time and
> >>  found
> >>>  it characteristically (for R) very straightforward and well
> >>  documented.
> >>>
> >>>  Whenever I deal with open source software I always endeavor to finish
> >>  the
> >>>  task I have in mind, and upon completing this, I then revisit all of
> >>  the
> >>>  configurations, customizing as necessary to achieve my goals more
> >>  fully.
> >>>  The ability to achieve some minimal level of functionality without
> >>  the
> >>  need
> >>>  for much filling in of configuration files, etc., is, I feel,
> >>  important to
> >>
> >>>  not scaring off the less technically inclined such as myself.
> >>>
> >>>  Based on this heuristic, it is my understanding that a few small
> >>  suggestions
> >>>  could make building a warning-free package as easy as running
> >>>  package.skeleton(), then R CMD check, R CMD build:
> >>>
> >>>  - Fill in default titles for each of the '*.Rd' files in /man
> >>>  - Take out the tildes in the 'examples' section of the '*-package.Rd'
> >>  main
> >>
> >>>  documentation file for the package (it seems to confuse the latex
> >>  compiler)
> >>>  - Put the lines '~~ Optionally other standard keywords, one per line,
> >>  from
> >>
> >>>  file KEYWORDS in ~~
> >>>  ~~ the R documentation directory ~~' into the \references{} section,
> >>  there
> >>
> >>>  is presently a warning about all text needing to be in a section.
> >>  Dear Kyle,
> >>  thanks for the suggestions. Actually, it is intended to generate
> >>  warnings /
> >>  Errors in R CMD check: We want to force package developers to document
> >>  their
> >>  packages probably. This way, package maintainers / developers have to
> >>  touch
> >>  each Rd file and cannot use them as is in order to pass the checks.
> >>  Best wishes,
> >>  uwe
> >
> >  Dear Uwe,
> >  in principle, I totally agree with your point of politely forcing developers
> >  to write well documented packages. However, when you're trying to put
> >  together a package, you (or at least I) never get it completely right on the
> >  first, say, 20 tries ;-) Yet, by running package.skelleton() over and over
> >  to keep track of changes you made during the process, you overwrite all Rd
> >  files each time - including the ones that you might already have put a lot
> >  of effort into. And delaying documentation to the very end of the process is
> >  probably not the best idea either ;-) IMHO the community should favor the
> >  approaches taken by packages such as roxygen or inlinedocs as at least it
> >  provides some sort of direct synchronization between code and documentation.
> >  Maybe one could agree on rejecting code that is missing roxygen or inlinedoc
> >  code, which would ensure that code is documented properly. In fact, isn't
> >  programming all about automating unnecessary manual procedures? I would
> >  count starting from scratch with all help files time and time again to be
> >  one of those unnecessary procedures. This time could better be invested in
> >  increasing the package's functionality.
>
> - I don't think package.skeleton overwrites files unless you ask for it.
>
> - I think once you got started with your package, it is not required to
> call package skeleton again. I tend to add files manually since I am
> working on the package hierarchy itself using some editor...

Hi Uwe.  This message is mostly for Janko and others.

You can add them manually, but I would usually use prompt(), a generic
function that produces just one .Rd file.

It's really one of the prompt methods that package.skeleton is calling
to produce the bad man pages.  My own feeling is that package.skeleton
should produce a package that is installable, but it shouldn't pass "R
CMD check" unless there's some manual intervention to fill in the details.
I think that is the current state of affairs, but if we're producing
something that causes "R CMD build" or "R CMD INSTALL" to fail, please
let us know.

By the way, I don't think the title can be filled in automatically
unless a user has roxygen style documentation, so we don't.  But doesn't
the roxygen package do that?

Duncan Murdoch

> - Last time I used package.skeleton is probably more than 2 years ago
> (except for presentations in courses about package creation).
>
> Best,
> Uwe
>
>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Janko Thyson
In reply to this post by William Dunlap


> -----Ursprüngliche Nachricht-----
> Von: William Dunlap [mailto:[hidden email]]
> Gesendet: Donnerstag, 16. September 2010 20:45
> An: Janko Thyson; r-devel@r-project. org
> Betreff: RE: [Rd] a small suggestion for improving the building of
> packages
>
> > From: [hidden email]
> > [mailto:[hidden email]] On Behalf Of Janko Thyson
> > Sent: Thursday, September 16, 2010 11:19 AM
> > To: r-devel@r-project. org
> > Subject: Re: [Rd] a small suggestion for improving the
> > building of packages
> ...
> > Dear Uwe,
> > in principle, I totally agree with your point of politely
> > forcing developers
> > to write well documented packages. However, when you're trying to put
> > together a package, you (or at least I) never get it
> > completely right on the
> > first, say, 20 tries ;-) Yet, by running package.skelleton()
> > over and over
> > to keep track of changes you made during the process, you
> > overwrite all Rd
> > files each time - including the ones that you might already
> > have put a lot
> > of effort into.
>
> Running package.skeleton more than once is destructive.
> Perhaps it needs an update=TRUE/FALSE sort of option
> to let you add functions and Rd templates.

Uwe just pointed out that there is the argument 'force' that does that but
since it said 'If FALSE will not overwrite an existing directory' I somehow
didn't consider it to handle the update=TRUE/FALSE case. My bad.

>
> When I start a package I don't use package.skeleton,
> mainly because it won't make all the usual directories
> that I expect to eventually use: src, data, inst, test
> (or it is tests?), etc.  I'd rather that it made all
> the usual directories (with the proper spelling) so
> I could delete them if they ended up being empty.
> Do other package writers use package.skeleton routinely?

I agree. It would be nice if package.skeleton() would create a
'full-feature' skeleton removing empty directories during R CMD check.

>
> I copy a template package directory, edit the template
> DESCRIPTION file, copy my code into the appropriate
> subdirectories, and run prompt(func, filename="pkg/man/func.Rd")
> on each function or dataset.   The last step is a pain:
> it would be nice if prompt had a dir= or destdir= argument
> so that
>    prompt(func, destdir="pkg/man")
> would make the file "pkg/man/func.Rd".
>

Oh, never really considered 'prompt()' before. Thanks for the suggestion!
All the manuals always mention 'package.skeleton()'
But couldn't you realize your destdir feature by just building a wrapper
around 'prompt()' or using it in a sapply/lapply construct?
The last couple of days I played around with Roxygen and together with a
couple of utility-functions I managed to completely automate the whole
process from creating a full-feature skeleton, processing the Rds with
roxygenize() and running the full R CMD suite on the package. That way you
document your code right within the actual script which I think is great.

Best regards,
Janko

> Bill Dunlap
> Spotfire, TIBCO Software
> wdunlap tibco.com
>
> > And delaying documentation to the very end of
> > the process is
> > probably not the best idea either ;-) IMHO the community
> > should favor the
> > approaches taken by packages such as roxygen or inlinedocs as
> > at least it
> > provides some sort of direct synchronization between code and
> > documentation.
> > Maybe one could agree on rejecting code that is missing
> > roxygen or inlinedoc
> > code, which would ensure that code is documented properly. In
> > fact, isn't
> > programming all about automating unnecessary manual
> > procedures? I would
> > count starting from scratch with all help files time and time
> > again to be
> > one of those unnecessary procedures. This time could better
> > be invested in
> > increasing the package's functionality.
> >
> > Best regards, my thanks go out to everyone as well,
> > Janko
> >
> > > > Thanks, as always, to everyone for their hard work to keep my
> > > statistical
> > > > computing free and easy.
> > > >
> > > > Best,
> > > >
> > > > Kyle
> > > >
> > > > [[alternative HTML version deleted]]
> > > >
> > > > ______________________________________________
> > > > R-devel_at_r-project.org mailing list
> > > > https://stat.ethz.ch/mailman/listinfo/r-devel
> >
> > ______________________________________________
> > [hidden email] mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
> >

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Janko Thyson
In reply to this post by Duncan Murdoch-2
> -----Ursprüngliche Nachricht-----
> Von: Duncan Murdoch [mailto:[hidden email]]
> Gesendet: Donnerstag, 16. September 2010 20:55
> An: Uwe Ligges
> Cc: Janko Thyson; r-devel@r-project. org
> Betreff: Re: [Rd] a small suggestion for improving the building of
> packages
>
>   On 16/09/2010 2:43 PM, Uwe Ligges wrote:
> >
> > On 16.09.2010 20:18, Janko Thyson wrote:
> > >>  From: Uwe Ligges<ligges_at_statistik.tu-dortmund.de>
> > >>  Date: Wed, 15 Sep 2010 15:23:01 +0200
> > >>  On 29.08.2010 22:34, Kyle Matoba wrote:
> > >>>  All,
> > >>>
> > >>>  I just finished the process of build a package for the first
> time and
> > >>  found
> > >>>  it characteristically (for R) very straightforward and well
> > >>  documented.
> > >>>
> > >>>  Whenever I deal with open source software I always endeavor to
> finish
> > >>  the
> > >>>  task I have in mind, and upon completing this, I then revisit
> all of
> > >>  the
> > >>>  configurations, customizing as necessary to achieve my goals
> more
> > >>  fully.
> > >>>  The ability to achieve some minimal level of functionality
> without
> > >>  the
> > >>  need
> > >>>  for much filling in of configuration files, etc., is, I feel,
> > >>  important to
> > >>
> > >>>  not scaring off the less technically inclined such as myself.
> > >>>
> > >>>  Based on this heuristic, it is my understanding that a few small
> > >>  suggestions
> > >>>  could make building a warning-free package as easy as running
> > >>>  package.skeleton(), then R CMD check, R CMD build:
> > >>>
> > >>>  - Fill in default titles for each of the '*.Rd' files in /man
> > >>>  - Take out the tildes in the 'examples' section of the '*-
> package.Rd'
> > >>  main
> > >>
> > >>>  documentation file for the package (it seems to confuse the
> latex
> > >>  compiler)
> > >>>  - Put the lines '~~ Optionally other standard keywords, one per
> line,
> > >>  from
> > >>
> > >>>  file KEYWORDS in ~~
> > >>>  ~~ the R documentation directory ~~' into the \references{}
> section,
> > >>  there
> > >>
> > >>>  is presently a warning about all text needing to be in a
> section.
> > >>  Dear Kyle,
> > >>  thanks for the suggestions. Actually, it is intended to generate
> > >>  warnings /
> > >>  Errors in R CMD check: We want to force package developers to
> document
> > >>  their
> > >>  packages probably. This way, package maintainers / developers
> have to
> > >>  touch
> > >>  each Rd file and cannot use them as is in order to pass the
> checks.
> > >>  Best wishes,
> > >>  uwe
> > >
> > >  Dear Uwe,
> > >  in principle, I totally agree with your point of politely forcing
> developers
> > >  to write well documented packages. However, when you're trying to
> put
> > >  together a package, you (or at least I) never get it completely
> right on the
> > >  first, say, 20 tries ;-) Yet, by running package.skelleton() over
> and over
> > >  to keep track of changes you made during the process, you
> overwrite all Rd
> > >  files each time - including the ones that you might already have
> put a lot
> > >  of effort into. And delaying documentation to the very end of the
> process is
> > >  probably not the best idea either ;-) IMHO the community should
> favor the
> > >  approaches taken by packages such as roxygen or inlinedocs as at
> least it
> > >  provides some sort of direct synchronization between code and
> documentation.
> > >  Maybe one could agree on rejecting code that is missing roxygen or
> inlinedoc
> > >  code, which would ensure that code is documented properly. In
> fact, isn't
> > >  programming all about automating unnecessary manual procedures? I
> would
> > >  count starting from scratch with all help files time and time
> again to be
> > >  one of those unnecessary procedures. This time could better be
> invested in
> > >  increasing the package's functionality.
> >
> > - I don't think package.skeleton overwrites files unless you ask for
> it.
> >
> > - I think once you got started with your package, it is not required
> to
> > call package skeleton again. I tend to add files manually since I am
> > working on the package hierarchy itself using some editor...
>
> Hi Uwe.  This message is mostly for Janko and others.
>
> You can add them manually, but I would usually use prompt(), a generic
> function that produces just one .Rd file.
>
> It's really one of the prompt methods that package.skeleton is calling
> to produce the bad man pages.  My own feeling is that package.skeleton
> should produce a package that is installable, but it shouldn't pass "R
> CMD check" unless there's some manual intervention to fill in the
> details.
> I think that is the current state of affairs, but if we're producing
> something that causes "R CMD build" or "R CMD INSTALL" to fail, please
> let us know.
>
> By the way, I don't think the title can be filled in automatically
> unless a user has roxygen style documentation, so we don't.  But
> doesn't
> the roxygen package do that?
>

Yes it does but I ran into the problem of roxygen not being able to process
non-S4 and S4-style code/Rd-files correctly if all the files are in the same
directory, e.g. pkg/man.
I played around with 'use.Rd2' but either way I either ended up with empty
titles or this error message:
http://lists.r-forge.r-project.org/pipermail/roxygen-devel/2009-November/000
096.html.  

> Duncan Murdoch
>
> > - Last time I used package.skeleton is probably more than 2 years ago
> > (except for presentations in courses about package creation).
> >
> > Best,
> > Uwe
> >
> >
> >

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Duncan Murdoch-2
In reply to this post by William Dunlap
  On 16/09/2010 2:45 PM, William Dunlap wrote:

> >  From: [hidden email]
> >  [mailto:[hidden email]] On Behalf Of Janko Thyson
> >  Sent: Thursday, September 16, 2010 11:19 AM
> >  To: r-devel@r-project. org
> >  Subject: Re: [Rd] a small suggestion for improving the
> >  building of packages
> ...
> >  Dear Uwe,
> >  in principle, I totally agree with your point of politely
> >  forcing developers
> >  to write well documented packages. However, when you're trying to put
> >  together a package, you (or at least I) never get it
> >  completely right on the
> >  first, say, 20 tries ;-) Yet, by running package.skelleton()
> >  over and over
> >  to keep track of changes you made during the process, you
> >  overwrite all Rd
> >  files each time - including the ones that you might already
> >  have put a lot
> >  of effort into.
>
> Running package.skeleton more than once is destructive.
> Perhaps it needs an update=TRUE/FALSE sort of option
> to let you add functions and Rd templates.

Yes, that would be a nice addition.  I think good default behaviour
would be to only create new files if none of the same name already exist
(and warn that's what you did), but with an option to completely
overwrite what was there.

> When I start a package I don't use package.skeleton,
> mainly because it won't make all the usual directories
> that I expect to eventually use: src, data, inst, test
> (or it is tests?), etc.  I'd rather that it made all
> the usual directories (with the proper spelling) so
> I could delete them if they ended up being empty.
> Do other package writers use package.skeleton routinely?

I don't make a lot of new packages, but I do use it for quick little
ones.  I'm not so sure we should create all the directories:  it's
mainly aimed at beginners, who might find that intimidating.  Advanced
users can do what you do.  Perhaps an option (default off) to create
everything
would be a good compromise.

Duncan Murdoch

> I copy a template package directory, edit the template
> DESCRIPTION file, copy my code into the appropriate
> subdirectories, and run prompt(func, filename="pkg/man/func.Rd")
> on each function or dataset.   The last step is a pain:
> it would be nice if prompt had a dir= or destdir= argument
> so that
>     prompt(func, destdir="pkg/man")
> would make the file "pkg/man/func.Rd".
>
> Bill Dunlap
> Spotfire, TIBCO Software
> wdunlap tibco.com
>
> >  And delaying documentation to the very end of
> >  the process is
> >  probably not the best idea either ;-) IMHO the community
> >  should favor the
> >  approaches taken by packages such as roxygen or inlinedocs as
> >  at least it
> >  provides some sort of direct synchronization between code and
> >  documentation.
> >  Maybe one could agree on rejecting code that is missing
> >  roxygen or inlinedoc
> >  code, which would ensure that code is documented properly. In
> >  fact, isn't
> >  programming all about automating unnecessary manual
> >  procedures? I would
> >  count starting from scratch with all help files time and time
> >  again to be
> >  one of those unnecessary procedures. This time could better
> >  be invested in
> >  increasing the package's functionality.
> >
> >  Best regards, my thanks go out to everyone as well,
> >  Janko
> >
> >  >  >  Thanks, as always, to everyone for their hard work to keep my
> >  >  statistical
> >  >  >  computing free and easy.
> >  >  >
> >  >  >  Best,
> >  >  >
> >  >  >  Kyle
> >  >  >
> >  >  >  [[alternative HTML version deleted]]
> >  >  >
> >  >  >  ______________________________________________
> >  >  >  R-devel_at_r-project.org mailing list
> >  >  >  https://stat.ethz.ch/mailman/listinfo/r-devel
> >
> >  ______________________________________________
> >  [hidden email] mailing list
> >  https://stat.ethz.ch/mailman/listinfo/r-devel
> >
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Kevin Coombes
In reply to this post by Janko Thyson
  The phrase that caught my attention in your post is the one about
"running package.skeleton() over and over".  When I'm developing
packages, I never run it more than once.  And I usually delete a lot of
the files it produces (since I like to organize my functions in logical
batches and  not in separate files).  And once I think I have the file
structure organized, I put everything under version control and run
future development out that system.

Can you explain why you would need to re-run package.skeleton()? Is
there some use case that I am missing?

     Kevin

On 9/16/2010 1:18 PM, Janko Thyson wrote:

> Dear Uwe,
> in principle, I totally agree with your point of politely forcing developers
> to write well documented packages. However, when you're trying to put
> together a package, you (or at least I) never get it completely right on the
> first, say, 20 tries ;-) Yet, by running package.skelleton() over and over
> to keep track of changes you made during the process, you overwrite all Rd
> files each time - including the ones that you might already have put a lot
> of effort into. And delaying documentation to the very end of the process is
> probably not the best idea either ;-) IMHO the community should favor the
> approaches taken by packages such as roxygen or inlinedocs as at least it
> provides some sort of direct synchronization between code and documentation.
> Maybe one could agree on rejecting code that is missing roxygen or inlinedoc
> code, which would ensure that code is documented properly. In fact, isn't
> programming all about automating unnecessary manual procedures? I would
> count starting from scratch with all help files time and time again to be
> one of those unnecessary procedures. This time could better be invested in
> increasing the package's functionality.
>
> Best regards, my thanks go out to everyone as well,
> Janko

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Kasper Daniel Hansen-2
I agree with Kevin, I never run package.skeleton more than once.  But
one advantage to running it over and over again is if you change the
names or the ordering of function arguments.  That gets autowritten
and I could see that being convenient if you change those a lot (as
you sometime do in development)

Kasper

On Thu, Sep 16, 2010 at 5:17 PM, Kevin R. Coombes
<[hidden email]> wrote:

>  The phrase that caught my attention in your post is the one about "running
> package.skeleton() over and over".  When I'm developing packages, I never
> run it more than once.  And I usually delete a lot of the files it produces
> (since I like to organize my functions in logical batches and  not in
> separate files).  And once I think I have the file structure organized, I
> put everything under version control and run future development out that
> system.
>
> Can you explain why you would need to re-run package.skeleton()? Is there
> some use case that I am missing?
>
>    Kevin
>
> On 9/16/2010 1:18 PM, Janko Thyson wrote:
>>
>> Dear Uwe,
>> in principle, I totally agree with your point of politely forcing
>> developers
>> to write well documented packages. However, when you're trying to put
>> together a package, you (or at least I) never get it completely right on
>> the
>> first, say, 20 tries ;-) Yet, by running package.skelleton() over and over
>> to keep track of changes you made during the process, you overwrite all Rd
>> files each time - including the ones that you might already have put a lot
>> of effort into. And delaying documentation to the very end of the process
>> is
>> probably not the best idea either ;-) IMHO the community should favor the
>> approaches taken by packages such as roxygen or inlinedocs as at least it
>> provides some sort of direct synchronization between code and
>> documentation.
>> Maybe one could agree on rejecting code that is missing roxygen or
>> inlinedoc
>> code, which would ensure that code is documented properly. In fact, isn't
>> programming all about automating unnecessary manual procedures? I would
>> count starting from scratch with all help files time and time again to be
>> one of those unnecessary procedures. This time could better be invested in
>> increasing the package's functionality.
>>
>> Best regards, my thanks go out to everyone as well,
>> Janko
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

MarkBravington
FWIW, the package-building tools in the 'mvbutils' package-- see ?mvbutils.packaging.tools-- are supposed to alleviate much of this (provided of course you are willing to sign up to MY view of the universe...). Building a "legal" package out of existing code from scratch takes me less than 5 minutes, I never have to write a line of Rd or call package.skeleton() or remember the syntax of NAMESPACE files etc, and if I don't want to write any doco myself yet I don't have to.  Plus,
once I've built the package the first time, I can continue to work on it "live", without needing to unload/rebuild/reinstall all the time. The modus operandi is to work from a "task package folder"-- a level above/before the formal source-package layout-- which is the basis for (i) automatically generating the source package, and (ii) updating the installed package.

WRTO some of the points in the discussion already:  
 
 - Using fixr( myfunc, new.doc=T) is a bit like 'prompt'. It will add "legal" documentation to your function 'myfunc'-- ie it should pass RCMD CHECK. (As per an earlier post, this is "automatically manipulating some text to fill in the minimal documentation necessary to pass checks"). Of course, it still won't be much use to human beings unless you take the trouble to edit it. Having said that, I've come across some packages on CRAN with documentation that is little better...

 - Documentation is in plain-text that is automatically converted to Rd format later. Even if your plain-text is "wrong", it should still emerge as "legal" Rd & help files.

 - It's subsequently up to you to keep the doco in synch with any changes you make to the function itself, but at least the code & documentation for a function live next to each other in the same text file, so you are confronted with the one whenever you change the other.

 - You can work "live" on your package while it's loaded, and all changes/additions to the code and documentation are instantly reflected. [I know I said this already, but it bears repeating :)]

R 2.12 has changed the structure of installed packages (specifically, where DLLs live), and I haven't had time to tweak mvbutils accordingly-- hopefully I will find some time to sort it out before the release of 2.12.

This email may not excite much interest because-- unlike some of the other writers-- I personally found the R package creation process to be rather horrendous; it required me to learn a whole lot of very specific things that inevitably were forgotten by the next time I had to do it. In fact, it was enough to put me off writing documentation or proper packages for a long time. Now that I have an easy-to-use system in place, I've been much better about writing documentation and distributing mini-packages to colleagues.

Mark

--
Mark Bravington
CSIRO Mathematical & Information Sciences
Marine Laboratory
Castray Esplanade
Hobart 7001
TAS

ph (+61) 3 6232 5118
fax (+61) 3 6232 5012
mob (+61) 438 315 623

Kasper Daniel Hansen wrote:

> I agree with Kevin, I never run package.skeleton more than once.  But
> one advantage to running it over and over again is if you change the
> names or the ordering of function arguments.  That gets autowritten
> and I could see that being convenient if you change those a lot (as
> you sometime do in development)    
>
> Kasper
>
> On Thu, Sep 16, 2010 at 5:17 PM, Kevin R. Coombes
> <[hidden email]> wrote:
>>  The phrase that caught my attention in your post is the one about
>> "running package.skeleton() over and over".  When I'm developing
>> packages, I never run it more than once.  And I usually delete a lot
>> of the files it produces (since I like to organize my functions in
>> logical batches and  not in separate files).  And once I think I
>> have the file structure organized, I put everything under version
>> control and run future development out that system.
>>
>> Can you explain why you would need to re-run package.skeleton()? Is
>> there some use case that I am missing?
>>
>>    Kevin
>>
>> On 9/16/2010 1:18 PM, Janko Thyson wrote:
>>>
>>> Dear Uwe,
>>> in principle, I totally agree with your point of politely forcing
>>> developers to write well documented packages. However, when you're
>>> trying to put together a package, you (or at least I) never get it
>>> completely right on the first, say, 20 tries ;-) Yet, by running
>>> package.skelleton() over and over to keep track of changes you made
>>> during the process, you overwrite all Rd files each time - including
>>> the ones that you might already have put a lot of effort into. And
>>> delaying documentation to the very end of the process is probably
>>> not the best idea either ;-) IMHO the community should favor the
>>> approaches taken by packages such as roxygen or inlinedocs as at
>>> least it provides some sort of direct synchronization between code
>>> and documentation. Maybe one could agree on rejecting code that is
>>> missing roxygen or inlinedoc code, which would ensure that code is
>>> documented properly. In fact, isn't programming all about
>>> automating unnecessary manual procedures? I would count starting
>>> from scratch with all help files time and time again to be one of
>>> those unnecessary procedures. This time could better be invested in
>>> increasing the package's functionality.
>>>
>>> Best regards, my thanks go out to everyone as well, Janko
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: a small suggestion for improving the building of packages

Janko Thyson
> -----Ursprüngliche Nachricht-----
> Von: [hidden email] [mailto:[hidden email]]
> Gesendet: Freitag, 17. September 2010 01:36
> An: [hidden email]; [hidden email]
> Cc: [hidden email]; [hidden email]
> Betreff: RE: [Rd] a small suggestion for improving the building of
> packages
>
> FWIW, the package-building tools in the 'mvbutils' package-- see
> ?mvbutils.packaging.tools-- are supposed to alleviate much of this
> (provided of course you are willing to sign up to MY view of the
> universe...). Building a "legal" package out of existing code from
> scratch takes me less than 5 minutes, I never have to write a line of
> Rd or call package.skeleton() or remember the syntax of NAMESPACE files
> etc, and if I don't want to write any doco myself yet I don't have to.
> Plus,
> once I've built the package the first time, I can continue to work on
> it "live", without needing to unload/rebuild/reinstall all the time.
> The modus operandi is to work from a "task package folder"-- a level
> above/before the formal source-package layout-- which is the basis for
> (i) automatically generating the source package, and (ii) updating the
> installed package.

Wow, that sounds cool! I also tried to come up with a framework that puts
the focus on coding functionality and not on tediously manipulating things
in order to end up with an actual package time and time again. Thanks for
mentioning that package!
 

> WRTO some of the points in the discussion already:
>
>  - Using fixr( myfunc, new.doc=T) is a bit like 'prompt'. It will add
> "legal" documentation to your function 'myfunc'-- ie it should pass
> RCMD CHECK. (As per an earlier post, this is "automatically
> manipulating some text to fill in the minimal documentation necessary
> to pass checks"). Of course, it still won't be much use to human beings
> unless you take the trouble to edit it. Having said that, I've come
> across some packages on CRAN with documentation that is little
> better...
>
>  - Documentation is in plain-text that is automatically converted to Rd
> format later. Even if your plain-text is "wrong", it should still
> emerge as "legal" Rd & help files.
>
>  - It's subsequently up to you to keep the doco in synch with any
> changes you make to the function itself, but at least the code &
> documentation for a function live next to each other in the same text
> file, so you are confronted with the one whenever you change the other.
>
>  - You can work "live" on your package while it's loaded, and all
> changes/additions to the code and documentation are instantly
> reflected. [I know I said this already, but it bears repeating :)]
>
> R 2.12 has changed the structure of installed packages (specifically,
> where DLLs live), and I haven't had time to tweak mvbutils accordingly-
> - hopefully I will find some time to sort it out before the release of
> 2.12.
>
> This email may not excite much interest because-- unlike some of the
> other writers-- I personally found the R package creation process to be
> rather horrendous; it required me to learn a whole lot of very specific
> things that inevitably were forgotten by the next time I had to do it.
> In fact, it was enough to put me off writing documentation or proper
> packages for a long time. Now that I have an easy-to-use system in
> place, I've been much better about writing documentation and
> distributing mini-packages to colleagues.

That TOTALLY reflects my experiences so far with building packages. I can
see that this is a piece of cake for experienced developers that already can
visualize the complete layout of their package structure in their mind and
thus don't need to change a lot during the actual development. But for me
it's still a rather incremental and tentative process (I regard facilitating
this to be one of the key advantages of R) that involves changing function
and/or argument names and their order quite often. That's also why I used
package.skeleton() numerous times to reflect the changed structure in the
Rd-files. Thanks a lot for all the hints so far on how to do this
differently. Yet, if we would roughly separate developers into cracks and
beginners, it would really be great to have such an 'easy-to-use system'
(e.g. mvbutils or an upgraded version of package.skeleton()) available for
the beginners, as part of the base distribution.

> Mark
>
> --
> Mark Bravington
> CSIRO Mathematical & Information Sciences
> Marine Laboratory
> Castray Esplanade
> Hobart 7001
> TAS
>
> ph (+61) 3 6232 5118
> fax (+61) 3 6232 5012
> mob (+61) 438 315 623
>
> Kasper Daniel Hansen wrote:
> > I agree with Kevin, I never run package.skeleton more than once.  But
> > one advantage to running it over and over again is if you change the
> > names or the ordering of function arguments.  That gets autowritten
> > and I could see that being convenient if you change those a lot (as
> > you sometime do in development)
> >
> > Kasper
> >
> > On Thu, Sep 16, 2010 at 5:17 PM, Kevin R. Coombes
> > <[hidden email]> wrote:
> >>  The phrase that caught my attention in your post is the one about
> >> "running package.skeleton() over and over".  When I'm developing
> >> packages, I never run it more than once.  And I usually delete a lot
> >> of the files it produces (since I like to organize my functions in
> >> logical batches and  not in separate files).  And once I think I
> >> have the file structure organized, I put everything under version
> >> control and run future development out that system.
> >>
> >> Can you explain why you would need to re-run package.skeleton()? Is
> >> there some use case that I am missing?
> >>
> >>    Kevin
> >>
> >> On 9/16/2010 1:18 PM, Janko Thyson wrote:
> >>>
> >>> Dear Uwe,
> >>> in principle, I totally agree with your point of politely forcing
> >>> developers to write well documented packages. However, when you're
> >>> trying to put together a package, you (or at least I) never get it
> >>> completely right on the first, say, 20 tries ;-) Yet, by running
> >>> package.skelleton() over and over to keep track of changes you made
> >>> during the process, you overwrite all Rd files each time -
> including
> >>> the ones that you might already have put a lot of effort into. And
> >>> delaying documentation to the very end of the process is probably
> >>> not the best idea either ;-) IMHO the community should favor the
> >>> approaches taken by packages such as roxygen or inlinedocs as at
> >>> least it provides some sort of direct synchronization between code
> >>> and documentation. Maybe one could agree on rejecting code that is
> >>> missing roxygen or inlinedoc code, which would ensure that code is
> >>> documented properly. In fact, isn't programming all about
> >>> automating unnecessary manual procedures? I would count starting
> >>> from scratch with all help files time and time again to be one of
> >>> those unnecessary procedures. This time could better be invested in
> >>> increasing the package's functionality.
> >>>
> >>> Best regards, my thanks go out to everyone as well, Janko
> >>
> >> ______________________________________________
> >> [hidden email] mailing list
> >> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>
> >
> > ______________________________________________
> > [hidden email] mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel