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

[Duncan Temple Lang]

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
>