[Rd] Delphi (Pascal) headerfiles online | Excel
Dear list Some time ago I told about the translation of the LGPL'ed R headerfiles to Delphi. I am happy that most of them are translated now and the code, demo and description is online (licensed under GPLv2): http://treetron.googlepages.com I just annonced a native Excel reader/writer in R-help which is based on this headerfile translation. Probably most of you won't care (using Linux) but it still would be nice if someone knowledgeable could have a look into it. It is my first package... and if there should be things not done so well, I'd like to fix it until final release (in about a week). Thanks and best regards, Hans-Peter [[alternative HTML version deleted]] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] Documentation issues [Was: Function hints]
I would like to follow up on another one of the documentation issues raised in
the discussion on function hints. Duncan mentioned that the R core were working
on preprocessing directives for .Rd files, which could possibly include some
sort of include directive. I was wondering if a "includeexamples" directive
might also be considered.
It often makes sense to use the same example to illustrate the use of different
functions, or perhaps extend an example used to illustrate one function to
illustrate another. One way to do this is simply to put
example(fnA)
in the \examples for fnB, but this is not particularly helpful for people
reading the help pages as they either need to look at both help pages or run
the example. The alternative is to maintain multiple copies of the same code,
which is not ideal.
So it would be useful to be able to put
\includeexamples(fnA)
so that the code is replicated in fnB.Rd. Perhaps an include directive could do
this anyway, but it might be useful to have a special directive for examples so
that RCMD check is set up to only check the original example to save time (and
unnecessary effort).
On a related issue, it would be nice if source() had an option to print
comments contained in the source file, so that example() and demo() could print
out annotation.
Heather
Dr H Turner
Research Assistant
Dept. of Statistics
The University of Warwick
Coventry
CV4 7AL
Tel: 024 76575870
Fax: 024 7652 4532
Url: www.warwick.ac.uk/go/heatherturner
>>> <[EMAIL PROTECTED]> 06/20/06 01:43am >>>
[This is not about the feasibility of a "hints" function-- which would
be incredibly useful, but perhaps very very hard to do-- but about some
of the other documentation issues raised in Hadley's post and in
Duncan's reply]
WRTO documentation & code together: for several years, I've successfully
used the 'mvbutils' package to keep every function definition & its
documentation together, editing them together in the same file--
function first, then documentation in plain-text (basically the format
you see if you use "vanilla help" inside R). Storage-wise, the
documentation is just kept as an attribute of the function (with a print
method that hides it by default)-- I also keep a text backup of the
combination. Any text editor will do. When it's time to create a
package, the Rd file is generated automatically.
For me, it's been extremely helpful to keep function & documentation
together during editing-- it greatly increases the chance that I will
actually update the doco when I change the code, rather than putting it
off until I've forgotten what I did. Also, writing Rd format is a
nightmare (again, personal opinion)-- being able to write plain-text
makes the whole documentation thing bearable.
The above is not quite to the point of the original post, I think, which
talks about storing the documentation as commented bits *inside* the
function code. However, I'm not sure the latter is really desirable;
there is some merit in forcing authors to write an explicit "Details" or
"Description" section that is not just a paraphrase of programming
comments, and such sections are unlikely to fit easily inside code. At
any rate, I wouldn't want to have to interpret my *own* programming
comments as a usage guide!
WRTO automatic "usage" sections: it is easy to write code to do this
('prompt', and there is also some in 'mvbutils'-- not sure if it's in
the current release though) but at least as far as the "usage" section
goes, I think people should be "vigorously encouraged" to write their
own, showing as far as possible how one might actually *use* the
function. For many functions, just duplicating the argument list is not
helpful to the user-- a function can often be invoked in several
different ways, with different arguments relevant to different
invocations. I think it's good to show how this can be done in the
"usage" section, with comments, rather than deferring all practical
usage to "examples". For one thing, "usage" is near the top, and so
gives a very quick reminder without having to scroll through the entire
doco; for another, "usage" and "arguments" are visually adjacent,
whereas "examples" can be widely separated from "arguments".
My general point here is: the documentating process should be as
painless as possible, but not more so. Defaults that are likely to lead
to unhelpful documentation are perhaps best avoided.
For this general reason, I applaud R's fairly rigid documentation
standards, even though I frequently curse them. (And I would like to see
some bits more rigid, such as compulsory "how-to-use-this" documentation
for each package!)
The next version of 'mvbutils' will include various tools for easy "live
editing" and automated preparation of packages-- I've been using them
for a while, but still have to get round to finishing the documentation
;)
Mark Bravington
CSIRO Mathematical & Information Sciences
Marine Laboratory
Castray Esplanade
Hobart 7001
TAS
ph (+61) 3 6232
Re: [Rd] [R] combining tables
On 19 Jun 2006, at 12:45, Gabor Grothendieck wrote:
> Try this:
>
> both <- c(x,y)
> as.table(tapply(both, names(both), sum))
thanks for this, Gabor.
The class of the objects I am manipulating in my
package is c("count", "table").
It'd be nice to overload the "+" symbol so that I can add
two count objects like this with a simple "x+y". To this end, I
defined a Ops.count() function that executed Gabor's summation.
But, this broke all sorts of functionality in the package,
because the ">" relation was not defined in my Ops.count()
function.
In my case, the only operation that I want to redefine is "+".
I want to leave all the others unchanged.
What is Best Practice for redefining just one binary operator?
>
> On 6/19/06, Robin Hankin <[EMAIL PROTECTED]> wrote:
>> Hi
>>
>> Suppose I have two tables of counts of different animals and I
>> wish to pool them so the total of the sum is the sum of the total.
>>
>> Toy example follows (the real ones are ~10^3 species and ~10^6
>> individuals).
>> x and y are zoos that have merged and I need a combined inventory
>> including animals that are temporarily absent.
>>
>>
>> > (x <- as.table(c(cats=3,squid=7,pigs=2,dogs=1,slugs=0)))
>> cats squid pigs dogs slugs
>> 3 7 2 1 0
>> > (y <- as.table(c(cats=4,dogs=5,slugs=3,crabs=0)))
>> cats dogs slugs crabs
>> 4 5 3 0
>> > (desired.output <- as.table(c
>> (cats=7,squid=7,pigs=2,dogs=6,slugs=3,crabs=0)))
>> cats squid pigs dogs slugs crabs
>> 7 7 2 6 3 0
>> >
>>
>>
>>
>>
>> Note that we have 7 cats altogether, and the crabs correctly show
>> as zero counts.
>>
>>
>> How to do this nicely in R?
>>
>>
>>
--
Robin Hankin
Uncertainty Analyst
National Oceanography Centre, Southampton
European Way, Southampton SO14 3ZH, UK
tel 023-8059-7743
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] Wish/suggestion: add output of citation() to package "manuals" (PR#9009)
Dear R core, influenced by recent panel discussion in Vienna I think that it would be nice to add package specific output of citation() function to package reference manuals. I think that apropriate place would be just after fields from DESCRIPTION file. This will be OK for CRAN, but not for locally installed packages as there is not reference manual there (at least on my linux box) - why is this the case? Perhaps output of citation() could be added to package specific help page i.e. to mypackage.package.Rd file. The same could be done with R's manuals. I know that there is an entry in FAQ on this and that there is a note after launching R, but questions about apropriate reference on R-help list are quite frequent. Perhaps this is so due to the habit that one looks into the paper/book/manual about relevant information for reference. -- Lep pozdrav / With regards, Gregor Gorjanc -- University of Ljubljana PhD student Biotechnical Faculty Zootechnical Department URI: http://www.bfro.uni-lj.si/MR/ggorjan Groblje 3 mail: gregor.gorjanc bfro.uni-lj.si SI-1230 Domzale tel: +386 (0)1 72 17 861 Slovenia, Europefax: +386 (0)1 72 17 888 -- "One must learn by doing the thing; for though you think you know it, you have no certainty until you try." Sophocles ~ 450 B.C. __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Delphi (Pascal) headerfiles online | Excel
Hans-Peter wrote:
> Dear list
>
> Some time ago I told about the translation of the LGPL'ed R headerfiles to
> Delphi. I am happy that most of them are translated now and the code, demo
> and description is online (licensed under GPLv2):
> http://treetron.googlepages.com
>
>
Finaly ;)
> I just annonced a native Excel reader/writer in R-help which is based on
> this headerfile translation.
>
> Probably most of you won't care (using Linux) but it still would be nice if
> someone knowledgeable could have a look into it. It is my first package...
> and if there should be things not done so well, I'd like to fix it until
> final release (in about a week).
>
Well, in my case it's a way to "sell the R" to clients, it's means they
don't know R, so I create a "standalone" program using R. After some
time I convince them to use a "client/server" version using linux, and
in the end it's constructed a cluster of servers and desktop in linux
;). I tried the RDCom ("hey, what are you doing with my Windows?") ,
Java ("What is this? A tiny program using 15Mb to 20Mb!") or C++("Don't
you think it's too expensive for a small program?") and they don't liked :(
So, Hans, your job is coming in a great help, thanks.
Sandro
[EMAIL PROTECTED]
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Documentation issues [Was: Function hints]
On 6/20/2006 5:18 AM, Heather Turner wrote:
> I would like to follow up on another one of the documentation issues raised
> in the discussion on function hints. Duncan mentioned that the R core were
> working on preprocessing directives for .Rd files, which could possibly
> include some sort of include directive. I was wondering if a
> "includeexamples" directive might also be considered.
>
> It often makes sense to use the same example to illustrate the use of
> different functions, or perhaps extend an example used to illustrate one
> function to illustrate another. One way to do this is simply to put
>
> example(fnA)
>
> in the \examples for fnB, but this is not particularly helpful for people
> reading the help pages as they either need to look at both help pages or run
> the example. The alternative is to maintain multiple copies of the same code,
> which is not ideal.
>
> So it would be useful to be able to put
>
> \includeexamples(fnA)
>
> so that the code is replicated in fnB.Rd. Perhaps an include directive could
> do this anyway, but it might be useful to have a special directive for
> examples so that RCMD check is set up to only check the original example to
> save time (and unnecessary effort).
Thanks, that's a good suggestion. My inclination would be towards just
one type of \include; it could be surrounded by notation saying not to
check it in all but one instance if the author wanted to save testing time.
> On a related issue, it would be nice if source() had an option to print
> comments contained in the source file, so that example() and demo() could
> print out annotation.
Yes, this has been a long-standing need, but it's somewhat tricky
because of the way source currently works: it parses the whole file,
then executes the parsed version. The first step loses the comments, so
you see a deparsed version when executing. What I think it should do is
have pointers back from the parsed version to the original source code,
but that needs fairly low level changes. This is some of the missing
"infrastructure" I mentioned below.
Duncan Murdoch
>
> Heather
>
> Dr H Turner
> Research Assistant
> Dept. of Statistics
> The University of Warwick
> Coventry
> CV4 7AL
>
> Tel: 024 76575870
> Fax: 024 7652 4532
> Url: www.warwick.ac.uk/go/heatherturner
>
<[EMAIL PROTECTED]> 06/20/06 01:43am >>>
> [This is not about the feasibility of a "hints" function-- which would
> be incredibly useful, but perhaps very very hard to do-- but about some
> of the other documentation issues raised in Hadley's post and in
> Duncan's reply]
>
> WRTO documentation & code together: for several years, I've successfully
> used the 'mvbutils' package to keep every function definition & its
> documentation together, editing them together in the same file--
> function first, then documentation in plain-text (basically the format
> you see if you use "vanilla help" inside R). Storage-wise, the
> documentation is just kept as an attribute of the function (with a print
> method that hides it by default)-- I also keep a text backup of the
> combination. Any text editor will do. When it's time to create a
> package, the Rd file is generated automatically.
>
> For me, it's been extremely helpful to keep function & documentation
> together during editing-- it greatly increases the chance that I will
> actually update the doco when I change the code, rather than putting it
> off until I've forgotten what I did. Also, writing Rd format is a
> nightmare (again, personal opinion)-- being able to write plain-text
> makes the whole documentation thing bearable.
>
> The above is not quite to the point of the original post, I think, which
> talks about storing the documentation as commented bits *inside* the
> function code. However, I'm not sure the latter is really desirable;
> there is some merit in forcing authors to write an explicit "Details" or
> "Description" section that is not just a paraphrase of programming
> comments, and such sections are unlikely to fit easily inside code. At
> any rate, I wouldn't want to have to interpret my *own* programming
> comments as a usage guide!
>
> WRTO automatic "usage" sections: it is easy to write code to do this
> ('prompt', and there is also some in 'mvbutils'-- not sure if it's in
> the current release though) but at least as far as the "usage" section
> goes, I think people should be "vigorously encouraged" to write their
> own, showing as far as possible how one might actually *use* the
> function. For many functions, just duplicating the argument list is not
> helpful to the user-- a function can often be invoked in several
> different ways, with different arguments relevant to different
> invocations. I think it's good to show how this can be done in the
> "usage" section, with comments, rather than deferring all practical
> usage to "examples". For one thing, "usage" is near the top, and so
> gives a very quick reminder without having to sc
Re: [Rd] [R] combining tables
On 6/20/06, Robin Hankin <[EMAIL PROTECTED]> wrote:
> On 19 Jun 2006, at 12:45, Gabor Grothendieck wrote:
> > Try this:
> >
> > both <- c(x,y)
> > as.table(tapply(both, names(both), sum))
>
>
> thanks for this, Gabor.
>
> The class of the objects I am manipulating in my
> package is c("count", "table").
>
> It'd be nice to overload the "+" symbol so that I can add
> two count objects like this with a simple "x+y". To this end, I
> defined a Ops.count() function that executed Gabor's summation.
>
> But, this broke all sorts of functionality in the package,
> because the ">" relation was not defined in my Ops.count()
> function.
>
> In my case, the only operation that I want to redefine is "+".
> I want to leave all the others unchanged.
>
> What is Best Practice for redefining just one binary operator?
>
>
>
> >
> > On 6/19/06, Robin Hankin <[EMAIL PROTECTED]> wrote:
> >> Hi
> >>
> >> Suppose I have two tables of counts of different animals and I
> >> wish to pool them so the total of the sum is the sum of the total.
> >>
> >> Toy example follows (the real ones are ~10^3 species and ~10^6
> >> individuals).
> >> x and y are zoos that have merged and I need a combined inventory
> >> including animals that are temporarily absent.
> >>
> >>
> >> > (x <- as.table(c(cats=3,squid=7,pigs=2,dogs=1,slugs=0)))
> >> cats squid pigs dogs slugs
> >> 3 7 2 1 0
> >> > (y <- as.table(c(cats=4,dogs=5,slugs=3,crabs=0)))
> >> cats dogs slugs crabs
> >> 4 5 3 0
> >> > (desired.output <- as.table(c
> >> (cats=7,squid=7,pigs=2,dogs=6,slugs=3,crabs=0)))
> >> cats squid pigs dogs slugs crabs
> >> 7 7 2 6 3 0
> >> >
> >>
> >>
> >>
> >>
> >> Note that we have 7 cats altogether, and the crabs correctly show
> >> as zero counts.
> >>
> >>
> >> How to do this nicely in R?
This will define + but not the others:
"+.count" <- function(x,y) {
both <- c(x,y)
as.table(tapply(both, names(both), sum))
}
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Wish/suggestion: add output of citation() to package "manuals" (PR#9009)
> On Tue, 20 Jun 2006 12:22:42 +0200 (CEST), > gregor gorjanc (gg) wrote: > Dear R core, > influenced by recent panel discussion in Vienna I think that it would be > nice to add package specific output of citation() function to package > reference manuals. I think that apropriate place would be just after > fields from DESCRIPTION file. This will be OK for CRAN, but not for > locally installed packages as there is not reference manual there (at > least on my linux box) - why is this the case? Perhaps output of > citation() could be added to package specific help page i.e. to > mypackage.package.Rd file. Yes, very good idea, I have put it onto my 2do list for 2.4. Best, Fritz __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Wish/suggestion: add output of citation() to package "manuals" (PR#9010)
> On Tue, 20 Jun 2006 12:22:42 +0200 (CEST), > gregor gorjanc (gg) wrote: > Dear R core, > influenced by recent panel discussion in Vienna I think that it would be > nice to add package specific output of citation() function to package > reference manuals. I think that apropriate place would be just after > fields from DESCRIPTION file. This will be OK for CRAN, but not for > locally installed packages as there is not reference manual there (at > least on my linux box) - why is this the case? Perhaps output of > citation() could be added to package specific help page i.e. to > mypackage.package.Rd file. Yes, very good idea, I have put it onto my 2do list for 2.4. Best, Fritz __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Documentation issues [Was: Function hints]
>>> Duncan Murdoch <[EMAIL PROTECTED]> 06/20/06 11:58am >>>
On 6/20/2006 5:18 AM, Heather Turner wrote:
> I would like to follow up on another one of the documentation issues raised
> in the discussion on function hints. Duncan mentioned that the R core were
> working on preprocessing directives for .Rd files, which could possibly
> include some sort of include directive. I was wondering if a
> "includeexamples" directive might also be considered.
>
> It often makes sense to use the same example to illustrate the use of
> different functions, or perhaps extend an example used to illustrate one
> function to illustrate another. One way to do this is simply to put
>
> example(fnA)
>
> in the \examples for fnB, but this is not particularly helpful for people
> reading the help pages as they either need to look at both help pages or run
> the example. The alternative is to maintain multiple copies of the same code,
> which is not ideal.
>
> So it would be useful to be able to put
>
> \includeexamples(fnA)
>
> so that the code is replicated in fnB.Rd. Perhaps an include directive could
> do this anyway, but it might be useful to have a special directive for
> examples so that RCMD check is set up to only check the original example to
> save time (and unnecessary effort).
Thanks, that's a good suggestion. My inclination would be towards just
one type of \include; it could be surrounded by notation saying not to
check it in all but one instance if the author wanted to save testing time.
Fair enough, but at the moment I don't think such notation exists - using
\dontrun would skip the check, but would also mean the code would not get run
by example(), leading to missing/broken examples. You could introduce a
\dontcheck directive but this might be dangerous!
Heather
> On a related issue, it would be nice if source() had an option to print
> comments contained in the source file, so that example() and demo() could
> print out annotation.
Yes, this has been a long-standing need, but it's somewhat tricky
because of the way source currently works: it parses the whole file,
then executes the parsed version. The first step loses the comments, so
you see a deparsed version when executing. What I think it should do is
have pointers back from the parsed version to the original source code,
but that needs fairly low level changes. This is some of the missing
"infrastructure" I mentioned below.
Duncan Murdoch
>
> Heather
>
> Dr H Turner
> Research Assistant
> Dept. of Statistics
> The University of Warwick
> Coventry
> CV4 7AL
>
> Tel: 024 76575870
> Fax: 024 7652 4532
> Url: www.warwick.ac.uk/go/heatherturner
>
<[EMAIL PROTECTED]> 06/20/06 01:43am >>>
> [This is not about the feasibility of a "hints" function-- which would
> be incredibly useful, but perhaps very very hard to do-- but about some
> of the other documentation issues raised in Hadley's post and in
> Duncan's reply]
>
> WRTO documentation & code together: for several years, I've successfully
> used the 'mvbutils' package to keep every function definition & its
> documentation together, editing them together in the same file--
> function first, then documentation in plain-text (basically the format
> you see if you use "vanilla help" inside R). Storage-wise, the
> documentation is just kept as an attribute of the function (with a print
> method that hides it by default)-- I also keep a text backup of the
> combination. Any text editor will do. When it's time to create a
> package, the Rd file is generated automatically.
>
> For me, it's been extremely helpful to keep function & documentation
> together during editing-- it greatly increases the chance that I will
> actually update the doco when I change the code, rather than putting it
> off until I've forgotten what I did. Also, writing Rd format is a
> nightmare (again, personal opinion)-- being able to write plain-text
> makes the whole documentation thing bearable.
>
> The above is not quite to the point of the original post, I think, which
> talks about storing the documentation as commented bits *inside* the
> function code. However, I'm not sure the latter is really desirable;
> there is some merit in forcing authors to write an explicit "Details" or
> "Description" section that is not just a paraphrase of programming
> comments, and such sections are unlikely to fit easily inside code. At
> any rate, I wouldn't want to have to interpret my *own* programming
> comments as a usage guide!
>
> WRTO automatic "usage" sections: it is easy to write code to do this
> ('prompt', and there is also some in 'mvbutils'-- not sure if it's in
> the current release though) but at least as far as the "usage" section
> goes, I think people should be "vigorously encouraged" to write their
> own, showing as far as possible how one might actually *use* the
> function. For many functions, just duplicating the argument list is not
> helpful to the user-- a function can of
Re: [Rd] [R] Function hints
I think it's bad to document dissimilar functions in the same file, but
similar related functions *should* be documented together. Not doing
this just adds to the burden of documenting them, and the risk of
modifying only part of the documentation so that it is inconsistent.
The user also gets the benefit of seeing a common description all at
once, rather than having to decide whether to follow "See also" links.
I agree - having some kind of include command would mitigate this
problem, but I think many documentation systems have struggled with
this (hard) problem and I'm not aware of any great solutions.
Your solutions would both be interesting on their own merits regardless
of the above. We did decide to work on preprocessing directives for .Rd
files at the R core meetings; some sort of include directive may be
possible.
One model to follow might be xinclude
(http://www.w3.org/TR/xinclude/), although I don't really know much
about it apart from a dim awareness of its existance, and being an xml
schema it is probably over complicated.
I don't think I would want complete documentation mixed with the
original source, but it would certainly be interesting to have partial
documentation there. (Complete documentation is too long, and would
make it harder to read the source without a dedicated editor that could
hide it. Though ESS users may see it as a reasonable requirement to
have everyone use the same editor, I don't think it is.) However, this
is a lot of work, depending on infrastructure that is not in place.
I've attached an example of my own inline documentation system,
modelled closely on javadoc, which I use for documenting my packages.
It took me a few hours to whip up a (ruby) program to turn this into
rdoc files, and wouldn't require too much more time to make more
robust (and rewrite in R for wider distribution).
Having a lot of documentation in your source files does feel strange
at first, but I think you quickly get used to it, and functions with
more code than documentation soon start to look strange.
I think it is worse than that. There are concepts in packages that just
don't arise in base R, and hence there would be no keywords for them
other than "misc", even if someone redesigned the current system.
Keywording is hard, and it's not clear to me how to do much better than
we currently do.
I agree - apart from hiring a dedicated keyword person I can't see
anyway that this is going to improve significantly.
> * Some functions aren't documented (eg. simulate.lm, formula.glm) -
> typically, these are methods where the documentation is in the
> generic. Solution: these methods should all be aliased to the generic
> (by default?), and R CMD check should be amended to check for this
> situation. You could also argue that this is a deficiency with my
> function, and easily fixed by automatically referring to the generic
> if the specific isn't documented.
I'd say it's a deficiency of your function. You might want to look at
the code in get("?") and .helpForCall() to see how those functions work
out things like
?simulate(x)
Ok, I can fix my function fairly easily, what should I list - the name
of the function, or what to call to get help? (or maybe if people
were more aware of the "?simulate(x)" form, it wouldn't be such a
problem.
> * Needs wide display to be effective. Could be dealt with by
> breaking description in a sensible manner (there may already by R code
> to do this. Please let me know if you know of any)
I think strwrap() may do what you want.
That's it - I'll give that a go.
> * Personally, I think sentence case is more aesthetically pleasing
> (and more flexible) than title case.
It's quite hard to go from existing title case to sentence case, because
we don't have any markup to indicate proper names. One would think it
would be easier to go in the opposite direction, but in fact the same
problem arises: "van Beethoven" for example, not "Van Beethoven".
Yes, which is why I don't do it automatically - it would be nice to
recommend using sentence case in the R developers guide.
Hadley
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] [R] Function hints
> For me, it's been extremely helpful to keep function & documentation
> together during editing-- it greatly increases the chance that I will
> actually update the doco when I change the code, rather than putting it
> off until I've forgotten what I did. Also, writing Rd format is a
> nightmare (again, personal opinion)-- being able to write plain-text
> makes the whole documentation thing bearable.
I agree!
> The above is not quite to the point of the original post, I think, which
> talks about storing the documentation as commented bits *inside* the
> function code. However, I'm not sure the latter is really desirable;
> there is some merit in forcing authors to write an explicit "Details" or
> "Description" section that is not just a paraphrase of programming
> comments, and such sections are unlikely to fit easily inside code. At
> any rate, I wouldn't want to have to interpret my *own* programming
> comments as a usage guide!
That is what I mean by inline documentation (in the same file),
probably need a better name. Javadoc uses "doc comments in source
code", rdoc "Generates structured HTML documentation from Ruby
source.", perl: "embedded documentation", php: "standard
auto-documentation tool"...
> WRTO automatic "usage" sections: it is easy to write code to do this
> ('prompt', and there is also some in 'mvbutils'-- not sure if it's in
> the current release though) but at least as far as the "usage" section
> goes, I think people should be "vigorously encouraged" to write their
> own, showing as far as possible how one might actually *use* the
> function. For many functions, just duplicating the argument list is not
> helpful to the user-- a function can often be invoked in several
> different ways, with different arguments relevant to different
> invocations. I think it's good to show how this can be done in the
I write functions that have only one use, and I think having a
function that takes widely different sets of parameters depending on
usage to be a bit of a "code smell" (personally opinion only, of
course)
> My general point here is: the documentating process should be as
> painless as possible, but not more so. Defaults that are likely to lead
> to unhelpful documentation are perhaps best avoided.
> For this general reason, I applaud R's fairly rigid documentation
> standards, even though I frequently curse them. (And I would like to see
> some bits more rigid, such as compulsory "how-to-use-this" documentation
> for each package!)
I agree - making it easy for people to generate useless documentation
is no better than making it hard to generate good documentation.
Reducing the duplication between code and documentation (eg. argument
list) and having sensible defaults (eg. usage section) can go a long
way to making the process much less painful.
Hadley
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Documentation issues [Was: Function hints]
I've done a bit on this, but I've kept a low profile because it is
"under development". In the R.oo package there is the Rdoc compiler,
which compiles Rdoc comments into Rd files. It uses directives such
as @include "../incl/myExample.R" and @synopsis (extracting details
from the code), @keyword IO, @see "base::ls", @TRUE, @NULL, and so on.
Many of these may be included in the Rd compiler directly. I decided
on a preprocessor because that gave me much more flexibility.
PRO:
* Easy to maintain Rd files.
* Rdoc help can standalone files, cf. Rd files, or incorporated as
specially tagged R comments within the source code.
* Written in plain R (no perl scripts).
CONS:
* The "@" prefix was decided on a bit before 'methods' came around and
is a bit unfortunate now. However, I wanted to keep it seperate from
the Rd tags \foo{}.
* Currently, little support for S4, because I don't use that too much.
* I've added more features to the Rdoc preprocessor as I needed them
myself; it is has grown for a small set or tags to quite a few and I
was never careful enough to design a real parser language. The actual
code is quite ad hoc.
I have little time to clean up the code etc. However, the
preprocessor works and at least it might give you some ideas if you
decided to extend the Rd language.
Cheers
Henrik
On 6/20/06, Duncan Murdoch <[EMAIL PROTECTED]> wrote:
> On 6/20/2006 5:18 AM, Heather Turner wrote:
> > I would like to follow up on another one of the documentation issues raised
> > in the discussion on function hints. Duncan mentioned that the R core were
> > working on preprocessing directives for .Rd files, which could possibly
> > include some sort of include directive. I was wondering if a
> > "includeexamples" directive might also be considered.
> >
> > It often makes sense to use the same example to illustrate the use of
> > different functions, or perhaps extend an example used to illustrate one
> > function to illustrate another. One way to do this is simply to put
> >
> > example(fnA)
> >
> > in the \examples for fnB, but this is not particularly helpful for people
> > reading the help pages as they either need to look at both help pages or
> > run the example. The alternative is to maintain multiple copies of the same
> > code, which is not ideal.
> >
> > So it would be useful to be able to put
> >
> > \includeexamples(fnA)
> >
> > so that the code is replicated in fnB.Rd. Perhaps an include directive
> > could do this anyway, but it might be useful to have a special directive
> > for examples so that RCMD check is set up to only check the original
> > example to save time (and unnecessary effort).
>
> Thanks, that's a good suggestion. My inclination would be towards just
> one type of \include; it could be surrounded by notation saying not to
> check it in all but one instance if the author wanted to save testing time.
>
> > On a related issue, it would be nice if source() had an option to print
> > comments contained in the source file, so that example() and demo() could
> > print out annotation.
>
> Yes, this has been a long-standing need, but it's somewhat tricky
> because of the way source currently works: it parses the whole file,
> then executes the parsed version. The first step loses the comments, so
> you see a deparsed version when executing. What I think it should do is
> have pointers back from the parsed version to the original source code,
> but that needs fairly low level changes. This is some of the missing
> "infrastructure" I mentioned below.
>
> Duncan Murdoch
>
> >
> > Heather
> >
> > Dr H Turner
> > Research Assistant
> > Dept. of Statistics
> > The University of Warwick
> > Coventry
> > CV4 7AL
> >
> > Tel: 024 76575870
> > Fax: 024 7652 4532
> > Url: www.warwick.ac.uk/go/heatherturner
> >
> <[EMAIL PROTECTED]> 06/20/06 01:43am >>>
> > [This is not about the feasibility of a "hints" function-- which would
> > be incredibly useful, but perhaps very very hard to do-- but about some
> > of the other documentation issues raised in Hadley's post and in
> > Duncan's reply]
> >
> > WRTO documentation & code together: for several years, I've successfully
> > used the 'mvbutils' package to keep every function definition & its
> > documentation together, editing them together in the same file--
> > function first, then documentation in plain-text (basically the format
> > you see if you use "vanilla help" inside R). Storage-wise, the
> > documentation is just kept as an attribute of the function (with a print
> > method that hides it by default)-- I also keep a text backup of the
> > combination. Any text editor will do. When it's time to create a
> > package, the Rd file is generated automatically.
> >
> > For me, it's been extremely helpful to keep function & documentation
> > together during editing-- it greatly increases the chance that I will
> > actually update the doco when I change the code, rather than putting it
> > off until I've forgotten what I did
[Rd] minor typos in ?which and ?apropos (PR#9013)
find . -name "*.Rd" | xargs grep "who's"
these should both be "whose"
./src/library/base/man/which.Rd: a \code{\link{dim}} attribute), the
result is a matrix who's rows each
(also consider "whose rows are each the indices ..." rather than
"whose rows each are the indices ...")
./src/library/utils/man/apropos.Rd: \item{mode}{character; if not
\code{"any"}, only objects who's
(under details "only those objects that are of mode \code{mode} ..."
but this is getting very grammatically picky indeed)
Ben
--
620B Bartram Hall[EMAIL PROTECTED]
Zoology Department, University of Floridahttp://www.zoo.ufl.edu/bolker
Box 118525 (ph) 352-392-5697
Gainesville, FL 32611-8525 (fax) 352-392-3704
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
