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

[Jarrett Barber]

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

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