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

From: Duncan Temple Lang <duncan_at_wald.ucdavis.edu>
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.

  D.

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
>



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel 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 https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive