The vignette for compareMCMCs has a need a bit outside the package vignette system,
so it is organized as custom vignette under inst.

(The main issue is that compareMCMCs is a package that generates jpg files
and html files that use those jpg images.  In the vignette, we link to an example
of results generated by the package.  However, it is difficult to include jpg files
in the standard vignette structure.  Whether from the vignettes directory for a
"package vignette" or from the inst/doc directory for an arbitrary vignette,
it seems that html and pdf files are included in the installation,  but  jpg files
are not.  At the time of this writing, it is not clear why this is the case. "Writing
R Extensions" seems to state that all contents under inst will be copied, except
those excluded by .Rinstignore.  Yet, for some reason jpg files are not being
copied.  Because we can't figure out why, we are working around this.)

In addition, we think it is better to build the vignette locally and manually,
and not have it built automatically, as can happen from the vignettes directory. That's
because it is a bit slow and it would be confusing if, for some reason, even the toy
examples turn out somehow surprisingly on a different machine.  The package makes
performance comparisons, and performance can depend on each system.  The
vignette text refers to the results as they turn out on the local machine they have been
run on by a package maintainer.

Our solution is to put the vignette source into the inst/vignette_source directory,
build it there, manually embed the jpg binary content into the htmls (not part of
regular package functionality at this time), and copy the results into inst/doc, with
an index.html file.  "Writing R Extensions" states that that index.html will then be
used as the vignette link from the package help page.  Unfortunately it does not
register the vignette for the vignette( ) function, and various searching has not
revealed if there is another way to index a vignette for the vignette() function.

Steps:
0. Open compareMCMCs.Rmd and uncomment the line "work_dir <- getwd()" in
the first code chunk.  CRAN policy forbids writing into a user's local filesystem
if they try to build a vignette.  Uncommenting this line serves as confirmation
that you want the vignette to write jpg and html files in your working directory.
If you don't do this, links to the results will not work.  The results will be in
tempdir() and may be erased after step 1 (next).

1. Within this directory, vignette_source, knit compareMCMCs.Rmd into
compareMCMCs.html.

2. Use the embed_jpg_in_html function (see .R file of the same name in this
directory) to embed each of the jpgs into each of the example results.  Each
call gives a warning about an incomplete final line.  These seem harmless.

This code should do it:
source("embed_jpg_in_html.R")
system2("cp", c("example1.html", "example1_orig.html")) # save original copy 
embed_jpg_in_html("example1.html", "example1_efficiencyDetails.jpg", overwrite = TRUE) # warnings about incomplete final line are no problem.
embed_jpg_in_html("example1.html", "example1_efficiencySummaryAll.jpg", overwrite = TRUE)
embed_jpg_in_html("example1.html", "example1_paceSummaryAll.jpg", overwrite = TRUE)
embed_jpg_in_html("example1.html", "example1_posteriorSummary.jpg", overwrite = TRUE)
# Check that example1.html renders correctly in a browser

# repeat for example2
system2("cp", c("example2.html", "example2_orig.html")) # save original copy 
embed_jpg_in_html("example2.html", "example2_efficiencyDetails.jpg", overwrite = TRUE)
embed_jpg_in_html("example2.html", "example2_efficiencySummaryAll.jpg", overwrite = TRUE)
embed_jpg_in_html("example2.html", "example2_paceSummaryAll.jpg", overwrite = TRUE)
embed_jpg_in_html("example2.html", "example2_posteriorSummary.jpg", overwrite = TRUE)
# Check that example2.html renders correctly in a browser

3. purl("compareMCMCs.Rmd") # generate compareMCMCs.R

4. Copy compareMCMCs.html, example1.html, and example2.html into inst/doc

5. Possibly inst/index.html?
