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

From: hadley wickham <>
Date: Tue, 07 Oct 2008 11:10:57 -0500

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



______________________________________________ mailing list
Received on Tue 07 Oct 2008 - 16:13:09 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 Thu 09 Oct 2008 - 07:30:17 GMT.

Mailing list information is available at Please read the posting guide before posting to the list.

list of date sections of archive