Viewing pdfs from inst/doc

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Viewing pdfs from inst/doc

RKoenker
Writing R extensions says:  

In addition to the help files in Rd format, R packages allow the inclusion of documents in arbitrary other formats. The standard location for these is subdirectory inst/doc of a source package, the contents will be copied to subdirectory doc when the package is installed. Pointers from package help indices to the installed documents are automatically created. Documents in inst/doc can be in arbitrary format, however we strongly recommend to provide them in PDF format, such that users on all platforms can easily read them.

My question is easily How?  The function vignette() provides a convenient way to read properly Sweaved
vignettes, but what about plain old pdfs that someone like me would like to stick into inst/doc and
then view?  It seems possible to make a modified vignette function to do this using print.vignette,
but having started down this road, I got the strong sensation of reinventing the wheel and the
inevitably related sensation that I wasn't going to know what to call my new wheel when it was
created.  I recognize that the current setup is supposed to encourage proper vignettes, but sometimes
courage fails.

A related questions is whether there is a convenient substitute for a package specific function like this:
    FAQ <- function (pkg = "quantreg")
          file.show(file.path(system.file(package = pkg), "FAQ"))

to read the faq that I've written for the package and placed in the inst/ directory.
Reply | Threaded
Open this post in threaded view
|

Re: Viewing pdfs from inst/doc

Barry Rowlingson
On Fri, Sep 4, 2009 at 10:44 PM, rudjer<[hidden email]> wrote:

>
> Writing R extensions says:
>
> In addition to the help files in Rd format, R packages allow the inclusion
> of documents in arbitrary other formats. The standard location for these is
> subdirectory inst/doc of a source package, the contents will be copied to
> subdirectory doc when the package is installed. Pointers from package help
> indices to the installed documents are automatically created. Documents in
> inst/doc can be in arbitrary format, however we strongly recommend to
> provide them in PDF format, such that users on all platforms can easily read
> them.
>
> My question is easily How?  The function vignette() provides a convenient
> way to read properly Sweaved
> vignettes, but what about plain old pdfs that someone like me would like to
> stick into inst/doc and
> then view?  It seems possible to make a modified vignette function to do
> this using print.vignette,
> but having started down this road, I got the strong sensation of reinventing
> the wheel and the
> inevitably related sensation that I wasn't going to know what to call my new
> wheel when it was
> created.  I recognize that the current setup is supposed to encourage proper
> vignettes, but sometimes
> courage fails.
>
> A related questions is whether there is a convenient substitute for a
> package specific function like this:
>    FAQ <- function (pkg = "quantreg")
>          file.show(file.path(system.file(package = pkg), "FAQ"))
>
> to read the faq that I've written for the package and placed in the inst/
> directory.

 I think I tried to do this a little while ago, and trawling R-help
and R-dev came up with the suggestion of putting something in a demo
section. Hence I have foo/demo/bar.R which is:

pdf = system.file("doc/bar.pdf",package="foo")

if (.Platform$OS.type == "windows") {
  shell.exec(pdf)
}else{
  system(paste(shQuote(getOption("pdfviewer")), shQuote(pdf)),
            wait = FALSE)
}

 Then when a user does demo(bar) the PDF pops up. I document this in
the Rd doc for bar.

 It does seem a bit kludgy, and maybe there's a need for a package to
handle all this...

Barry

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Viewing pdfs from inst/doc

Romain Francois
On 09/04/2009 11:58 PM, Barry Rowlingson wrote:

>
> On Fri, Sep 4, 2009 at 10:44 PM, rudjer<[hidden email]>  wrote:
>>
>> Writing R extensions says:
>>
>> In addition to the help files in Rd format, R packages allow the inclusion
>> of documents in arbitrary other formats. The standard location for these is
>> subdirectory inst/doc of a source package, the contents will be copied to
>> subdirectory doc when the package is installed. Pointers from package help
>> indices to the installed documents are automatically created. Documents in
>> inst/doc can be in arbitrary format, however we strongly recommend to
>> provide them in PDF format, such that users on all platforms can easily read
>> them.
>>
>> My question is easily How?  The function vignette() provides a convenient
>> way to read properly Sweaved
>> vignettes, but what about plain old pdfs that someone like me would like to
>> stick into inst/doc and
>> then view?  It seems possible to make a modified vignette function to do
>> this using print.vignette,
>> but having started down this road, I got the strong sensation of reinventing
>> the wheel and the
>> inevitably related sensation that I wasn't going to know what to call my new
>> wheel when it was
>> created.  I recognize that the current setup is supposed to encourage proper
>> vignettes, but sometimes
>> courage fails.
>>
>> A related questions is whether there is a convenient substitute for a
>> package specific function like this:
>>     FAQ<- function (pkg = "quantreg")
>>           file.show(file.path(system.file(package = pkg), "FAQ"))
>>
>> to read the faq that I've written for the package and placed in the inst/
>> directory.
>
>   I think I tried to do this a little while ago, and trawling R-help
> and R-dev came up with the suggestion of putting something in a demo
> section. Hence I have foo/demo/bar.R which is:
>
> pdf = system.file("doc/bar.pdf",package="foo")
>
> if (.Platform$OS.type == "windows") {
>    shell.exec(pdf)
> }else{
>    system(paste(shQuote(getOption("pdfviewer")), shQuote(pdf)),
>              wait = FALSE)
> }
>
>   Then when a user does demo(bar) the PDF pops up. I document this in
> the Rd doc for bar.
>
>   It does seem a bit kludgy, and maybe there's a need for a package to
> handle all this...
>
> Barry

print.vignette knows that it needs to factor out the "open a pdf file"
part, see the <FIXME> section :

 > utils:::print.vignette
function(x, ...){

     if(length(x$pdf)){
         ## <FIXME>
         ## Should really abstract this into a BioC style
         ## openPDF() along the lines of browseURL() ...
         if(.Platform$OS.type == "windows")
             shell.exec(x$pdf)
         else
             system(paste(shQuote(getOption("pdfviewer")), shQuote(x$pdf)),
                    wait = FALSE)
         ## </FIXME>
     } else {
         warning(gettextf("vignette '%s' has no PDF", x$topic),
                 call. = FALSE, domain = NA)
     }
     invisible(x)
}
<environment: namespace:utils>


You can trick the system using something like this :

fake.vignette <- function( file = system.file( "doc", vignette, package
= package ), vignette, package, topic = vignette ){
        structure( pdf = file, topic = topic, class = "vignette" )
}

Romain

--
Romain Francois
Professional R Enthusiast
+33(0) 6 28 91 30 30
http://romainfrancois.blog.free.fr
|- http://tr.im/xMdt : update on the ant package
|- http://tr.im/xHLs : R capable version of ant
`- http://tr.im/xHiZ : Tip: get java home from R with rJava

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Viewing pdfs from inst/doc

RKoenker
Thanks Romain and Barry for help with this.  I've written a faux.vignette
function somewhat  along the lines of Romain's suggestion.  


Roger Koenker