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

[Robert Gentleman]

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