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

From: Duncan Temple Lang <>
Date: Tue, 07 Oct 2008 09:18:30 -0700

FWIW, I'll note that one or two of us are working on a documentation system that uses XML and specifically extensions of Docbook to create documentation for R objects and that transparently extends to general articles, vignettes, books, etc. and dynamic and interactive reproducible documents. The tools are all R-based (via packages embedding XML and XSL processors) and the expectation is that it will provide a parallel framework in which interested researchers can experiment with new ideas.


hadley wickham wrote:
>> 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
> mailing list Received on Tue 07 Oct 2008 - 16:21:49 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