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

[Duncan Murdoch]

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