Random.Rd

[ripley@stats.ox.ac.uk]

On Fri, 26 Jul 2002, Uwe Ligges wrote:

>
>
> On Fri, 26 Jul 2002, Kurt Hornik wrote:
>
> > >>>>> Martin Maechler writes:
> >
> > >>>>> "KH" == Kurt Hornik <hornik@ci.tuwien.ac.at> writes:
> > >>>>> ripley  writes:
> > BDR> Uwe,
> > BDR> The titles are not necessarily intended to be aliases.  units.Rd is
> > BDR> another one.  Once upon a time \title automatically generated a \alias,
> > BDR> but not for some time (and I've forgotten the reasoning).
> >
> > Not \title, but \name.
>
> Right, sorry.

[You don't need to apologize for *my* slips!]

> > This is how we started out.  We then realized
> > that e.g. we cannot have .Script.Rd so now we separate the name of the
> > documentation object from the topics it provides documentation for.
> >
> > BDR> I think this is confusing, as help.search shows the entry as
> > BDR> Random(base) but ?Random does not work.  On the other hand, ?Binomial
> > BDR> does work, and there is no object Binomial.  My preference would be to
> > BDR> change help.search, I think.
> >
> > > However I think, he (and I) would also want
> >
> > >   ?Random
> >
> > > to work which needs a change to help() as well {or rather to an
> > > underlying utility common to all of help(), help.search() and
> > > Java searching from the help.start() search interface ?!
>
> Right.
>
>
> > I do not see what is confusing.
>
> Well, Random is listed at several places, e.g. in the result of
>  help.search("random")  : # ..., Random(base), ...
> So, at least for me, it is confusing trying ?Random after that.

I think Kurt is already allowing that as confusing.

> > Rd writers create a help file and use
> > \alias to register the topics documented.  We cannot assume that the
> > file name is a topic documented, see zScript.Rd which documents .Script.
>
> Agreed, but why not \name ?

We need \name to hyperlink correctly. This came about originally because
of Windows file name restrictions, and later Kurt's example came up on
some MacOS variant.

> > Why should 'Random' be a topic documented?
> >
> > help.start() has a bug because it incorrectly assumes that we can get
> > help on the name. I will fix this by instead pointing to the *first*
> > alias in the documentation object.
>
> As Martin pointed out, not only help.start() has this "bug"(?).
>
> I think it is not a bad idea to get help with ?NAME , if NAME is listed
> anywhere else ...

Agreed, but my solution was to not use NAME anywhere else.  I don't have a
problem with the Java search, as clicking on the item works.

There is a side issue. Is `Random' a reasonable help topic?  Probably not
(ditto Binomial) but `random' probably is.

-- 
Brian D. Ripley,                  ripley@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 272860 (secr)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-devel-request@stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._