From ripley@stats.ox.ac.uk  Sun Dec 31 22:16:39 2000
From: ripley@stats.ox.ac.uk (Prof Brian Ripley)
Date: Sun, 31 Dec 2000 22:16:39 +0000 (GMT)
Subject: [Rd] Package overview document?
In-Reply-To: <3a4f5971.54339465@smtp1.sympatico.ca>
Message-ID: <Pine.GSO.4.05.10012312209120.16875-100000@toucan.stats>

On Sun, 31 Dec 2000, Duncan Murdoch wrote:

> On Sun, 31 Dec 2000 14:11:47 +0000 (GMT Standard Time), Prof Brian D
> Ripley <ripley@stats.ox.ac.uk> wrote:
> 
> >On Sun, 31 Dec 2000, Duncan Murdoch wrote:
> >> I'd like to write an overview of a package, and have it show up when
> >> someone types
> >> 
> >>  library(help=mypackage)
>   ...
> >> Is it reasonable to write such a
> >> description into the INDEX file?  Is there some other file where I can
> >
> >That's what a lot of other packages do, e.g. boot.
> 
> Okay, I'll do that.  There are a couple of deficiencies, most notably
> the fact that INDEX isn't used in the HTML or LaTeX versions of the
> help files.  I saw in the docs somewhere that the DESCRIPTION text
> would show up in the Latex output in some later version; is anyone
> working on this?  If not, I might give it a shot.

I've not seen that.  The latex versions are separate files, so it seems
only to make sense if running pkg2tex on a package.

> >> >  ?mypackage
> 
> >It is possible, but you need to watch namespace issues.  For example,
> >package sm has a file sm.Rd that gives an overview: you need it loaded
> >for that to work via ?sm but help(sm, package="sm") works always
> >(if sm is installed).
> >
> >The problem is ensuring that you have a non-clashing name. dse1 has
> >00General.Description which seems to me to be very likely to clash.
> 
> I think the most obvious choice of name is the name of the package,
> but that would clash fairly often with the name of a function within
> it (e.g. boot), and it wouldn't show up first in alphabetical lists.
> What some other help systems (e.g. Winhelp) do when a request is
> ambiguous is to present a list of choices, with extra information
> appended to help select.  If R did that, the clash wouldn't be such a
> big deal. 

Um. They only sometimes do that, and only for searches or perhaps indices,
never for hyperlinks. They also only cope with single help files, and the
problem here is across help sets.  It's a lot less convenient on a non-GUI
system, too.

Perhaps we need to give a help file such as pkg-foo.Rd or foo-overview.Rd
special treatment.  It will not happen soon, though, and both imposing
more standards on .Rd format and moving away from .Rd to something 
easier to parse are under discussion.

Brian

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


[Rd] Package overview document?
Prof Brian Ripley