R devel - Jul 2009 - problem with internal functions in Windows

Dear R users,
 
I included 2 internal functions in the package 'dlnm', called
'mkbasis' and 'mklagbasis'.
Despite they are not meant to be called by the users, I included them in the
namespace in order to make them available, keeping the process more transparent
and giving the opportunity to change or improve them.
 
I included an help page 'dlnm-internal.Rd' to document them, and some
examples in a package vignette I want to add.
The problem is that the link to this help page doesn't work in the version
installed by the CRAN (eg. try ?mkbasis).
I checked the help pages for internal functions in other packages: some of them
work (e.g. ?geepack::anova.geeglm), others don't (e.g. ?gam::.First.lib).
 
Any suggestions?
Thanks for your time
 
Antonio Gasparrini
Public and Environmental Health Research Unit (PEHRU)
London School of Hygiene & Tropical Medicine
Keppel Street, London WC1E 7HT, UK
Office: 0044 (0)20 79272406 - Mobile: 0044 (0)79 64925523
Skype contact: a.gasparrini

This is more of an r-devel topic, so I've sent my reply there.

On 06/07/2009 6:50 AM, Antonio.Gasparrini at lshtm.ac.uk
wrote:
> Dear R users,
>  
> I included 2 internal functions in the package 'dlnm', called
'mkbasis' and 'mklagbasis'.
> Despite they are not meant to be called by the users, I included them in
the namespace in order to make them available, keeping the process more
transparent and giving the opportunity to change or improve them.
The usual reason to make something an internal function is so that you 
feel no obligation to maintain the interface.  If it is in the 
NAMESPACE, you should feel guilty whenever you make incompatible changes.

Another reason to keep them internal is that they don't really fit with 
the goals of your package:  they are just a distraction.  You don't want 
people to use your package just for those things.  (This is actually the 
same reason as the first: the reason you don't want your package to be 
used for some little utility function is that you would drop it if it 
showed up in a base package.)

So if you think those functions are useful and on target, and you don't 
foresee changing them, then exporting them is reasonable.
> I included an help page 'dlnm-internal.Rd' to document them, and
some examples in a package vignette I want to add.
> The problem is that the link to this help page doesn't work in the
version installed by the CRAN (eg. try ?mkbasis).
> I checked the help pages for internal functions in other packages: some of
them work (e.g. ?geepack::anova.geeglm), others don't (e.g.
?gam::.First.lib).
>  
> Any suggestions?
Did you set aliases in the help pages?  Those are what help uses to find 
the page.

And what OS and R version are you using?  ?gam::.First.lib works for me 
(on Windows, with 2.9.0 or 2.9.1 patched).

Duncan Murdoch

On 7/6/2009 8:23 AM, Antonio.Gasparrini at lshtm.ac.uk
wrote:
> 
> I kept those functions as internal because users don't need to call
them
> directly to use all the functionalities of the package (they are called 
> by other functions).
> Nonetheless, I want to make them available and documented because they 
> can give an idea about the process to specify the other functions.
>  
> The package is called 'dlnm' (available in the CRAN), the two
internal
> functions are 'mkbasis' ans 'mklagbasis', included as
aliases in
> 'dlnm-internal.Rd'.
> But the link ?mkbasis typed in R returns "The page cannot be
displayed".
> I tried in 3 different machines (with both Vista and XP, R version 
> 2.9.1), but I got the same result.
> The strange thing is that everything is working when, instead than the 
> CRAN version, I install the .zip file with he binaries I create with my 
> machine.
I have no problem with ?mkbasis in the text or HTML display, but it 
fails in the CHM help display.  When I look at the .chm file on CRAN, I 
don't see the dlnm-internals topic.  I'll see if I can spot what's
going
wrong...

Duncan Murdoch

>  
> I hope this helps.
> Antonio Gasparrini
> 
>  >>> Duncan Murdoch <murdoch at stats.uwo.ca> 06/07/2009
12:13 >>>
> This is more of an r-devel topic, so I've sent my reply there.
> 
> On 06/07/2009 6:50 AM, Antonio.Gasparrini at lshtm.ac.uk wrote:
>  > Dear R users,
>  > 
>  > I included 2 internal functions in the package 'dlnm', called
> 'mkbasis' and 'mklagbasis'.
>  > Despite they are not meant to be called by the users, I included them
> in the namespace in order to make them available, keeping the process 
> more transparent and giving the opportunity to change or improve them.
> 
> The usual reason to make something an internal function is so that you
> feel no obligation to maintain the interface.  If it is in the
> NAMESPACE, you should feel guilty whenever you make incompatible changes.
> 
> Another reason to keep them internal is that they don't really fit with
> the goals of your package:  they are just a distraction.  You don't
want
> people to use your package just for those things.  (This is actually the
> same reason as the first: the reason you don't want your package to be
> used for some little utility function is that you would drop it if it
> showed up in a base package.)
> 
> So if you think those functions are useful and on target, and you don't
> foresee changing them, then exporting them is reasonable.
> 
>  > I included an help page 'dlnm-internal.Rd' to document them,
and some
> examples in a package vignette I want to add.
>  > The problem is that the link to this help page doesn't work in
the
> version installed by the CRAN (eg. try ?mkbasis).
>  > I checked the help pages for internal functions in other packages: 
> some of them work (e.g. ?geepack::anova.geeglm), others don't (e.g. 
> ?gam::.First.lib).
>  > 
>  > Any suggestions?
> 
> Did you set aliases in the help pages?  Those are what help uses to find
> the page.
> 
> And what OS and R version are you using?  ?gam::.First.lib works for me
> (on Windows, with 2.9.0 or 2.9.1 patched).
> 
> Duncan Murdoch