[Rd] Links to non-vignette documentation

[Berwin A Turlach]

G'day all,

seems as if I must have slept through most of this most interesting
discussion. :)

>>>>> "BR" == Prof Brian Ripley <ripley at stats.ox.ac.uk> writes:

    BR> On Thu, 23 Feb 2006, hadley wickham wrote:
    >> How can I write an index file with a pointer to my pdf?  Should
    >> I provide a code snippet to run
    >> system(paste(getOption("pdfviewer"), system.file("doc/my.pdf",
    >> package="mypackage"), "&"))?
    BR> Just add a hyperlink in inst/doc/index.html to foo.pdf and let
    BR> the browser do the rest.  The grid/doc/index.html is a
    BR> suitable template.
Editing this file by hand is certainly an option, but one more think
to remember while maintaining a package.  Thus, I think it is
preferable to automate process as much as possible.  I ran into a
similar problem as Hadley with a package that I am currently developing
(since some time) and offer my solution below.

>>>>> "DM" == Duncan Murdoch <murdoch at stats.uwo.ca> writes:

    DM> On 2/23/2006 4:23 PM, hadley wickham wrote:
    >> What about (eg.) help(package=grid)?  This is where vignettes
    >> are listed by name (and location).  I would like to be able put
    >> my pdf into a similar list.
    DM> I don't think you can do that, but you should be using a
    DM> package man page anyway.
I believe this can be done, albeit not directly.

In my case, I wanted to include a PDF, whose source is not in Sweave
format, with the documentation of the package and have the links to
this documentation created automatically.  My solution, in the end was
to create a "dummy" Rnw vignette which has a link to the pdf file.  I
include that dummy vignette below.  Hence, in the directory inst/doc
of my package there are the following files:
    interface96.pdf             The PDF file I actually want to include
                                as part of the documentation
    interface96-vignette.Rnw    The dummy vignette file
Using hyperref with a "file:" url, the dummy vignette file links to
the actual files.

For the user, this means that she/he sees the dummy vignette and
access it first and then has to click once more on a link to get to
the actual document.  Slightly inconvenient for the user, but I
believe it is a fair price to pay to make my life as developer
easier. ;-))

If you want to distribute binary copies (e.g. for the various version
of Windows that exists) of your package, then you need of course all
the tools that are necessary to handle vignettes.

Cheers,

        Berwin

------------------------- Source of dummy vignette -------------------------
\documentclass[a4paper]{article}
%\VignetteIndexEntry{Interface '96 paper by Marron et al. (1997)}
%\VignettePackage{clps}

\usepackage{hyperref}
\usepackage{natbib}

\title{Interface '96 paper by \cite{mar:tur:wan:96}}
\author{Berwin A Turlach}
\date{September 25, 2004}

\begin{document}
\maketitle

This is just a dummy vignette with a link to the 
\href{file:interface96.pdf}{PDF file} of \cite{mar:tur:wan:96} which
is part of the \textit{CLPS} package.  The dummy vignette should
appear in the automatically generated index, but I did not succeed in
getting the actual paper to appear in that index.

\bibliographystyle{dcunsp}
\bibliography{clps}

\end{document}