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

[hadley wickham]

> 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.)

Well I'm arguing from two different positions - as a developer, I want
to minimise the amount of work I have to do get a package up and
running, and as a user I want documentation that's easy to understand.
 This makes my arguments somewhat schizophrenic ;)

Another approach would be to leverage something like Roxygen - i.e.
build a parallel documentation system where it would be possible to
play with these new ideas.  There would be no pressure for developers
to switch, except to access the nice new features enabled by the
format.

>  - 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.

That would be great, and I think for the documentation parser I would
err on the side of being too restrictive - that will impose some cost
on developers, but would enable more powerful higher order tools.
Output to xml would also be useful as it would make it easier to feed
into other tools (like search applications).  I continue to be
confused about where (if anywhere) % can be used in rdoc, and where
they need to be escaped.

>  - 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.

The more I look at my documentation, the more I think a simple macro
simple wouldn't work for me.  There is no way I could write the
documentation for ggplot2 with a set of macros - there are too many
conditionals and complicated sub-expression.  It may help for simpler
packages.

> 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.

I'd be happy to help, especially with my experience writing rdoc with
R and with ruby.  I also have a couple of packages in development that
currently don't have any documentation, where I'd be happy to
experiment with new ways of doing documentation (I'm currently
planning on trying out Roxygen)

Hadley

-- 
http://had.co.nz/