Requests for vignette clarification (re: Writing R Extensions)

[PaulJohnson32gmail]

I apologize that these questions are stupid and literal.

I write to ask for clarification of comments in the R extensions
manual about vignettes.  I'm not great at LaTeX, but I'm not a
complete novice either, and some of the comments are puzzling to me.

1. I'm stumbling over this line:

"Make sure all files needed to run the R code in the vignette (data
sets, ...) are accessible by either placing them in the inst/doc
hierarchy of the source package or by using calls to system.file()."

Where it says "inst/doc", can I interpret it to mean "vignettes"?  The
vignette files are under vignettes. Why wouldn't those other files be
in there? Or does that mean I'm supposed to copy the style and bib
files from the vignettes folder to the inst/doc folder?  Or none of
the above :)

2. I'm also curious about the implications of the parenthesized
section of this comment:

"By default R CMD build will run Sweave on all files in Sweave format
in vignettes, or if that does not exist, inst/doc (but not in
sub-directories)."

At first I though that meant it will search vignettes and
subdirectories under vignettes, or it will look under inst/doc, but no
subdirectories under inst/doc.  So I created vignettes in
subdirectories under vignettes and they are ignored by the build
process, so that was obviously wrong.  For clarification, it would
help me if the manual said

"By default R CMD build will run Sweave on all files in Sweave format
in vignettes (but not in sub-directories), or if that does not exist,
inst/doc ."

In this list I've read several questions/complaints from people who
don't want their vignettes rebuild during the package check or build
process, and I wondered if there is a benefit to having vignettes in
subdirectories.   Could inclusion of troublesome vignettes in
subdirectories be a way that people can circumvent the rebuilding and
re-checking of vignettes during build, check, or install?  If I build
my vignettes manually and copy the pdf output over to inst/doc, will
those pdf files be "legitimate" vignette files as far as CRAN is
concerned?  The writeup in R Extensions is a little bit confusing on
that point.

"By including the PDF version in the package sources it is not
necessary that the vignette PDFs can be re-built at install time,
i.e., the package author can use private R packages, screen snapshots
and LaTeX extensions which are only available on his machine."

Its just confusing, that's all I can say about it.

I could learn how to do this from some examples of packages that
manage vignettes the "right way", if you could tell me which ones are
"right" :) I'd like to see one that has a Makefile, uses a bib file,
and, if possible, one that imports a pdf file from elsewhere.  If
there is one that uses subdirectories under vignettes to keep separate
 the content of vignettes, that would be extra helpful.

I'm eager to do this in the correct way, just point me at some that are proper.

pj

--
Paul E. Johnson
Professor, Political Science    Assoc. Director
1541 Lilac Lane, Room 504     Center for Research Methods
University of Kansas               University of Kansas
http://pj.freefaculty.org            http://quant.ku.edu

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

[Paul Gilbert-2]

I'll make a guess at some parts of this.

On 12-06-01 02:53 PM, Paul Johnson wrote:

> I apologize that these questions are stupid and literal.
>
> I write to ask for clarification of comments in the R extensions
> manual about vignettes.  I'm not great at LaTeX, but I'm not a
> complete novice either, and some of the comments are puzzling to me.
>
> 1. I'm stumbling over this line:
>
> "Make sure all files needed to run the R code in the vignette (data
> sets, ...) are accessible by either placing them in the inst/doc
> hierarchy of the source package or by using calls to system.file()."
>
> Where it says "inst/doc", can I interpret it to mean "vignettes"?  The
> vignette files are under vignettes. Why wouldn't those other files be
> in there? Or does that mean I'm supposed to copy the style and bib
> files from the vignettes folder to the inst/doc folder?  Or none of
> the above :)

I think the idea is that a user looking at an installed version of the
package will be able to see things that are in the doc/ directory of the
installed package. This automatically includes the source files (eg
*.Stex) from vignettes/ and also the generated *.pdf and the *.R files
stripped from the *.Stex files. If you want them to have access to other
files then you should put those somewhere so they get installed, such as
in the source package /inst/doc directory so they get put in the doc/
directory of the installed package. That should probably include
anything else that is important to reproduce the results in the
vignette, but I do not count the .bib file in that list (so I have it in
vignettes/ and users would need to look at the package source to find it).

