Hi,
Not that I have time, but I suspect that there are not that many ways
to document a package, probably only five or six variants in the wild
and an overview function, with a name like packageOverview, would be
relatively easy to write and would be able to extract all available
information into a single place for a user.
An advantage of such an approach is that it can be updated, independent
of what particular developers/packages do, leaving us free to choose our
own manner of documentation. Also, one could easily imaging giving
overviews of the class structure and functions + relationships (a thread
on r-help) could be options, as could extracting doxygen type comments.
But, as with all things R, someone needs to actually put it together -
the tools are all there.
best wishes
Robert
Duncan Murdoch wrote:
On 07/10/2008 10:17 AM, hadley wickham wrote:
This shows up in the HTML help system. It would be better if it
showed up
in all help formats, but there are other ways to do that, e.g.
creating an
Rd help page pointing to those files.
Or you can just link to them from your website.
I don't think you'd argue with the statement that there's already too
many different ways to find R documentation.
I think that's a paraphrase of one of my earlier posts.
There are plenty of
hacks and work-arounds to jam different types of documentation in
different places, but they are just hacks and work-arounds. My
feeling is that evolutionary modification of the documentation system
is only going to get us so far, and at some point the entire
foundations need to be rethought.
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.)
I think any change we make now needs to be incremental, but there's a
tremendous amount of friction against anything at all, and very few
offers of support to actually do the work.
Here are things I'm currently working on, that I'd appreciate support for:
- 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.
- 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.
- Source level debugging support. Gabor mentioned that it's hard to
debug Sweave files; this could help.
Of course, the problem is having enough time to do that, and then to
code up the solution!
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.
Duncan Murdoch
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
--
Robert Gentleman, PhD
Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M2-B876
PO Box 19024
Seattle, Washington 98109-1024
206-667-7700
[EMAIL PROTECTED]
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
