From rgentlem at fhcrc.org  Tue Oct  7 18:01:00 2008
From: rgentlem at fhcrc.org (Robert Gentleman)
Date: Tue, 07 Oct 2008 09:01:00 -0700
Subject: [Rd] why is \alias{anRpackage} not mandatory?
In-Reply-To: <48EB76DF.1040709@stats.uwo.ca>
References: <48E9DE58.6070303@tu-dresden.de>
	<48E9E9E3.90905@stats.uwo.ca>		<48E9FF28.6060207@tu-dresden.de>		<f8e6ff050810060559j19623c5ew8f8e3f47811088c0@mail.gmail.com>		<48EA15B5.8020800@tu-dresden.de>		<f8e6ff050810060655p25baba3bw6ab54af0ef35acfa@mail.gmail.com>		<48EA1F2E.1060207@stats.uwo.ca>		<971536df0810070611y2c31e014rf6056c763e886686@mail.gmail.com>		<48EB6820.1000502@stats.uwo.ca>	<f8e6ff050810070717w53d62eebgf4d25d76a0aa0c90@mail.gmail.com>
	<48EB76DF.1040709@stats.uwo.ca>
Message-ID: <48EB87BC.8070309@fhcrc.org>

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



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