[Rd] [R] problem with internal functions in Windows

[Duncan Murdoch]

On 7/6/2009 9:30 AM, Duncan Murdoch wrote:
> 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...

I have found the problem.  R never lists topics that are marked as 
internal in the HTML index, but normally it includes their aliases in 
the internal index it uses for those.  However, CHM help doesn't make 
use of that file, it uses the HTML index as the root for finding what 
files to include in the .chm output.  Since internal pages aren't listed 
there, it won't include the corresponding help page, and you get the 
"cannot be displayed" message.

I'll see if there's another way to include the page.

Duncan Murdoch

> 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
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel