Links to non-vignette documentation

Section 1.4 of 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.

Where are these pointers created?  I have a package with a pdf file
(introduction.pdf) in inst/doc but I can't find a link to it from the
documentation (eg. from help.start() or help(package=...)

Is there anyway to have my pdf documentation listed under vignettes
other than making it a sweave file?

A manually written inst/doc/index.html file will be linked into the help 
system.

I don't know if the sentence about pointers being created is true otherwise.

Duncan Murdoch

On 2/23/2006 11:53 AM, hadley wickham wrote:

Section 1.4 of 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.

Where are these pointers created?  I have a package with a pdf file
(introduction.pdf) in inst/doc but I can't find a link to it from the
documentation (eg. from help.start() or help(package=...)

Is there anyway to have my pdf documentation listed under vignettes
other than making it a sweave file?

No, a vignette is regarded as an Sweave file.

A manually written inst/doc/index.html file will be linked into the help
system.

.install_package_vignette_index does create an index, and info does get 
put on the packages html page.

I just tried this by adding inst/doc/foo.pdf to windlgs.  If there is an 
pdf file but no .[RS]nw vignettes, the index is fairly useless but 
browsing is available.

I don't know if the sentence about pointers being created is true otherwise.

It seems to be.

Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

Is there anyway to have my pdf documentation listed under vignettes
other than making it a sweave file?

No, a vignette is regarded as an Sweave file.

It would be useful if there was a mechanism to allow arbitrary pdf
files to be included as vignettes.  There are many other ways to
include R code/output in pdf files other than through Sweave.

I just tried this by adding inst/doc/foo.pdf to windlgs.  If there is an
pdf file but no .[RS]nw vignettes, the index is fairly useless but
browsing is available.

I don't know if the sentence about pointers being created is true otherwise.

It seems to be.

A link to the directory where the pdf is located, only available in
the html version of help, rather stretches the definition of a
pointer.

Hadley

Is there anyway to have my pdf documentation listed under vignettes
other than making it a sweave file?

No, a vignette is regarded as an Sweave file.

It would be useful if there was a mechanism to allow arbitrary pdf
files to be included as vignettes.  There are many other ways to
include R code/output in pdf files other than through Sweave.

I think you need to define `vignette'.  I understand the usage to mean an
Sweave file.  There are ways to include other PDF files, and you can write 
your own index file.  R can't do that for you as it cannot read PDF (it 
can read Sweave).

I just tried this by adding inst/doc/foo.pdf to windlgs.  If there is an
pdf file but no .[RS]nw vignettes, the index is fairly useless but
browsing is available.

I don't know if the sentence about pointers being created is true otherwise.

It seems to be.

A link to the directory where the pdf is located, only available in
the html version of help, rather stretches the definition of a
pointer.

What is a link if not a pointer?  What it actually says is

    Pointers from package help indices to the installed
    documents are automatically created.

I am not aware of any other sort of `package help index', although one 
could arge the toss about Compiled HTML.

Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

I think you need to define `vignette'.  I understand the usage to mean an
Sweave file.  There are ways to include other PDF files, and you can write
your own index file.  R can't do that for you as it cannot read PDF (it
can read Sweave).

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"), "&"))?

Perhaps my problem is thinking of a vignette as a "A brief verbal
description of a person, place, etc.; a short descriptive or evocative
episode in a play, etc." rather than a Sweave document.

I am not aware of any other sort of `package help index', although one
could arge the toss about Compiled HTML.

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.

Hadley

I think you need to define `vignette'.  I understand the usage to mean an
Sweave file.  There are ways to include other PDF files, and you can write
your own index file.  R can't do that for you as it cannot read PDF (it
can read Sweave).

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"), "&"))?

Just add a hyperlink in inst/doc/index.html to foo.pdf and let the browser 
do the rest.  The grid/doc/index.html is a suitable template.

Perhaps my problem is thinking of a vignette as a "A brief verbal
description of a person, place, etc.; a short descriptive or evocative
episode in a play, etc." rather than a Sweave document.

I am not aware of any other sort of `package help index', although one
could arge the toss about Compiled HTML.

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.

Which is really library(help=grid).  Vignettes there are a recent 
addition, and we need the author to tell us.  It looks to me as if that 
means strict-sense vignettes (it gets the info from the vignette 
metadata).  If there were a mechanism for authors to list PDF docs and 
titles in a two-column format in some file in inst/docs, the installation 
tools could provide more support.  (I think this is Kurt's area.)

[I am not arguing that this could not be better documented, but I think 
most things are possible by digging around.]

Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

I think you need to define `vignette'.  I understand the usage to mean an
Sweave file.  There are ways to include other PDF files, and you can write
your own index file.  R can't do that for you as it cannot read PDF (it
can read Sweave).

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"), "&"))?

We were referring to an HTML index file.  If you want to have a 
reference from your package man page (foo-package.Rd) or some other man 
page, you can use \url{../doc/my.pdf} and the link will work in HTML 
versions of help, and won't be too misleading in other versions 
(especially if you explain how to use it).

Perhaps my problem is thinking of a vignette as a "A brief verbal
description of a person, place, etc.; a short descriptive or evocative
episode in a play, etc." rather than a Sweave document.

I am not aware of any other sort of `package help index', although one
could arge the toss about Compiled HTML.

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.

I don't think you can do that, but you should be using a package man 
page anyway.

Duncan Murdoch

We were referring to an HTML index file.  If you want to have a
reference from your package man page (foo-package.Rd) or some other man
page, you can use \url{../doc/my.pdf} and the link will work in HTML
versions of help, and won't be too misleading in other versions
(especially if you explain how to use it).

Ok, I'll give that a go.

I don't think you can do that, but you should be using a package man
page anyway.

Can you suggest a good example of a package man page?  I've tried a
few packages and haven't been able to find one.  The example generated
by promptPackage suggests I need to duplicate the contents of
DESCRIPTION and INDEX.

Hadley

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:

>> 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:

>> 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}

We were referring to an HTML index file.  If you want to have a
reference from your package man page (foo-package.Rd) or some other man
page, you can use \url{../doc/my.pdf} and the link will work in HTML
versions of help, and won't be too misleading in other versions
(especially if you explain how to use it).

Ok, I'll give that a go.

I don't think you can do that, but you should be using a package man
page anyway.

Can you suggest a good example of a package man page?  I've tried a
few packages and haven't been able to find one.  The example generated
by promptPackage suggests I need to duplicate the contents of
DESCRIPTION and INDEX.

All of the base packages have them; some contain more than others.  I 
don't know which ones I'd consider to be "good".

They are meant to replace the INDEX, which you shouldn't need to create 
any more.  The DESCRIPTION file is still needed, but it contains more 
structured information meant for mechanical reading and processing; the 
package man page is meant to be the place to put things intended for 
people to read.

Duncan Murdoch

They are meant to replace the INDEX, which you shouldn't need to create
any more.  The DESCRIPTION file is still needed, but it contains more
structured information meant for mechanical reading and processing; the
package man page is meant to be the place to put things intended for
people to read.

Do I need to keep the list of functions on the package man page in
sync myself, or will they be automatically rebuilt?  Is the intention
to eventually change help(package=XXX) to point to the package man
page?

Hadley

I haven't followed this whole thread but note that if your
package is called mypkg then you can create an .Rd
file called mypkg-package.Rd which will be called up
when the user issues:

package?mypkg

and that can contain links to whatever you are
interested in.

Try

library(dyn)
package?dyn

for an example.  The R command, promptPackage, can be
used to facilitate the creation of the -package.Rd file.

They are meant to replace the INDEX, which you shouldn't need to create
any more.  The DESCRIPTION file is still needed, but it contains more
structured information meant for mechanical reading and processing; the
package man page is meant to be the place to put things intended for
people to read.

Do I need to keep the list of functions on the package man page in
sync myself, or will they be automatically rebuilt?  Is the intention
to eventually change help(package=XXX) to point to the package man
page?

Hadley

______________________________________________
R-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

They are meant to replace the INDEX, which you shouldn't need to create
any more.  The DESCRIPTION file is still needed, but it contains more
structured information meant for mechanical reading and processing; the
package man page is meant to be the place to put things intended for
people to read.

Do I need to keep the list of functions on the package man page in
sync myself, or will they be automatically rebuilt?  Is the intention
to eventually change help(package=XXX) to point to the package man
page?

No, there's no automatic building after the promptPackage call.  It's up 
to you to decide which functions need to be mentioned to users.  In 
large packages it usually doesn't make sense to list all the functions, 
so the package writer needs to use judgement here.  There are other 
mechanisms (e.g. ls("package:XXX") for a list of names, the help index 
generation for a list of names and titles) to get a list of everything.

There aren't any immediate plans to change help(package=XXX), but I 
think in the long run, if package?XXX receives wider support than it has 
now, it would make sense to make that change.

Duncan Murdoch

Le 24.02.2006 01:26, Berwin A Turlach a ?crit :

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}
  

Hi,

What about using the latex package pdfpages to copy the pages from your 
PDF file `interface96.pdf` to your Sweave file. (I don't know if it is 
compatible with Sweave).

Not tested :

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

\usepackage{hyperref}
\usepackage{natbib}
\usepackage{pdfpages}

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

\begin{document}
\maketitle

\newpage

\includepdf{interface96.pdf}


\bibliographystyle{dcunsp}
\bibliography{clps}

\end{document}


Romain

visit the R Graph Gallery : http://addictedtor.free.fr/graphiques
Discover the R Movies Gallery : http://addictedtor.free.fr/movies
+---------------------------------------------------------------+
| Romain FRANCOIS - http://francoisromain.free.fr               |
| Doctorant INRIA Futurs / EDF                                  |
+---------------------------------------------------------------+

What about using the latex package pdfpages to copy the pages from your 
PDF file `interface96.pdf` to your Sweave file. (I don't know if it is 
compatible with Sweave).

Not tested :

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

\usepackage{hyperref}
\usepackage{natbib}
\usepackage{pdfpages}

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

\begin{document}
\maketitle

\newpage

\includepdf{interface96.pdf}


\bibliographystyle{dcunsp}
\bibliography{clps}

\end{document}

That's a nice hack.  You probably want the "fitpaper" option on the 
\includepdf command, so that you don't get an extra border around the 
page.  For example, this file test.Rnw

\documentclass{article}
%\VignetteIndexEntry{test include of pdf}
%\VignettePackage{ellipse}

\usepackage{pdfpages}

\begin{document}

\includepdf[fitpaper=true]{response.pdf}

\end{document}

produces an output that looks pretty much exactly like the 
"response.pdf" file I used as test input in a viewer.

The only disadvantages I see are that both the test.pdf and response.pdf 
files got built into the package (but only test.pdf shows up in the 
index), and that test.pdf is a lot larger than response.pdf.  (This may 
be because response.pdf was small; I haven't checked if the increase is 
additive or multiplicative).

For a non-hack solution:

A change to the R package build process would be to add support for a 
command like

%\VignetteExists

to the test.Rnw file, telling R not to bother trying to build the pdf, 
because it had already been built by other means.  Then I'd just have 
test.Rnw containing

%\VignetteIndexEntry{test include of pdf}
%\VignettePackage{ellipse}
%\VignetteExists

and solve both of the problems with Romain's workaround.

Duncan Murdoch

No, there's no automatic building after the promptPackage call.  It's up
to you to decide which functions need to be mentioned to users.  In
large packages it usually doesn't make sense to list all the functions,
so the package writer needs to use judgement here.  There are other
mechanisms (e.g. ls("package:XXX") for a list of names, the help index
generation for a list of names and titles) to get a list of everything.

Ok, that seems reasonable, but perhaps promptPackage (or
documentation) could make this more clear.

There aren't any immediate plans to change help(package=XXX), but I
think in the long run, if package?XXX receives wider support than it has
now, it would make sense to make that change.

When was this form of package documentation created?  How are users
supposed to know it exists?  I couldn't find any pointers to it from
?help, ?library or from help(package=XXX).

Hadley

<snipped>

\usepackage{pdfpages}

<snipped>

That's a nice hack.  You probably want the "fitpaper" option on the 
\includepdf command, so that you don't get an extra border around the 
page.  For example, this file test.Rnw

<snipped>

The only disadvantages I see are that both the test.pdf and response.pdf 
files got built into the package (but only test.pdf shows up in the 
index), and that test.pdf is a lot larger than response.pdf.  (This may 
be because response.pdf was small; I haven't checked if the increase is 
additive or multiplicative).

<snipped>

I like pdfpages and do use it from time to time (as frequently as
every couple of weeks for filling expense/travel/claim forms) -
but in fact it isn't shipped with tetex 1.0 and is not in the
site-wise LaTeX installation in my work location.
(and luckily I am not using the site-wise one...). I checked and
pdfpages was added to tetex in Oct 2001 and is in tetex 2.0 which
was released in feb 2003; but sites could be slow in upgrading...
so such constructions would break on sites which hasn't upgraded
their LaTeX installation in the last 3 years.

HTL

No, there's no automatic building after the promptPackage call.  It's up
to you to decide which functions need to be mentioned to users.  In
large packages it usually doesn't make sense to list all the functions,
so the package writer needs to use judgement here.  There are other
mechanisms (e.g. ls("package:XXX") for a list of names, the help index
generation for a list of names and titles) to get a list of everything.

Ok, that seems reasonable, but perhaps promptPackage (or
documentation) could make this more clear.

There aren't any immediate plans to change help(package=XXX), but I
think in the long run, if package?XXX receives wider support than it has
now, it would make sense to make that change.

When was this form of package documentation created?  How are users
supposed to know it exists?  I couldn't find any pointers to it from
?help, ?library or from help(package=XXX).

It's described in the Writing R Extensions Manual, in Writing R 
Documentation Files, Rd Format, Documenting Packages (section 2.1.4 in 
the PDF).

There probably should be more pointers to it...

Duncan Murdoch

G'day all,

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

>> 
    >> What about using the latex package pdfpages to copy the pages from your 
    >> PDF file `interface96.pdf` to your Sweave file. 
Merci beaucoup, I wasn't aware that this style file exists, it
definitely seems to be useful.

    DM> That's a nice hack.  You probably want the "fitpaper" option on the 
    DM> \includepdf command, so that you don't get an extra border around the 
    DM> page.  For example, this file test.Rnw [...]

    DM> \includepdf[fitpaper=true]{response.pdf}
Additionally, if response.pdf has several pages and you want to
include them all, you should also include a "pages" options, such as:

        \includepdf[fitpaper=true,pages=-]{interface96.pdf}

More details can be found in the pdfpages documentation, but by
default only the first page is included.

    DM> produces an output that looks pretty much exactly like the 
    DM> "response.pdf" file I used as test input in a viewer.
Perhaps interface96.pdf was created too long ago (it says PDF 1.2 at
the top of that file), but the result looks strange in xpdf (the
included pages are quite small and in the upper left corner, selecting
"fit to page" creates an acceptable viewing results); no problem with
acroread.  This is on a linux box.

    DM> The only disadvantages I see are that both the test.pdf and
    DM> response.pdf files got built into the package (but only
    DM> test.pdf shows up in the index),
That is a potential disadvantage as it duplicates material.  But I
guess .Rbuildignore in the main directory of the package can help in
this case.  I have put the line "inst/doc/interface96.pdf" into the
.Rbuildignore file of that package.

    DM> and that test.pdf is a lot larger than response.pdf.  (This
    DM> may be because response.pdf was small; I haven't checked if
    DM> the increase is additive or multiplicative).
I didn't check this either, but here are some results on including a 6
page pdf file (extracts from looking at the .tar.gz file produced by
the build process).  First, the old solution with a separate PDF file
and a dummy vignette:

 drwxr-xr-x  berwin/berwin        0 clps/inst/
 drwxr-xr-x  berwin/berwin        0 clps/inst/doc/
 -rw-r--r--  berwin/berwin      649 clps/inst/doc/clps.bib
 -rw-r--r--  berwin/berwin      670 clps/inst/doc/interface96-vignette.Rnw
 -rw-r--r--  berwin/berwin   105035 clps/inst/doc/interface96.pdf
 -rw-r--r--  berwin/berwin    49242 clps/inst/doc/interface96-vignette.pdf
 
Second, with \includepdf and .Rbuildignore:

 drwxr-xr-x  berwin/berwin        0 clps/inst/
 drwxr-xr-x  berwin/berwin        0 clps/inst/doc/
 -rw-r--r--  berwin/berwin      649 clps/inst/doc/clps.bib
 -rw-r--r--  berwin/berwin      440 clps/inst/doc/interface96-vignette.Rnw
 -rw-r--r--  berwin/berwin   191589 clps/inst/doc/interface96-vignette.pdf

Looks like an increase of about 40 kB to me which I would find acceptable.

    DM> A change to the R package build process would be to add support for a 
    DM> command like

    DM> %\VignetteExists

    DM> to the test.Rnw file, telling R not to bother trying to build the pdf, 
    DM> because it had already been built by other means.  Then I'd just have 
    DM> test.Rnw containing
Searching the "Writing R Extensions" manual for vignette, I noticed
the following:

      Unless @kbd{R CMD build} is invoked with the
      @option{--no-vignettes} option, it will attempt to rebuild the
      vignettes (@pxref{Writing package vignettes}) in the package.
      To do so it installs the current package/bundle into a temporary
      library tree, but any dependent packages need to be installed in
      an available library tree (see the Note: below).

Thus there is already a mechanism to avoid (automatic) rebuilding of
vignettes.  But it seems to be a "all-or-nothing" solution and I could
imagine that some packages might have "real" vignettes that the
maintainer would like to have rebuild automatically and "dummy"
vignettes that should not be rebuild.  So a fine-grained control,
along the way that you suggest, would be a nice way.

"HT" == Hin-Tak Leung <hin-tak.leung at cimr.cam.ac.uk> writes:

HT> I like pdfpages and do use it from time to time [...]  so such
    HT> constructions would break on sites which hasn't upgraded their
    HT> LaTeX installation in the last 3 years.
The "Writing R Extensions" manual states on page 15:

      @code{R CMD build} will automatically create PDF versions of the
      vignettes for distribution with the package sources.  By
      including the PDF version in the package sources it is not
      necessary that the vignettes can be compiled at install time,
      i.e., the package author can use private @LaTeX{} extensions
      which are only available on his machine.  Only the @R{} code
      inside the vignettes is part of the checking procedure,
      typesetting manuals is not part of the package QC.

Thus, only the (La)TeX installation of the maintainer of a package has
to be on a reasonably up-to-date level to use such a construction.  

Thanks everybody for their input and comments.

Cheers,

        Berwin

G'day all,

"HW" == hadley wickham <h.wickham at gmail.com> writes:

>> There aren't any immediate plans to change help(package=XXX), but I
    >> think in the long run, if package?XXX receives wider support than it has
    >> now, it would make sense to make that change.
    HW> When was this form of package documentation created?
Well, the section in "Writing R extensions" on "Documenting packages"
appeared first in the version for R 2.2.0.  My impression is that this
form of package documentation was created in response to the following
discussion:
        http://tolstoy.newcastle.edu.au/R/devel/05/06/index.html#1141
In particular, look at message :
        http://tolstoy.newcastle.edu.au/R/devel/05/06/1161.html
in that thread.

    HW> How are users supposed to know it exists?
By asking questions (or following the discussions) on r-help and r-devel? ;-))

More seriously, as Duncan pointed out in his reply, this is a
relatively new feature and few packages support it.  But I guess
sooner or later this feature will be advertised more widely, if only
because of it being again and again mentioned in discussions on r-help
and r-devel.

Cheers,

        Berwin