R help - Feb 2007 - Documenting options specific to a package.

If one specifies new options in a package, using the options()
function, where does/should one document these new options?

E.g. suppose that I put the line

	options(melvin=42)

in a file zzz.R in the R directory of the package source, where the
package contains functions foo(), bar(), clyde(), and irving() which
all query options("melvin") and take some action based on the value
of ``melvin''.  The user can of course change the value of
``melvin''
from its default value by doing, e.g.

        options(melvin=99)

Are there any conventions or standards as to how and where the option
``melvin'' should be documented?  It seems somewhat redundant to
include docmentation about melvin in the help on all 4 of foo(),
bar(), clyde(), and irving().

Thanks for any insights.

                                cheers,

                                        Rolf Turner
                                        rolf at math.unb.ca

(An R-devel topic, I believe.)

I would have documentation for options() in the package that documented 
the additional options and linked to \code{\link[base]{options}}.
Users will be given a choice of which page to view on most systems, so 
just make sure the title makes clear that this is options for the package.

On Mon, 19 Feb 2007, rolf at math.unb.ca wrote:
> If one specifies new options in a package, using the options()
> function, where does/should one document these new options?
>
> E.g. suppose that I put the line
>
> 	options(melvin=42)
>
> in a file zzz.R in the R directory of the package source, where the
> package contains functions foo(), bar(), clyde(), and irving() which
> all query options("melvin") and take some action based on the
value
> of ``melvin''.  The user can of course change the value of
``melvin''
> from its default value by doing, e.g.
>
>        options(melvin=99)
>
> Are there any conventions or standards as to how and where the option
> ``melvin'' should be documented?  It seems somewhat redundant to
> include docmentation about melvin in the help on all 4 of foo(),
> bar(), clyde(), and irving().
>
> Thanks for any insights.
>
>                                cheers,
>
>                                        Rolf Turner
>                                        rolf at math.unb.ca
>
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
>
-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595