From maechler at stat.math.ethz.ch  Wed Nov 16 09:42:35 2005
From: maechler at stat.math.ethz.ch (Martin Maechler)
Date: Wed, 16 Nov 2005 09:42:35 +0100
Subject: [Rd] Package manpage DCF hooks
In-Reply-To: <Pine.OSF.4.58.0511151235350.98026@wotan.mdacc.tmc.edu>
References: <Pine.OSF.4.58.0511140146400.518678@wotan.mdacc.tmc.edu>
	<971536df0511140012t5b9a2ee0vfd72dbb66c574a11@mail.gmail.com>
	<Pine.OSF.4.58.0511141539060.32647@wotan.mdacc.tmc.edu>
	<17273.44877.537229.807094@stat.math.ethz.ch>
	<Pine.OSF.4.58.0511151235350.98026@wotan.mdacc.tmc.edu>
Message-ID: <17274.61691.755261.379446@stat.math.ethz.ch>

>>>>> "Paul" == Paul Roebuck <roebuck at mdanderson.org>
>>>>>     on Tue, 15 Nov 2005 13:07:47 -0600 (CST) writes:

    Paul> On Tue, 15 Nov 2005, Martin Maechler wrote:
    >> >>>>> "Paul" == Paul Roebuck <roebuck at mdanderson.org>
    >> >>>>>     on Mon, 14 Nov 2005 15:57:04 -0600 (CST) writes:
    >> 
    Paul> On Mon, 14 Nov 2005, Gabor Grothendieck wrote:
    >> >> On 11/14/05, Paul Roebuck <roebuck at mdanderson.org> wrote:
    >> >>
    >> >> > Was looking at what was output for <pkgname>-package.Rd
    >> >> > and wondered if any there was any means (via macro, etc)
    >> >> > to merge some of the same information with a template
    >> >> > for my package manpage? As much (all?) of the generated
    >> >> > information was already provided in the DESCRIPTION, I'd
    >> >> > prefer not to have to update the information in multiple
    >> >> > places. I'm thinking here that I could provide a template
    >> >> > file "<pkgname>-package.Rd.in" and during build, the
    >> >> > DCF information could be substituted appropriately and
    >> >> > "<pkgname>-package.Rd" would be output.
    >> >> >
    >> >> > see also:
    >> >> >    promptPackage method
    >> >>
    >> >> What I do is make my whatever-package.Rd page be
    >> >> the central page where one can get a list of all
    >> >> the other places one can look for info (rather than
    >> >> placing the info itself there).  See, for example,
    >> >>
    >> >> library(dyn)
    >> >> package?dyn
    >> 
    Paul> Thanks for your reply. That gives me some additional
    Paul> ideas but still think being able to display DCF
    Paul> information and public function listing would be a nice
    Paul> thing to have. For example, 'dyn-package.Rd' repeats its
    Paul> DCF description.
    >> 
    >> which I agree is not ideal.  I agree that such information
    >> should in principle reside in one place and be
    >> ``auto-distributed'' to other places during package installation
    >> and maybe also package load time.
    >> 
    >> Note that packageDescription("dyn") returns an object that
    >> contains (and may print if you want) the DCF information.

    Paul> I'm aware of this, having used it in various places. What
    Paul> I don't know is how to access/use it during package
    Paul> installation (if even possible). Using read.dcf and a sed
    Paul> script, I could probably manage to perform the template
    Paul> merge. But I don't know how to invoke such without adding
    Paul> a configure script (overkill for R-only packages), as
    Paul> 'install.R' is meant for something else.

    >> One possibility I see would be the convention that the
    >> 'generated' (text, html, tex) help files for 'package-<name>'
    >> would combine both the packageDescription() and
    >> the contents of <name>-package.Rd.

    Paul> Well, a system-level approach would be preferable to doing
    Paul> this per-package.

Definitely, and actually I was only thinking of the former.

    Paul>  R-2.3 then?

with help of contributions from smart R-devel
readers/contributors that should be fairly plausible, 
otherwise I'm much less confident.

Martin



[Rd] Package manpage DCF hooks
Martin Maechler