>
> 2. I'm also curious about the implications of the parenthesized
> section of this comment:
>
> "By default R CMD build will run Sweave on all files in Sweave format
> in vignettes, or if that does not exist, inst/doc (but not in
> sub-directories)."
>
> At first I though that meant it will search vignettes and
> subdirectories under vignettes, or it will look under inst/doc, but no
> subdirectories under inst/doc.  So I created vignettes in
> subdirectories under vignettes and they are ignored by the build
> process, so that was obviously wrong.  For clarification, it would
> help me if the manual said
>
> "By default R CMD build will run Sweave on all files in Sweave format
> in vignettes (but not in sub-directories), or if that does not exist,
> inst/doc ."
>
> In this list I've read several questions/complaints from people who
> don't want their vignettes rebuild during the package check or build
> process, and I wondered if there is a benefit to having vignettes in
> subdirectories.   Could inclusion of troublesome vignettes in
> subdirectories be a way that people can circumvent the rebuilding and
> re-checking of vignettes during build, check, or install?  If I build
> my vignettes manually and copy the pdf output over to inst/doc, will
> those pdf files be "legitimate" vignette files as far as CRAN is
> concerned?  The writeup in R Extensions is a little bit confusing on
> that point.
>
> "By including the PDF version in the package sources it is not
> necessary that the vignette PDFs can be re-built at install time,
> i.e., the package author can use private R packages, screen snapshots
> and LaTeX extensions which are only available on his machine."
>
> Its just confusing, that's all I can say about it.

There was at least one earlier R-devel discussion of this, in which I
contributed an incorrect understanding, but was generally straightened
out by Uwe. I hope I have a correct understanding now.

You can put a pdf file in inst/doc and specify "BuildVignettes: false"
in the DESCRIPTION file, in which case the already constructed pdf from
inst/doc will be used. The purpose of this is to allow vignettes which
would not be completely constructed from sources, for example, because
certain data or other resources may not be generally available. However,
R CMD check will still try to parse the Sweave file and run the R code,
and fail if it does not run. So, when the resources to build the
vignette are not generally available this does require some special
attention, often with try(), in the code for your vignette.

It is possible to claim special exemption for a vignette. If the reasons
seem valid then that package will be put on a special list which allows
skipping the vignette when the package is tested for CRAN. The reason
for somewhat tight control on this by CRAN maintainers is that the
vignettes have proven to be a good check on problems with packages, so
skipping them will reduce quality, and so CRAN maintainers do not want
to provide an easy option to skip this check.

There have been a variety of mechanism suggested on R-devel for
subverting the CRAN checks of the vignette code. My interpretation is
that these should generally be considered contrary to the spirit of what
CRAN maintainers are attempting to do, and package maintainers should
expect continuing problems as the loopholes are removed.

Paul Gilbert

>
> I could learn how to do this from some examples of packages that
> manage vignettes the "right way", if you could tell me which ones are
> "right" :) I'd like to see one that has a Makefile, uses a bib file,
> and, if possible, one that imports a pdf file from elsewhere.  If
> there is one that uses subdirectories under vignettes to keep separate
>   the content of vignettes, that would be extra helpful.
>
> I'm eager to do this in the correct way, just point me at some that are proper.
>
> pj
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

[PaulJohnson32gmail]

On Sun, Jun 3, 2012 at 2:02 PM, Paul Gilbert <[hidden email]> wrote:

