> -----Ursprüngliche Nachricht----- > Von: Duncan Murdoch [mailto:murdoch.dun...@gmail.com] > Gesendet: Donnerstag, 16. September 2010 20:55 > An: Uwe Ligges > Cc: Janko Thyson; r-de...@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 > > > > > > ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel