Re: [Rd] why is \alias{anRpackage} not mandatory?

From: Robert Gentleman <rgentlem_at_fhcrc.org>
Date: Tue, 07 Oct 2008 09:01:00 -0700

Hi,

   Not that I have time, but I suspect that there are not that many ways to document a package, probably only five or six variants in the wild and an overview function, with a name like packageOverview, would be relatively easy to write and would be able to extract all available information into a single place for a user.

An advantage of such an approach is that it can be updated, independent of what particular developers/packages do, leaving us free to choose our own manner of documentation. Also, one could easily imaging giving overviews of the class structure and functions + relationships (a thread on r-help) could be options, as could extracting doxygen type comments. But, as with all things R, someone needs to actually put it together - the tools are all there.

best wishes

   Robert

Duncan Murdoch wrote:
> On 07/10/2008 10:17 AM, hadley wickham wrote:

>>> This shows up in the HTML help system.  It would be better if it 
>>> showed up
>>> in all help formats, but there are other ways to do that, e.g. 
>>> creating an
>>> Rd help page pointing to those files.
>>
>> Or you can just link to them from your website.
>>
>> I don't think you'd argue with the statement that there's already too
>> many different ways to find R documentation.  

>
> I think that's a paraphrase of one of my earlier posts.
>
>> There are plenty of
>> hacks and work-arounds to jam different types of documentation in
>> different places, but they are just hacks and work-arounds.  My
>> feeling is that evolutionary modification of the documentation system
>> is only going to get us so far, and at some point the entire
>> foundations need to be rethought.

>
> I don't agree with this. Back in 2001 when this was first proposed it
> might have worked, but there's far too much inertia now to make a big
> change. Weren't you the one who objected to a requirement for a
> foo-package help topic? How would you like to rewrite all the help
> files for all of your packages? (I imagine not much. I'm certainly not
> going to do that for mine.)
>
> I think any change we make now needs to be incremental, but there's a
> tremendous amount of friction against anything at all, and very few
> offers of support to actually do the work.
>
> Here are things I'm currently working on, that I'd appreciate support for:
>
> - Formalizing the Rd format and writing a parser for it. (The current
> parser finds errors in about 2-5% of base package man files. Should it
> be more permissive? I would guess it will find more errors in
> contributed packages.) Can it make changes? I would really love to say
> that % is nothing special in an R code section in an Rd file, but there
> are lots of pages that use it as a comment, as it is documented to be.
>
> - Allowing macros in an Rd file. This will give a way to avoid
> duplication of information, will allow you to include an index of
> whatever sort of files you want, generated on the fly, and will slice
> bread if you write a macro for it.
>
> - Source level debugging support. Gabor mentioned that it's hard to
> debug Sweave files; this could help.
>
>
>> Of course, the problem is having enough time to do that, and then to
>> code up the solution!

>
> That's the main problem. I find the coding is much easier than the
> design, though. I can code on my own, but the design really needs
> careful thought and criticism. (It's easy to get shallow criticism; the
> hard thing is to get useful criticism.) That means at least two people
> need to find time to work together on the problem, and in my experience,
> that has almost never happened with any of the problems above. So I
> move very, very slowly on them.
>
> Duncan Murdoch
>
> ______________________________________________
> R-devel_at_r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
-- 
Robert Gentleman, PhD
Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M2-B876
PO Box 19024
Seattle, Washington 98109-1024
206-667-7700
rgentlem_at_fhcrc.org

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Tue 07 Oct 2008 - 16:13:30 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Tue 07 Oct 2008 - 17:30:18 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive