[Rd] man page of hist points to truehist, which can't be viewed without loading a library?

[Prof Brian Ripley]

On Thu, 9 Sep 2004, A.J. Rossini wrote:

> Prof Brian Ripley <ripley at stats.ox.ac.uk> writes:
> 
> > On Thu, 9 Sep 2004, A.J. Rossini wrote:
> >
> >> 
> >> rdevel from yesterday, also in 1.9.1 (Debian, -3).
> >> 
> >> The man page of 'hist' (from the graphics package, obtained by
> >> "?hist") suggests 'truehist' under "see also", but 'truehist' isn't
> >> loaded by default (a sensible "of course"), so that "?truehist" fails.
> >> One can do help.search(), of course, which points what to do, but
> >> leads to my question:
> >> 
> >>   In referencing functions in other packages, should the "See Also"
> >>   link mention the library that they are coming from?  I'm less
> >>   concerned about the example and more concerned about some packages
> >>   I'm wrapping up.
> >> 
> >> (this was from the command line in a terminal window, not w/in ESS).
> >
> > It is the norm: see e.g. format.Date.Rd or write.table.Rd, and a good 
> > idea.
> 
> I apologize for not being clear.  It actually does what you describe
> in the underlying markup for the help page for "hist".  What I'm
> referring to is the display of text, not in the source code which
> generates the man page.  i.e.  it would be nice if the markup
> 
>    \code{\link[OtherPackage]{relatedFunction}}
> 
> generated text such as for example, "relatedFunction (in OtherPackage)".

It doesn't and people have written assuming so (see below).

> So to be a bit more explicit, I was wondering whether:
> 
>    \code{\link[OtherPackage]{relatedFunction}}  
> 
> or
> 
>    \code{\link[OtherPackage]{relatedFunction}}  (in OtherPackage)
> 
> would be better, stylistically.  I am leaning towards the use of the
> latter.  I guess I could submit a patch for the former, not sure if I
> can get it done for 2.0 (or if it is even too late).

The latter.  format.date says 

  Also objects of class
  \code{"date"} (from package \pkg{\link[date:as.date]{date}} or
  \pkg{\link[survival:as.date]{survival}}) and
  \code{"dates"} (from package \pkg{\link[chron]{chron}}).

and there are lots of other examples.  So the first would need a lot of 
rewriting.

I've just added several instances of (from package \pkg{foo}) to base.

-- 
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