add vignette

diff --git a/DESCRIPTION b/DESCRIPTION
index cadc405f694216d30cb11bdb990b9354c3ca263f..be584b4d2d757eeaeba06f25352fbdb6e6352e34 100644 (file)
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -20,3 +20,5 @@ Description: Collection of hacks for Cairo components (bookmarks, raster plots)
  megabytes in size, while still allowing other plot components to be
  presented in their original vector format.
 License: GPL (>=3)
+Suggests: knitr
+VignetteBuilder: knitr

diff --git a/vignettes/cairohacks.Rmd b/vignettes/cairohacks.Rmd
new file mode 100644 (file)
index 0000000..e11f4c2
--- /dev/null
+++ b/vignettes/cairohacks.Rmd
@@ -0,0 +1,64 @@
+---
+title: "CairoHacks: Bookmarks and Rasters"
+author: "Don Armstrong"
+output:
+    html_document:
+        toc: TRUE
+vignette: >
+  %\VignetteIndexEntry{CairoHacks}
+  %\VignetteEngine{knitr::knitr}
+  \usepackage[utf8]{inputenc}
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo=TRUE)
+```
+
+# Bookmarks
+
+CairoHacks allows you to create bookmarks in PDF documents. This
+requires the use of pdftk to actually create the bookmarks at the end
+of the pdf creation.
+
+Here is a simple example:
+
+```{r, eval=FALSE}
+     Cairo::CairoPDF(file="example.pdf",onefile=TRUE)
+     plot(y~x,data.frame(x=1:5,y=1:5))
+     bookmarks <- make.pdf.bookmark("First plot")
+     plot(y~x,data.frame(x=1:5,y=1:5))
+     bookmarks <- bookmarks + make.pdf.bookmark("Second plot")
+     dev.off()
+     write.pdf.bookmarks(file="example.pdf",bookmarks)
+```
+
+This will create two bookmarks in the file `example.pdf` named "First
+plot" and "Second plot" which point to the first and second pages,
+respectively.
+
+Bookmarks requires the use of the CairoPDF device so that the current
+page number can be obtained using the onSave Cairo Hook. In the
+future, if other devices allow reporting the current page number, they
+will be supported.
+
+# Raster Images
+
+CairoHacks also allows you to create raster images (bitmaps) which can
+then be embedded into a PDF. This is very useful, because sometimes
+you have a huge number (millions) of points which you would like to
+plot on a single plot without making the resultant PDF megabytes in
+size. For example:
+
+```{r echo=TRUE,fig.keep="last"}
+library("CairoHacks")
+library("lattice")
+start_rasterplot(width=1024)
+plot(y~x,
+     data=data.frame(y=rnorm(1E5),x=rnorm(1E5)))
+raster.image <- stop_rasterplot(plot=FALSE)
+grid::grid.raster(raster.image)
+```
+
+produces a plot with 10 million points, but is only 1024 pixels wide
+by 1024 pixels tall. (The width is 1024 by default, and the height is
+automatically scaled on the basis of the underlying graphics device.)