[R] user library help functionality (packages.html)

[Jarrett Barber]

Whoops!  Yes, my last "help.search()" should have been  
"help.start()".  Thanks again.  -- Jarrett

On Jan 15, 2009, at 1:27 PM, Duncan Murdoch wrote:

> On 1/15/2009 3:17 PM, Jarrett Barber wrote:
>> This helps a lot.  I have options(htmlhelp=TRUE) and   
>> options(chmhelp=FALSE) (else problems).  Now, ?, help(), and   
>> help.search() seem to work well.  But, help.start() appears  
>> restricted  to packages in the site library.  I see, in the Help/ 
>> FAQ on R for  Windows/ Sections 4.3 and 4.4, that I cannot expect  
>> more from  help.start() unless I have write permission to $RHOME/ 
>> library, which I  do not (package does have a CONTENTS file  
>> however).  I assume that, if  I want my students to have this  
>> functionality, they, too, would need  write access to $RHOME/ 
>> library, correct?  But, this does not seem a  wise thing to give.   
>> Am I missing something here, barring permission  changes, that  
>> would allow help.search() to see user libraries?
>
> You mean help.start() here, don't you?  help.search() does see  
> everything in the libraries listed in .libPaths().
>
>
> This
>> would be ideal, but your suggestions seems to give us nice help   
>> functionality, and I think we can implement an R installation  
>> campus- wide without the full functionality of help.seach().   
>> Thanks very much.
>
> As far as I know on Windows there's currently no way to get  
> help.start() to go to a personalized page.  The stuff that it refers  
> to all lives in RHOME/doc/html, and many of the links in the files  
> it works with assume that they are installed in the same hierarchy.
>
> I'm not sure if things are different on Unix, where we use soft  
> links to make all the package directories appear to be under one  
> parent.
>
> Duncan Murdoch
>
>> Jarrett
>> R Session:
>> R version 2.7.0 (2008-04-22)
>> ...snip...
>> > personalLib<- .libPaths()[1]; personalLib
>> [1] "H:\\Desktop\\RFiles\\Library"
>> > getOption("htmlhelp")
>> [1] TRUE
>> > getOption("chmhelp")
>> [1] FALSE
>> > install.packages("UsingR",
>> + lib=personalLib,
>> + depend=TRUE)
>> trying URL 'http://streaming.stat.iastate.edu/CRAN/bin/windows/contrib/2.7/UsingR_0.1-10.zip'
>> Content type 'application/zip' length 1433201 bytes (1.4 Mb)
>> opened URL
>> downloaded 1.4 Mb
>> package 'UsingR' successfully unpacked and MD5 sums checked
>> The downloaded packages are in
>>         C:\Temp\RtmpQr4t3E\downloaded_packages
>> updating HTML package descriptions
>> Warning message:
>> In file.create(f.tg) :
>>   cannot create file 'C:\PROGRA~1\R\R-27~1.0/doc/html/ 
>> packages.html',  reason 'Permission denied'  ## PERMISSION PROBLEM
>> > library("UsingR")
>> Warning message:
>> package 'UsingR' was built under R version 2.7.2
>> > help("UsingR") ## works!
>> Help for ëUsingRí is shown in the browser
>> > help.start() ## restricted to site library
>> updating HTML package listing
>> updating HTML search index
>> fixing URLs in non-standard libraries
>> If nothing happens, you should open 'C:\PROGRA~1\R\R-27~1.0\doc 
>> \html \index.html' yourself
>> Warning message:
>> In file.create(f.tg) :
>>   cannot create file 'C:\PROGRA~1\R\R-27~1.0/doc/html/ 
>> packages.html',  reason 'Permission denied' ## SAME PERMISSION  
>> PROBLEM
>> > help.search("UsingR") ## works!
>> > ?UsingR ## works!
>> Help for ëUsingRí is shown in the browser
>> > q()
>> On Jan 15, 2009, at 11:42 AM, Duncan Murdoch wrote:
>>> On 1/15/2009 12:50 PM, Jarrett Barber wrote:
>>>> Here's another help file question.
>>>> Some context: University setting wherein R is installed for    
>>>> availability to students and course instructors across campus  
>>>> in   various PC labs.  Windows Vista environment.
>>>> Goal: To maximize flexibility and functionality of installing  
>>>> add- on  packages and associated help files among different  
>>>> users,  while  avoiding conflicts across different user  
>>>> libraries.  (I  could have my  difficult-to-access sysadmin  
>>>> install _all_  libraries, but this seems  wasteful, and would  
>>>> seem to present  problems when my colleague or I  want to update  
>>>> a package or  install a newly available package but do  not have  
>>>> time to wait a  week or two for our sysadmin.)
>>>> Problem (?): As a course instructor, I want flexibility to  
>>>> install  add- on libraries to a user (not site) library, and I  
>>>> don't want to  step on  my colleagues' toes (or vice-versa) when  
>>>> it comes to add- on packages  and associated help files for use  
>>>> in classes.  I have  no problem  installing add-on packages to a  
>>>> user library, with one  exception: I do  not have permission to  
>>>> update the file $RHOME/doc/ html/packages.html,  as evidenced by  
>>>> a permission error upon  installing a package to a user  library  
>>>> using update.packages (not  to the default site library, which   
>>>> is also restricted).  The  installed add-on packages work fine,  
>>>> with  the exception of some of  the help functionality.  I find  
>>>> myself having  to use browseURL()  to point to the html files in  
>>>> the package's file  structure.  I  cannot expect the average  
>>>> student (or senior colleague)  to  tolerate this situation.
>>>
>>> A simpler way to get to the HTML man pages is to run
>>>
>>> options(htmlhelp=TRUE)
>>>
>>> and then the regular ?topic or help("topic") will find the HTML  
>>> help  pages in your local library.
>>>
>>>> I'm thinking that I simply need to have my sysadmin give me and  
>>>> my   colleagues (all users who want to install add-ons  
>>>> packages?)   permission to read/write packages.html, and the  
>>>> problem will go  away.   But, before I ask my sysadmin to give  
>>>> permission, I want to  know, does  this create another problem?   
>>>> For example, my colleague  creates a  library for STAT3000BC,  
>>>> which, I assume, will modify  packages.html  (assuming my  
>>>> sysadmin gives permission), then I  create a library for   
>>>> STAT2010, which also modifies packages.html.   See my concern?   
>>>> Does R  somehow allow harmonious help  functionality in such  
>>>> cases (by, for  example, maintaining separate  copies of  
>>>> packages.html for different  users)?
>>>
>>> You will likely have strange problems if you do that.  The doc/ 
>>> html/ packages.html file is intended to talk about what is  
>>> available to  everyone; I suspect in your scenario, it would be  
>>> updated to show  your packages (but not your colleague's) whenever  
>>> you added one, and  then updated to show your colleague's packages  
>>> (but not yours) when  he added one, and would almost never be  
>>> right for both of you.
>>>
>>> The good news is that it looks as though sometime this year we  
>>> will  make quite substantial changes to the way the help system is  
>>> stored,  so a lot of things like packages.html could be generated  
>>> on the fly.
>>>
>>> Duncan Murdoch
>