From sean.mcguffee at gmail.com  Sat May 14 01:08:11 2011
From: sean.mcguffee at gmail.com (Sean Robert McGuffee)
Date: Fri, 13 May 2011 19:08:11 -0400
Subject: [Rd] R html help system [Was: How to document man/*.Rd pages
 with images?]
In-Reply-To: <56C958F1-C50C-4ABB-84BB-160207F8F190@r-project.org>
Message-ID: <C9F3321B.41B9%sean.mcguffee@gmail.com>


On 5/12/11 9:13 AM, "Simon Urbanek" <simon.urbanek at r-project.org> wrote:

> I just want to clarify the mechanics of the help system when using html.
> 
> R has a built-in HTTP server (aka Rhttpd) which transforms HTTP requests to
> function calls. It is not your usual web server, because it doesn't map URL
> paths to files, it just allows R functions to do anything with it -- something
> like CGI except that we are talking about functions and not files. Therefore
> you won't find any files and there is no file structure involved.
> 
> For the help system, the function handling the requests is tools:::httpd() -
> you can look at what it does.

Awesome, will do!

> Basically, it generates pages according to the
> various paths it supports. As part of its path handling it allows certain
> paths to reference files, e.g.
> /library/myPackage/doc/randomStuffInPackagesDocDirectory.html will read the
> file doc/randomStuffInPackagesDocDirectory.html in myPackage.
> 
> Note that the whole point of the dynamic help *is* to generate content on the
> fly, because the content depends on the state of your current workspace --
> packages loaded, classes defined, etc. so you cannot pre-generate pages as
> they won't have correct links - that's why we shifted from static html pages
> to the dynamic ones.

This is interesting. It actually speaks to a constructive criticism I have
of R. As a user of R, I don't want to have conditional dynamic help. I want
to always get the same answer to a question so to say. If there is a way to
do something that works and is reproducible, then I don't want to maybe or
maybe not get that answer. Thus, I guess what I'm thinking is that there
should maybe be selection within help that has organization based on
packages loaded and classes defined, but I would hope that the state of my
system doesn't change the help that is displayed. At least I as one user
would prefer to see all of my options will all packages and not have any of
it emphasized or excluded by how my system is currently set up.

In the satus quo, I can see how the choice of which pages to look at is
dynamic if more than one comes up on a search, but it seems inefficient to
me to have the page itself be dynamic. I think it would be a good idea if
package authors could at least have an option to have their help pages
produced as files either way. I mean, when my package will be loaded, I
certainly won't want options and do want to be able to point my users to an
unconditional file location to point their browser to.

> 
> I'm curious about "If it?s a large picture this process nearly crashes my
> machine when trying to access the file via help" - do you have an example
> package that would illustrate the problem?

I?ve tried to recreate the problem with a small fake package, and although
it passes the check it doesn?t seem to work quite right on my system. I
might have some compiler issues or configuration issues though, so it might
work as is on your system. If not, I think you could quickly find the
relevant parts though and add them to a package of your own to see the bug
if this doesn?t work as is on your machine. I?m not really sure why this
doesn?t work on my machine. I did almost exactly the same thing as in the
huge package that I can?t fit on my file transfer site. However, it is set
up to only install in 64-bit and I couldn't remember how I set that up. So
it might be the 32-bit part that is messing things up on my system. I think
there should be a simple way to declare an architecture in a package
DESCRIPTION or something. I can't remember. Anyway, that's beside the point.
Here is an example of a syntax and image file that makes my help go
extremely slow and not show images:

http://ftsext.mskcc.org/FileExchange/FileList.aspx?id=9afb4fe1-ce1c-406d-b1a
1-c9360493137c

Please let me know if you see why this isn?t working for me--both as to if
this works as is on your system and as to if this causes the bug. At the
moment this tells me " Error in gzfile(file, "rb") : cannot open the
connection" even though it passes all the build check install tests on my
machine.

> 
> Thanks,
> Simon
> 
> 
> On May 11, 2011, at 7:14 PM, Sean Robert McGuffee wrote:
> 
>> Thanks everyone for your help,
>> 
>> To summarize a resolution to my issue, it turns out that an image can be
>> include in a documentation file via html by putting an image file in the
>> inst/doc directory, for example inst/doc/myPic.png, and then pointing to it
>> in the man/myHelpPage.Rd file, for example as follows:
>> 
>> \if{html}{
>> \out{<img src="../doc/myPic.png" alt="image ../doc/myPic.png should be
>> here"/>}
>> }\ifelse{latex}{}{}
>> 
>> Note, this doesn?t mean that R?s help browser will view those images inside
>> the properly generated html help files.
>> Also, note that without the \out{} part, the text of the <img .../>  line
>> would show up instead of the html commands.
>>  
>> I have some concerns incase anyone on the list is interested. If it?s a large
>> picture this process nearly crashes my machine when trying to access the file
>> via help?and I?m sure there must be some bug in that. I should note that the
>> picture won?t actually display within R?s help console (at least on my
>> machine--I?m on a mac with a binary version of R). To see that the html files
>> are created properly, I have to copy a link to the help file and then point
>> an actual browser such as firefox to the help file to see the page with the
>> image. I?m not sure how R is running httpd or how that interacts with help.
>> I?m not even sure about the basics of help. Is there a way to configure R to
>> use an actual web browser by default instead of it?s slow one that doesn?t
>> show images? It would also be nice if there were an address bar on R?s help
>> browser. I mean, until I put a link to my help file inside another help file,
>> there was no way for me to even get it?s address to copy and paste into
>> firefox. It would also be nice if it didn?t almost crash and let me more
>> easily get the link, but ideally it would be best not to have a
>> semi-functional help browser. Furthermore, this brings up the point that I
>> can?t find the files I?m browsing with the link. In this case, I get a link
>> such as: 
>> http://127.0.0.1:23269/library/MyPackage/html/MyPackage.html
>> But I can?t find the MyPackage.html file anywhere on my computer. It?s there
>> in the web browser, but seems to be only in existence via R?s httpd without
>> actually existing on my file system.
>> Is it there and I can?t find it or is it encoded in R somehow? If it is
>> there, where would it be? If I close R, I no longer have access to the page
>> that R?s httpd is serving. It seems to me that it?s being created every time
>> I use help?and I think that is extremely inefficient. I think firefox can
>> handle file-type urls, so I if there is a way to get R to both generate these
>> files and use firefox to browse them for help, I would very much like to know
>> more about it. It would be much faster and useful than the status quo on my
>> machine if this file were generated once at installation and remained as a
>> file--and and using help simply pointed a web-browser to the file.
>> Anyway, I suppose this is a tangent. The main point is that there is a way to
>> provide help documentation with images?but even though it tries to view them
>> correctly via help?R?s help browser displays broken images so I have the
>> awkward need to copy and paste links into other web browsers.
>> 
>> Regarding some feedback I?ve gotten about some user?s interests in help
>> formatted as text, I think there are two things in this process that keep a
>> text help user on track: (1) the conditional html part and (2) even if using
>> a textual html browser, <img ... alt=?alternate text?/> take care of
>> displaying images as text. I think though that the other way around, the
>> users who require images in their help files are having less functionality
>> via help in R. At least in this case, the best I could do was get R to
>> generate the proper help pages in html, but R?s default html help browser (at
>> least on my machine) doesn?t display the images (although they are there and
>> can be displayed by the same link in firefox).
>> Sometimes it?s true what they say about a picture being worth a thousand
>> words?I think in general this is true for complex things that need computer
>> power to deal with, so I hope R can eventually support images in help files
>> due to the usefulness of doing so in some cases.
>> 
>> Thanks again,
>> 
>> Sean
> 



[Rd] R html help system [Was: How to document man/*.Rd pages with images?]
Sean Robert McGuffee