> I'll make a guess at some parts of this.
>
>
> On 12-06-01 02:53 PM, Paul Johnson wrote:
>>
>> I apologize that these questions are stupid and literal.
>>
>> I write to ask for clarification of comments in the R extensions
>> manual about vignettes.  I'm not great at LaTeX, but I'm not a
>> complete novice either, and some of the comments are puzzling to me.
>>
>> 1. I'm stumbling over this line:
>>
>> "Make sure all files needed to run the R code in the vignette (data
>> sets, ...) are accessible by either placing them in the inst/doc
>> hierarchy of the source package or by using calls to system.file()."
>>
>> Where it says "inst/doc", can I interpret it to mean "vignettes"?  The
>> vignette files are under vignettes. Why wouldn't those other files be
>> in there? Or does that mean I'm supposed to copy the style and bib
>> files from the vignettes folder to the inst/doc folder?  Or none of
>> the above :)
>
>
> I think the idea is that a user looking at an installed version of the
> package will be able to see things that are in the doc/ directory of the
> installed package. This automatically includes the source files (eg *.Stex)
> from vignettes/ and also the generated *.pdf and the *.R files stripped from
> the *.Stex files. If you want them to have access to other files then you
> should put those somewhere so they get installed, such as in the source
> package /inst/doc directory so they get put in the doc/ directory of the
> installed package. That should probably include anything else that is
> important to reproduce the results in the vignette, but I do not count the
> .bib file in that list (so I have it in vignettes/ and users would need to
> look at the package source to find it).
>
>>
>> 2. I'm also curious about the implications of the parenthesized
>> section of this comment:
>>
>> "By default R CMD build will run Sweave on all files in Sweave format
>> in vignettes, or if that does not exist, inst/doc (but not in
>> sub-directories)."
>>
>> At first I though that meant it will search vignettes and
>> subdirectories under vignettes, or it will look under inst/doc, but no
>> subdirectories under inst/doc.  So I created vignettes in
>> subdirectories under vignettes and they are ignored by the build
>> process, so that was obviously wrong.  For clarification, it would
>> help me if the manual said
>>
>> "By default R CMD build will run Sweave on all files in Sweave format
>> in vignettes (but not in sub-directories), or if that does not exist,
>> inst/doc ."
>>
>> In this list I've read several questions/complaints from people who
>> don't want their vignettes rebuild during the package check or build
>> process, and I wondered if there is a benefit to having vignettes in
>> subdirectories.   Could inclusion of troublesome vignettes in
>> subdirectories be a way that people can circumvent the rebuilding and
>> re-checking of vignettes during build, check, or install?  If I build
>> my vignettes manually and copy the pdf output over to inst/doc, will
>> those pdf files be "legitimate" vignette files as far as CRAN is
>> concerned?  The writeup in R Extensions is a little bit confusing on
>> that point.
>>
>> "By including the PDF version in the package sources it is not
>> necessary that the vignette PDFs can be re-built at install time,
>> i.e., the package author can use private R packages, screen snapshots
>> and LaTeX extensions which are only available on his machine."
>>
>> Its just confusing, that's all I can say about it.
>
>
> There was at least one earlier R-devel discussion of this, in which I
> contributed an incorrect understanding, but was generally straightened out
> by Uwe. I hope I have a correct understanding now.
>
> You can put a pdf file in inst/doc and specify "BuildVignettes: false" in
> the DESCRIPTION file, in which case the already constructed pdf from
> inst/doc will be used. The purpose of this is to allow vignettes which would
> not be completely constructed from sources, for example, because certain
> data or other resources may not be generally available. However, R CMD check
> will still try to parse the Sweave file and run the R code, and fail if it
> does not run. So, when the resources to build the vignette are not generally
> available this does require some special attention, often with try(), in the
> code for your vignette.
>
> It is possible to claim special exemption for a vignette. If the reasons
> seem valid then that package will be put on a special list which allows
> skipping the vignette when the package is tested for CRAN. The reason for
> somewhat tight control on this by CRAN maintainers is that the vignettes
> have proven to be a good check on problems with packages, so skipping them
> will reduce quality, and so CRAN maintainers do not want to provide an easy
> option to skip this check.
>
> There have been a variety of mechanism suggested on R-devel for subverting
> the CRAN checks of the vignette code. My interpretation is that these should
> generally be considered contrary to the spirit of what CRAN maintainers are
> attempting to do, and package maintainers should expect continuing problems
> as the loopholes are removed.
>
> Paul Gilbert
>
>
>>
>> I could learn how to do this from some examples of packages that
>> manage vignettes the "right way", if you could tell me which ones are
>> "right" :) I'd like to see one that has a Makefile, uses a bib file,
>> and, if possible, one that imports a pdf file from elsewhere.  If
>> there is one that uses subdirectories under vignettes to keep separate
>>  the content of vignettes, that would be extra helpful.
>>
>> I'm eager to do this in the correct way, just point me at some that are
>> proper.
>>
>> pj
>>
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

I got to the bottom of the problem that made me ask. I had a package
that failed build check. I wrote the vignette in LyX and when I add a
bibliography file in LyX, it adds a full path, not just {rockchalk},
in the Rnw file.

\bibliography{0_home_pauljohn_SVN_rgroup_trunk_rockchalk_rockchalk_vignettes_rockchalk}

LyX does that because it runs its builds in a temporary folder.

When it is like that, the vignette builds for me, but it does not
survive the package check because the check  won't go looking on the
long path.

pj


--
Paul E. Johnson
Professor, Political Science    Assoc. Director
1541 Lilac Lane, Room 504     Center for Research Methods
University of Kansas               University of Kansas
http://pj.freefaculty.org            http://quant.ku.edu

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

[Yihui Xie-2]

You should export to Rnw directly from LyX instead of copying the Rnw
document in the LyX temp dir. The former one is a clean TeX document,
and the latter one will mangle all filenames.

Regards,
Yihui
--
Yihui Xie <[hidden email]>
Phone: [phone] Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA


On Mon, Jun 4, 2012 at 9:29 AM, Paul Johnson <[hidden email]> wrote:

>
>
> I got to the bottom of the problem that made me ask. I had a package
> that failed build check. I wrote the vignette in LyX and when I add a
> bibliography file in LyX, it adds a full path, not just {rockchalk},
> in the Rnw file.
>
> \bibliography{0_home_pauljohn_SVN_rgroup_trunk_rockchalk_rockchalk_vignettes_rockchalk}
>
> LyX does that because it runs its builds in a temporary folder.
>
> When it is like that, the vignette builds for me, but it does not
> survive the package check because the check  won't go looking on the
> long path.
>
> pj
>
>
> --
> Paul E. Johnson
> Professor, Political Science    Assoc. Director
> 1541 Lilac Lane, Room 504     Center for Research Methods
> University of Kansas               University of Kansas
> http://pj.freefaculty.org            http://quant.ku.edu
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel