Set/get pdf bookmarks

get_bookmarks() gets pdf bookmarks from a file. set_bookmarks() sets pdf bookmarks for a file.

Usage

get_bookmarks(filename, use_names = TRUE)

get_bookmarks_pdftk(filename, use_names = TRUE)

get_bookmarks_pdftools(filename, use_names = TRUE)

get_bookmarks_augmented(filename, use_names = TRUE)

set_bookmarks(bookmarks, input, output = input)

set_bookmarks_pdftk(bookmarks, input, output = input)

set_bookmarks_gs(bookmarks, input, output = input)

Arguments

filename

Filename(s) (pdf) to extract bookmarks from.

use_names

If TRUE (default) use filename as the names of the result.

bookmarks

A data frame with bookmark information with the following columns:

title: Title for bookmark (mandatory, character)
page: Page number for bookmark (mandatory, integer)
level: Level of bookmark e.g. 1 top level, 2 second level, etc. (optional, integer). If missing will be inferred from count column else will be assumed to be 1L.
count: Number of bookmarks immediately subordinate (optional, integer). Excludes subordinates of subordinates. Positive count indicates bookmark should start open while negative count indicates that this bookmark should start closed. If missing will be inferred from level column and (if specified) the open column else will be assumed to be 0L. Note some pdf viewers quietly ignore the initially open/closed feature.
open: Whether the bookmark starts open or closed if it has subordinate bookmarks (optional, logical). If missing will default to open. Ignored if the count column is specified (instead use a negative count if the bookmark should start closed). Note some pdf viewers quietly ignore the initially open/closed feature.
fontface: Font face of the bookmark (optional, integer). If NA_character_ or NA_integer_ will be unset (defaults to "plain"). "plain" or 1 is plain, "bold" or 2 is bold, "italic" or 3 is italic, Note many pdf viewers quietly ignore this feature.
color: Color of the bookmark (optional, character). If NA_character_ will be unset (presumably defaults to "black"). Note many pdf viewers quietly ignore this feature.

input

Input pdf filename.

output

Output pdf filename.

Value

get_bookmarks() returns a list of data frames with bookmark info (see bookmarks parameter for details about columns) plus "total_pages", "filename", and "title" attributes. NA values in the data frame indicates that the backend doesn't report information about this pdf feature. set_bookmarks() returns the (output) filename invisibly.

Details

get_bookmarks() will try to use the following helper functions in the following order:

get_bookmarks_augmented() which augments data from get_bookmarks_pdftk() with open/close data from get_bookmarks_pdftools()
get_bookmarks_pdftk() which wraps pdftk command-line tool
get_bookmarks_pdftools() which wraps pdftools::pdf_toc()

set_bookmarks() will try to use the following helper functions in the following order:

set_bookmarks_gs() which wraps ghostscript command-line tool
set_bookmarks_pdftk() which wraps pdftk command-line tool

Known limitations

get_bookmarks_pdftk() doesn't report information about bookmarks color, fontface, and whether the bookmarks should start open or closed.
get_bookmarks_pdftools() doesn't report information about bookmarks page number, color, and fontface.
get_bookmarks_augmented() doesn't report information about bookmarks color and fontface.
set_bookmarks_gs() supports most bookmarks features including color and font face but only action supported is to view a particular page.
set_bookmarks_gs() has a destructive side effect on any existing XMP metadata, since it uses ghostscript's pdfwrite device. See edit_docinfo() for details.
set_bookmarks_pdftk() only supports setting the title, page number, and level of bookmarks.

Examples

# Create 2-page pdf using `pdf)` and add some bookmarks to it
if (supports_set_bookmarks() && supports_get_bookmarks() && require("grid", quietly = TRUE)) {
  f <- tempfile(fileext = ".pdf")
  pdf(f, onefile = TRUE)
  grid.text("Page 1")
  grid.newpage()
  grid.text("Page 2")
  invisible(dev.off())

  print(get_bookmarks(f)[[1]])
  DONTSHOW({cat("\n")})

  bookmarks <- data.frame(title = c("Page 1", "Page 2"), page = c(1, 2))

  set_bookmarks(bookmarks, f)
  print(get_bookmarks(f)[[1]])
  unlink(f)
}
#> [1] title    page     level    count    open     color    fontface
#> <0 rows> (or 0-length row.names)
#> 
#>    title page level count open color fontface
#> 1 Page 1    1     1     0   NA  <NA>     <NA>
#> 2 Page 2    2     1     0   NA  <NA>     <NA>