Documentation with Rd, roxygen2 and Vignettes

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/isbn.R
\name{normalise_isbn}
\alias{normalise_isbn}
\alias{is_valid_isbn13}
\title{Normalise and validate ISBN-13 strings}
\usage{
normalise_isbn(x)

is_valid_isbn13(x)
}
\arguments{
\item{x}{A character vector of ISBNs; \code{NA} and empty strings are allowed.}
}
\value{
\code{normalise_isbn()} returns a character vector of the same length;
\code{is_valid_isbn13()} a logical vector of the same length, \code{FALSE} for
\code{NA} and for the empty string.
}
\description{
\code{normalise_isbn()} drops everything except digits and \code{X} and upper-cases
the result, so \code{"978-0-00-100010-0"} and \code{"9780001000100"} compare equal.
\code{is_valid_isbn13()} checks that a (normalised) string has 13 digits and a
correct check digit: the digits are multiplied alternately by 1 and 3 and
the sum must be divisible by 10.
}
\examples{
normalise_isbn("978-0-00-100010-0")
is_valid_isbn13(c("978-0-00-100010-0", "9780001000101", "", NA))
}

# Parse man/book.Rd (written by roxygen2) and look at the parse tree.
rd <- tools::parse_Rd("man/book.Rd")
class(rd)
#> [1] "Rd"
tags <- vapply(rd, \(x) attr(x, "Rd_tag"), character(1))
tags[tags != "TEXT"]
#>  [1] "COMMENT"       "COMMENT"       "\\name"        "\\alias"
#>  [5] "\\alias"       "\\alias"       "\\title"       "\\usage"
#>  [9] "\\arguments"   "\\value"       "\\description" "\\examples"
#> [13] "\\seealso"     "\\concept"
length(rd)
#> [1] 28

# The text of an element: its leaves pasted together.
rd_text <- \(x) paste(vapply(x, as.character, character(1)), collapse = "")

# The \alias entries are what help() searches.
vapply(rd[tags == "\\alias"], rd_text, character(1))
#> [1] "book"          "new_book"      "validate_book"

# The title and the concept index entry as plain text.
rd_text(rd[[which(tags == "\\title")]])
#> [1] "The book class"
rd_text(rd[[which(tags == "\\concept")]])
#> [1] "book class"

# The parts of the usage section, as the parser sees them.
usage <- rd[[which(tags == "\\usage")]]
attr(usage, "Rd_tag")
#> [1] "\\usage"
attr(usage[[2L]], "Rd_tag")
#> [1] "RCODE"

# A hand-written Rd file that uses most of the markup macros, rendered as text.
rd_file <- file.path(tempdir(), "loan_rules.Rd")
writeLines(r"---(\newcommand{\isbn}{\code{ISBN-13}}
\name{loan_rules}
\alias{loan_rules}
\title{Loan Rules of the Shelf Library}
\description{
  The loan period is \code{getOption("shelf.loan_days")} days; set it
  with \code{\link{options}}, or with the environment variable
  \env{SHELF_LOAN_DAYS} in \file{.Renviron}. See \pkg{shelf},
  \emph{emphasis}, \strong{strong text} and \sQuote{single} or
  \dQuote{double} quotes; \verb{x[[1]]} is shown verbatim.
  A book is identified by its \isbn{} (see \doi{10.32614/R.manuals}).
}
\details{
  \itemize{
    \item A loan is overdue after \eqn{d > 21} days.
    \item Members may hold \eqn{n \le 5}{n <= 5} loans.
  }
  \enumerate{
    \item Take the book out.
    \item Return it.
  }
  \describe{
    \item{late}{returned after the loan period.}
    \item{out}{not returned yet.}
  }
  \tabular{lrr}{
    genre \tab loans \tab overdue \cr
    Fiction \tab 12 \tab 6 \cr
    Poetry \tab 4 \tab 1
  }
  The rate is \deqn{r = \frac{o}{n}}{r = o / n}
  See \url{https://example.com/shelf} and
  \href{https://example.com/shelf/rules}{the rules}.
  This text is for the console: \ifelse{text}{plain text}{rich text}.
}
\section{Evaluated when the page is built}{
  The page has \Sexpr[stage=build]{length(letters)} letters in its
  alphabet and is rendered with \Sexpr[stage=render]{R.version$language}.
}
\examples{
x <- 1:3
sum(x)
\dontrun{stop("never run")}
\donttest{max(x)}
\dontshow{stopifnot(is.numeric(x))}
}
\keyword{documentation}
)---", rd_file)
tools::Rd2txt(
  rd_file,
  stages = c("build", "install", "render"),
  options = list(underline_titles = FALSE)
)
#> Loan Rules of the Shelf Library
#>
#> Description:
#>
#>      The loan period is ‘getOption("shelf.loan_days")’ days; set it
#>      with ‘options’, or with the environment variable ‘SHELF_LOAN_DAYS’
#>      in ‘.Renviron’. See ‘shelf’, _emphasis_, *strong text* and
#>      ‘single’ or “double” quotes; x[[1]] is shown verbatim.  A book is
#>      identified by its ‘ISBN-13’ (see doi:10.32614/R.manuals
#>      <https://doi.org/10.32614/R.manuals>).
#>
#> Details:
#>
#>         • A loan is overdue after d > 21 days.
#>
#>         • Members may hold n <= 5 loans.
#>
#>        1. Take the book out.
#>
#>        2. Return it.
#>
#>      late
#>           returned after the loan period.
#>
#>      out
#>           not returned yet.
#>
#>        genre    loans  overdue
#>        Fiction     12        6
#>        Poetry       4        1
#>
#>      The rate is
#>
#>                                   r = o / n
#>
#>      See <https://example.com/shelf> and the rules.  This text is for
#>      the console: plain text.
#>
#> Evaluated when the page is built:
#>
#>      The page has 26 letters in its alphabet and is rendered with R.
#>
#> Examples:
#>
#>      x <- 1:3
#>      sum(x)
#>      ## Not run: stop("never run")
#>      max(x)
#>

# The default is stages = "render": a build-stage macro is then left as written.
small <- file.path(tempdir(), "small.Rd")
writeLines(r"---(\name{small}
\alias{small}
\title{Small}
\description{
  Built: \Sexpr[stage=build]{length(letters)};
  rendered: \Sexpr[stage=render]{R.version$language}.
}
)---", small)
tools::Rd2txt(small, options = list(underline_titles = FALSE))
#> Small
#>
#> Description:
#>
#>      Built: \Sexpr[stage=build]{length(letters)}; rendered: R.
#>

# tools::checkRd() on small broken Rd files; each case shows what R reports.
check_rd <- \(label, lines) {
  f <- file.path(tempdir(), "broken.Rd")
  writeLines(lines, f)
  res <- NULL
  msg <- capture.output(
    res <- tryCatch(tools::checkRd(f), error = \(e) conditionMessage(e)),
    type = "message"
  )
  out <- capture.output(print(res))
  # Keep the temporary directory out of the messages.
  cat(label, ":\n", sep = "")
  cat(sub(paste0(tempdir(), "/"), "", c(msg, out), fixed = TRUE), sep = "\n")
}

check_rd("no title", c("\\name{a}", "\\alias{a}", "\\usage{a()}"))
#> no title:
#> [1] "broken.Rd: Sections \\title, and \\name must exist and be unique in Rd files"

check_rd("unclosed brace", c(
  "\\name{a}", "\\alias{a}", "\\title{T}",
  "\\description{An unclosed {brace.", "}"
))
#> unclosed brace:
#> prepare_Rd: broken.Rd:6: unexpected END_OF_INPUT '
#> '
#> checkRd: (-1) broken.Rd:4-5: Lost braces; missing escapes or markup?
#>      4 | \description{An unclosed {brace.
#>        |                          ^

check_rd("macro without its backslash", c(
  "\\name{a}", "\\alias{a}", "\\title{T}",
  "\\description{Use code{x} here.}"
))
#> macro without its backslash:
#> checkRd: (-1) broken.Rd:4: Lost braces
#>      4 | \description{Use code{x} here.}
#>        |                      ^

check_rd("misspelt macro", c(
  "\\name{a}", "\\alias{a}", "\\title{T}",
  "\\description{Use \\codee{x} here.}"
))
#> misspelt macro:
#> prepare_Rd: broken.Rd:4: unknown macro '\codee'

check_rd("unescaped percent sign", c(
  "\\name{a}", "\\alias{a}", "\\title{T}",
  "\\description{It is 50% done.}", "\\examples{x <- 1}"
))
#> unescaped percent sign:
#> prepare_Rd: broken.Rd:5: unexpected section header '\examples'
#> prepare_Rd: broken.Rd:6: unexpected END_OF_INPUT '
#> '
#> checkRd: (-1) broken.Rd:5: Lost braces; missing escapes or markup?
#>      5 | \examples{x <- 1}
#>        |          ^

check_rd("title ending in a period, item with two arguments", c(
  "\\name{a}", "\\alias{a}", "\\title{A title.}", "\\description{Text.}",
  "\\details{\\itemize{\\item{x}{y}}}"
))
#> title ending in a period, item with two arguments:
#> checkRd: (-5) broken.Rd:3: \title should not end in a period
#> checkRd: (-3) broken.Rd:5: Lost braces
#>      5 | \details{\itemize{\item{x}{y}}}
#>        |                        ^
#> checkRd: (-1) broken.Rd:5: Lost braces in \itemize; meant \describe ?

# prompt() writes an Rd skeleton for a function, to be edited by hand.
library(shelf)
#> shelf 0.1.0: loan period is 21 days
file <- file.path(tempdir(), "normalise_isbn.Rd")
invisible(capture.output(
  prompt(normalise_isbn, filename = file),
  type = "message"
))
head(readLines(file), 16)
#>  [1] "\\name{normalise_isbn}"
#>  [2] "\\alias{normalise_isbn}"
#>  [3] "%- Also NEED an '\\alias' for EACH other topic documented here."
#>  [4] "\\title{"
#>  [5] "A Capitalized Title (ideally limited to 65 characters)"
#>  [6] "}"
#>  [7] "\\description{"
#>  [8] "%%  ~~ A concise (1-5 lines) description of what the function does. ~~"
#>  [9] "}"
#> [10] "\\usage{"
#> [11] "normalise_isbn(x)"
#> [12] "}"
#> [13] "%- maybe also 'usage' for other objects documented here."
#> [14] "\\arguments{"
#> [15] "  \\item{x}{"
#> [16] "%%     ~~Describe \\code{x} here~~"

# Render man/book.Rd as plain text, the way help("book") shows it in a terminal.
tools::Rd2txt("man/book.Rd", options = list(underline_titles = FALSE))
#> The 'book' class
#>
#> Description:
#>
#>      ‘book()’ is the user-facing constructor of the ‘book’ class: it
#>      trims the text fields, normalises the ISBN with
#>      ‘normalise_isbn()’, coerces ‘year’ and ‘pages’ to integer and
#>      validates the result. ‘new_book()’ is the low-level constructor
#>      that only checks types, and ‘validate_book()’ checks the values;
#>      both are exported so that other packages can extend the class.
#>
#> Usage:
#>
#>      book(
#>        title,
#>        author = NA_character_,
#>        isbn = NA_character_,
#>        year = NA_integer_,
#>        genre = NA_character_,
#>        pages = NA_integer_
#>      )
#>
#>      new_book(
#>        title = character(),
#>        author = character(),
#>        isbn = character(),
#>        year = integer(),
#>        genre = character(),
#>        pages = integer()
#>      )
#>
#>      validate_book(x)
#>
#> Arguments:
#>
#>    title: Title of the book (a single string).
#>
#>   author: Author (a single string, or ‘NA’).
#>
#>     isbn: ISBN-13, hyphenated or bare (a single string, or ‘NA’).
#>
#>     year: Publication year (a single number, or ‘NA’).
#>
#>    genre: Genre (a single string, or ‘NA’).
#>
#>    pages: Number of pages (a single number, or ‘NA’).
#>
#>        x: A ‘book’ object.
#>
#> Value:
#>
#>      An object of class ‘book’: a list with the six fields above, each
#>      of length one.
#>
#> See Also:
#>
#>      Other book class: ‘book-methods’
#>
#> Examples:
#>
#>      b <- book("  the quiet streets ", "Mara Quill", "978-0-00-100010-0", 2019,
#>                "Fiction ", 214)
#>      b
#>      summary(b)
#>      unclass(b)
#>

# The same Rd file through the other converters, written to temporary files.
html <- tempfile(fileext = ".html")
tools::Rd2HTML("man/book.Rd", out = html, package = "shelf")
lines <- readLines(html)
# The title line of the page and the headings of its sections.
grep("R Documentation|^<h[23]", lines, value = TRUE)
#> [1] "<table style=\"width: 100%;\"><tr><td>book {shelf}</td><td style=\"text-align: right;\">R Documentation</td></tr></table>"
#> [2] "<h2>The <code>book</code> class</h2>"
#> [3] "<h3>Description</h3>"
#> [4] "<h3>Usage</h3>"
#> [5] "<h3>Arguments</h3>"
#> [6] "<h3>Value</h3>"
#> [7] "<h3>See Also</h3>"
#> [8] "<h3>Examples</h3>"

# Rd2ex() extracts the examples, with a header that records the page.
ex <- tempfile(fileext = ".R")
tools::Rd2ex("man/book.Rd", out = ex)
cat(readLines(ex), sep = "\n")
#> ### Name: book
#> ### Title: The 'book' class
#> ### Aliases: book new_book validate_book
#>
#> ### ** Examples
#>
#> b <- book("  the quiet streets ", "Mara Quill", "978-0-00-100010-0", 2019,
#>           "Fiction ", 214)
#> b
#> summary(b)
#> unclass(b)
#>
#>
#>

# Rd2latex() writes the LaTeX that R CMD Rd2pdf feeds to pdflatex.
tex <- tempfile(fileext = ".tex")
tools::Rd2latex("man/book.Rd", out = tex)
head(readLines(tex), 6)
#> [1] "\\HeaderA{book}{The \\code{book} class}{book}"
#> [2] "\\aliasA{new\\_book}{book}{new.Rul.book}"
#> [3] "\\aliasA{validate\\_book}{book}{validate.Rul.book}"
#> [4] "\\keyword{book class}{book}"
#> [5] "%"
#> [6] "\\begin{Description}"

R CMD Rdconv -t example shelf/man/normalise_isbn.Rd
echo "exit status: $?"

### Name: normalise_isbn
### Title: Normalise and validate ISBN-13 strings
### Aliases: normalise_isbn is_valid_isbn13

### ** Examples

normalise_isbn("978-0-00-100010-0")
is_valid_isbn13(c("978-0-00-100010-0", "9780001000101", "", NA))



exit status: 0

R CMD Rd2pdf --no-preview --output=shelf-manual.pdf shelf
echo "exit status: $?"

Hmm ... looks like a package
Converting Rd files to LaTeX
Creating pdf output from LaTeX ...
Warning in texi2dvi(file = file, pdf = TRUE, clean = clean, quiet = quiet,  :
  texi2dvi script/program not available, using emulation
Error in texi2dvi(file = file, pdf = TRUE, clean = clean, quiet = quiet,  :
  pdflatex is not available
Warning in texi2dvi(file = file, pdf = TRUE, clean = clean, quiet = quiet,  :
  texi2dvi script/program not available, using emulation
Error in texi2dvi(file = file, pdf = TRUE, clean = clean, quiet = quiet,  :
  pdflatex is not available
Error in running tools::texi2pdf()
exit status: 1

# What the installation of the Rd files leaves in the library.
help_dir <- system.file("help", package = "shelf")
list.files(help_dir)
#> [1] "aliases.rds" "AnIndex"     "paths.rds"   "shelf.rdb"   "shelf.rdx"

# aliases.rds maps every \alias to the Rd file (the topic name) it came from.
aliases <- readRDS(file.path(help_dir, "aliases.rds"))
aliases[c("format.book", "is_valid_isbn13", "new_book", "clean_loans")]
#>      format.book  is_valid_isbn13         new_book      clean_loans
#>   "book-methods" "normalise_isbn"           "book"    "clean_books"

# Meta/Rd.rds is the table that help.search() and the HTML index are built from.
rd <- readRDS(system.file("Meta", "Rd.rds", package = "shelf"))
names(rd)
#> [1] "File"     "Name"     "Type"     "Title"    "Encoding" "Aliases"  "Concepts"
#> [8] "Keywords"
rd[, c("File", "Name", "Title")]
#>                 File            Name                                   Title
#> 1    book-methods.Rd    book-methods            Methods for the 'book' class
#> 2            book.Rd            book                        The 'book' class
#> 3           books.Rd           books                     The shelf catalogue
#> 4     clean_books.Rd     clean_books Clean the catalogue and the loans table
#> 5    loan_summary.Rd    loan_summary       Loans and overdue rates per genre
#> 6           loans.Rd           loans                         The shelf loans
#> 7 loans_per_month.Rd loans_per_month                         Loans per month
#> 8  normalise_isbn.Rd  normalise_isbn  Normalise and validate ISBN-13 strings
#> 9   overdue_loans.Rd   overdue_loans                           Overdue loans
rd$Aliases[[2L]]
#> [1] "book"          "new_book"      "validate_book"
rd$Concepts[[2L]]
#> [1] "book class"

# How help() finds the page of an installed package.
library(shelf)
#> shelf 0.1.0: loan period is 21 days

# help(package =) lists the topics of the package: its index.
h <- help(package = "shelf")
class(h)
#> [1] "packageInfo"
cat(h$info[[2L]], sep = "\n")
#> book                    The 'book' class
#> book-methods            Methods for the 'book' class
#> books                   The shelf catalogue
#> clean_books             Clean the catalogue and the loans table
#> loan_summary            Loans and overdue rates per genre
#> loans                   The shelf loans
#> loans_per_month         Loans per month
#> normalise_isbn          Normalise and validate ISBN-13 strings
#> overdue_loans           Overdue loans

# A topic is an \alias. format.book is an alias of the page book-methods.
basename(help("book", package = "shelf"))
#> [1] "book"
basename(help("new_book", package = "shelf"))
#> [1] "book"
basename(help("format.book", package = "shelf"))
#> [1] "book-methods"
help("no_such_topic", package = "shelf")
#> No documentation for ‘no_such_topic’ in specified packages and libraries:
#> you could try ‘??no_such_topic’

# ?? and help.search() look in titles, aliases and concepts. Printing the
# result shows it in the pager; the table of matches is a data frame.
hs <- help.search("ISBN", package = "shelf")
class(hs)
#> [1] "hsearch"
hs$matches[, c("Topic", "Field", "Entry")]
#>            Topic Field                                  Entry
#> 1 normalise_isbn alias                         normalise_isbn
#> 2 normalise_isbn alias                        is_valid_isbn13
#> 3 normalise_isbn Title Normalise and validate ISBN-13 strings

# example() runs the \examples of the page.
example(book)
#>
#> book> b <- book("  the quiet streets ", "Mara Quill", "978-0-00-100010-0", 2019,
#> book+           "Fiction ", 214)
#>
#> book> b
#> <book> the quiet streets (Mara Quill, 2019)
#>
#> book> summary(b)
#> Book: the quiet streets
#> ISBN known: TRUE
#> Pages: 214
#>
#> book> unclass(b)
#> $title
#> [1] "the quiet streets"
#>
#> $author
#> [1] "Mara Quill"
#>
#> $isbn
#> [1] "9780001000100"
#>
#> $year
#> [1] 2019
#>
#> $genre
#> [1] "Fiction"
#>
#> $pages
#> [1] 214
#>

# A throwaway package with one documented function, turned into Rd by roxygen2.
pkg <- file.path(tempdir(), "demo")
dir.create(file.path(pkg, "R"), recursive = TRUE)
writeLines(c(
  "Package: demo",
  "Title: A Demonstration",
  "Version: 0.0.1",
  "Description: Shows what roxygen2 writes.",
  "License: MIT",
  "Encoding: UTF-8",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))

writeLines(r"(#' Take a book out
#'
#' Records a loan of `book` to `member`. The loan is overdue after
#' `days` days. Summarise loan lengths with [stats::median()].
#'
#' The second paragraph is the *details* section. A list:
#' * one
#' * two
#'
#' @param book A book (a string).
#' @param member,days Name of the member and length of the loan.
#' @returns A list with the three inputs.
#' @examples
#' loan_book("Dune", "Ana")
#' @importFrom stats median
#' @export
loan_book <- function(book, member, days = 21L) {
  list(book = book, member = member, days = days)
}
)", file.path(pkg, "R", "loan.R"))

invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
cat(readLines(file.path(pkg, "man", "loan_book.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/loan.R
#> \name{loan_book}
#> \alias{loan_book}
#> \title{Take a book out}
#> \usage{
#> loan_book(book, member, days = 21L)
#> }
#> \arguments{
#> \item{book}{A book (a string).}
#>
#> \item{member, days}{Name of the member and length of the loan.}
#> }
#> \value{
#> A list with the three inputs.
#> }
#> \description{
#> Records a loan of \code{book} to \code{member}. The loan is overdue after
#> \code{days} days. Summarise loan lengths with \code{\link[stats:median]{stats::median()}}.
#> }
#> \details{
#> The second paragraph is the \emph{details} section. A list:
#> \itemize{
#> \item one
#> \item two
#> }
#> }
#> \examples{
#> loan_book("Dune", "Ana")
#> }
cat(readLines(file.path(pkg, "NAMESPACE")), sep = "\n")
#> # Generated by roxygen2: do not edit by hand
#>
#> export(loan_book)
#> importFrom(stats,median)

# The options roxygen2 reads for the package, and where they come from.
read.dcf("DESCRIPTION", fields = c("Roxygen", "Config/roxygen2/version"))
#>      Roxygen                 Config/roxygen2/version
#> [1,] "list(markdown = TRUE)" "8.1.1"
opts <- roxygen2::load_options(".")
opts$roclets
#> [1] "collate"   "namespace" "rd"
opts$markdown
#> [1] TRUE
opts$load
#> [1] "pkgload"

# roxygen2 does not overwrite an Rd file that it did not write itself.
pkg <- file.path(tempdir(), "demo")
dir.create(file.path(pkg, "R"), recursive = TRUE)
dir.create(file.path(pkg, "man"))
writeLines(c(
  "Package: demo",
  "Title: A Demonstration",
  "Version: 0.0.1",
  "Description: Shows what roxygen2 writes.",
  "License: MIT",
  "Encoding: UTF-8",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))
writeLines(c(
  "#' Take a book out",
  "#' @export",
  "loan_book <- function() 1"
), file.path(pkg, "R", "loan.R"))
writeLines(c(
  "\\name{loan_book}",
  "\\alias{loan_book}",
  "\\title{Written by hand}",
  "\\description{Not generated.}"
), file.path(pkg, "man", "loan_book.Rd"))

msg <- capture.output(roxygen2::roxygenise(pkg), type = "message")
sub("\\(<file://.*>\\)", "(man/loan_book.Rd)", msg)
#> [1] "First time using roxygen2. Upgrading automatically..."
#> [2] "ℹ Setting Config/roxygen2/version to \"8.1.1\""
#> [3] "ℹ Loading demo"
#> [4] "Writing 'NAMESPACE'"
#> [5] "✖ Skipping loan_book.Rd (man/loan_book.Rd)"
#> [6] "ℹ It already exists and was not generated by roxygen2."
cat(readLines(file.path(pkg, "man", "loan_book.Rd")), sep = "\n")
#> \name{loan_book}
#> \alias{loan_book}
#> \title{Written by hand}
#> \description{Not generated.}

# Start from a package with no man/ and no NAMESPACE, as after use_r() only.
unlink(c("man", "NAMESPACE"), recursive = TRUE)
list.files()
#>  [1] "cran-comments.md" "data"             "data-raw"         "DESCRIPTION"
#>  [5] "inst"             "LICENSE"          "LICENSE.md"       "NEWS.md"
#>  [9] "R"                "tests"            "vignettes"

# First run: every [fn()] link to a topic that does not exist yet is reported.
# The messages are collected so that the listing can be shortened below.
first <- capture.output(devtools::document(), type = "message")
length(first)
#> [1] 83
head(first, 9)
#> [1] "ℹ Updating shelf documentation"
#> [2] "ℹ Loading shelf"
#> [3] "shelf 0.1.0: loan period is 21 days"
#> [4] "✖ book.R:3: @description Could not resolve link to topic \"normalise_isbn\" in"
#> [5] "  the dependencies or base packages.."
#> [6] "ℹ If you haven't documented \"normalise_isbn\" yet, or just changed its name,"
#> [7] "  this is normal. Once \"normalise_isbn\" is documented, this warning goes away."
#> [8] "ℹ Make sure that the name of the topic is spelled correctly."
#> [9] "ℹ Always list the linked package as a dependency."
grep("^[✖]", first, value = TRUE)
#>  [1] "✖ book.R:3: @description Could not resolve link to topic \"normalise_isbn\" in"
#>  [2] "✖ clean.R:10: @param Could not resolve link to topic \"books\" in the"
#>  [3] "✖ clean.R:11: @param Could not resolve link to topic \"loans\" in the"
#>  [4] "✖ data.R:3: @description Could not resolve link to topic \"clean_books\" in the"
#>  [5] "✖ data.R:25: @description Could not resolve link to topic \"books\" in the"
#>  [6] "✖ data.R:25: @description Could not resolve link to topic \"clean_loans\" in the"
#>  [7] "✖ loans.R:8: @param Could not resolve link to topic \"loans\" in the dependencies"
#>  [8] "✖ loans.R:8: @param Could not resolve link to topic \"clean_loans\" in the"
#>  [9] "✖ loans.R:42: @description Could not resolve link to topic \"overdue_loans\" in"
#> [10] "✖ loans.R:47: @param Could not resolve link to topic \"clean_books\" in the"
tail(first, 10)
#>  [1] "Writing 'NAMESPACE'"          "Writing 'book.Rd'"
#>  [3] "Writing 'book-methods.Rd'"    "Writing 'clean_books.Rd'"
#>  [5] "Writing 'books.Rd'"           "Writing 'loans.Rd'"
#>  [7] "Writing 'normalise_isbn.Rd'"  "Writing 'overdue_loans.Rd'"
#>  [9] "Writing 'loan_summary.Rd'"    "Writing 'loans_per_month.Rd'"

# Second run: the topics exist, so the links resolve and nothing is reported.
devtools::document()
#> ℹ Updating shelf documentation
#> ℹ Loading shelf
#> shelf 0.1.0: loan period is 21 days
list.files("man")
#> [1] "book-methods.Rd"    "book.Rd"            "books.Rd"
#> [4] "clean_books.Rd"     "loan_summary.Rd"    "loans_per_month.Rd"
#> [7] "loans.Rd"           "normalise_isbn.Rd"  "overdue_loans.Rd"

Package: shelf
Title: Tools for a Small Library Catalogue
Version: 0.1.0
Authors@R:
    person("Shelf", "Maintainers", , "maintainer@example.com", role = c("aut", "cre", "cph"))
Description: Cleans a small library catalogue and its loans table,
    validates ISBN-13 strings, and reports overdue loans and overdue rates
    by genre. Ships the example 'books' and 'loans' datasets used by the
    documentation.
License: MIT + file LICENSE
Config/roxygen2/version: 8.1.1
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
Suggests:
    knitr,
    rmarkdown,
    testthat (>= 3.0.0),
    withr
Config/testthat/edition: 3
Depends:
    R (>= 4.1.0)
VignetteBuilder: knitr
LazyData: true

# What roxygen2's markdown support writes for links, code, lists and tables.
pkg <- file.path(tempdir(), "mddemo")
dir.create(file.path(pkg, "R"), recursive = TRUE)
writeLines(c(
  "Package: mddemo",
  "Title: Markdown in roxygen2",
  "Version: 0.0.1",
  "Description: Shows the markdown to Rd translation.",
  "License: MIT",
  "Encoding: UTF-8",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))

writeLines(r"(#' Markdown forms
#'
#' Links: [mean()], [stats::median()], [base::paste], [the mean][mean] and
#' <https://roxygen2.r-lib.org>. Code: `x[1]` and `a b`.
#' Emphasis: *one* and **two**. A literal percent sign: 50% of 100%.
#'
#' @details
#' ## A subsection
#' 1. first
#' 2. second
#'
#' | genre   | loans |
#' | ------- | ----: |
#' | Fiction |    12 |
#'
#' ```
#' x <- 1:3
#' sum(x)
#' ```
#'
#' Evaluated while documenting: 6 * 7 is `r 6 * 7`.
#'
#' @param x Anything.
#' @examplesIf interactive()
#' browseURL("https://roxygen2.r-lib.org")
#' @export
md_forms <- function(x) NULL
)", file.path(pkg, "R", "md.R"))

invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
cat(readLines(file.path(pkg, "man", "md_forms.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/md.R
#> \name{md_forms}
#> \alias{md_forms}
#> \title{Markdown forms}
#> \usage{
#> md_forms(x)
#> }
#> \arguments{
#> \item{x}{Anything.}
#> }
#> \description{
#> Links: \code{\link[=mean]{mean()}}, \code{\link[stats:median]{stats::median()}}, \link[base:paste]{base::paste}, \link[=mean]{the mean} and
#> \url{https://roxygen2.r-lib.org}. Code: \code{x[1]} and \verb{a b}.
#> Emphasis: \emph{one} and \strong{two}. A literal percent sign: 50\% of 100\%.
#> }
#> \details{
#> \subsection{A subsection}{
#> \enumerate{
#> \item first
#> \item second
#> }\tabular{lr}{
#>    genre \tab loans \cr
#>    Fiction \tab 12 \cr
#> }
#>
#>
#> \if{html}{\out{<div class="sourceCode">}}\preformatted{x <- 1:3
#> sum(x)
#> }\if{html}{\out{</div>}}
#>
#> Evaluated while documenting: 6 * 7 is 42.
#> }
#> }
#> \examples{
#> \dontshow{if (interactive()) withAutoprint(\{ # examplesIf}
#> browseURL("https://roxygen2.r-lib.org")
#> \dontshow{\}) # examplesIf}
#> }

# Reusing documentation: @inheritParams, @inheritSection, @inherit,
# @inheritDotParams, @family, @seealso, @aliases, @concept, @describeIn and
# @keywords internal, in a throwaway package.
pkg <- file.path(tempdir(), "reuse")
dir.create(file.path(pkg, "R"), recursive = TRUE)
writeLines(c(
  "Package: reuse",
  "Title: Reusing Documentation",
  "Version: 0.0.1",
  "Description: Shows the roxygen2 tags that copy documentation.",
  "License: MIT",
  "Encoding: UTF-8",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))

writeLines(r"(#' Overdue loans
#'
#' @param loans A data frame of loans.
#' @param today Reference date for loans that are still out.
#' @param ... Further arguments passed to [utils::head()].
#' @returns A data frame with the overdue rows.
#' @section Loan period:
#' A loan is overdue after 21 days.
#' @family loan analyses
#' @concept overdue
#' @export
overdue <- function(loans, today, ...) NULL

#' Overdue rate
#'
#' @inheritParams overdue
#' @inheritSection overdue Loan period
#' @inherit overdue returns
#' @inheritDotParams utils::head n
#' @param by The column to group by.
#' @family loan analyses
#' @seealso [overdue()]
#' @aliases overdue_ratio
#' @export
overdue_rate <- function(loans, today, by, ...) NULL

#' Format a loan
#'
#' @param x A loan.
#' @export
format_loan <- function(x) NULL

#' @describeIn format_loan Print a formatted loan.
#' @export
print_loan <- function(x) NULL

#' Helper that users do not need
#' @keywords internal
#' @param x Anything.
squish_loan <- function(x) x

#' Not documented as a page
#' @param x Anything.
#' @noRd
hidden_helper <- function(x) x
)", file.path(pkg, "R", "loans.R"))

invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
list.files(file.path(pkg, "man"))
#> [1] "format_loan.Rd"  "overdue_rate.Rd" "overdue.Rd"      "squish_loan.Rd"
rd <- \(name) cat(readLines(file.path(pkg, "man", name)), sep = "\n")
rd("overdue_rate.Rd")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/loans.R
#> \name{overdue_rate}
#> \alias{overdue_rate}
#> \alias{overdue_ratio}
#> \title{Overdue rate}
#> \usage{
#> overdue_rate(loans, today, by, ...)
#> }
#> \arguments{
#> \item{loans}{A data frame of loans.}
#>
#> \item{today}{Reference date for loans that are still out.}
#>
#> \item{by}{The column to group by.}
#>
#> \item{...}{
#>   Arguments passed on to \code{\link[utils:head]{utils::head}}
#>   \describe{
#>     \item{\code{n}}{an integer vector of length up to \code{dim(x)} (or 1,
#>     for non-dimensioned objects).  A \code{logical} is silently coerced to
#>     integer.  Values specify the indices to be
#>     selected in the corresponding dimension (or along the length) of the
#>     object. A positive value of \code{n[i]} includes the first/last
#>     \code{n[i]} indices in that dimension, while a negative value
#>     excludes the last/first \code{abs(n[i])}, including all remaining
#>     indices. \code{NA} or non-specified values (when \code{length(n) <
#>       length(dim(x))}) select all indices in that dimension. Must
#>     contain at least one non-missing value.}
#>   }}
#> }
#> \value{
#> A data frame with the overdue rows.
#> }
#> \description{
#> Overdue rate
#> }
#> \section{Loan period}{
#>
#> A loan is overdue after 21 days.
#> }
#>
#> \seealso{
#> \code{\link[=overdue]{overdue()}}
#>
#> Other loan analyses:
#> \code{\link[=overdue]{overdue()}}
#> }
#> \concept{loan analyses}
rd("format_loan.Rd")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/loans.R
#> \name{format_loan}
#> \alias{format_loan}
#> \alias{print_loan}
#> \title{Format a loan}
#> \usage{
#> format_loan(x)
#>
#> print_loan(x)
#> }
#> \arguments{
#> \item{x}{A loan.}
#> }
#> \description{
#> Format a loan
#> }
#> \section{Functions}{
#> \itemize{
#> \item \code{print_loan()}: Print a formatted loan.
#>
#> }}
# An internal page keeps its topic but is left out of the indices.
squish <- readLines(file.path(pkg, "man", "squish_loan.Rd"))
grep("^.(name|alias|keyword)", squish, value = TRUE)
#> [1] "\\name{squish_loan}"  "\\alias{squish_loan}" "\\keyword{internal}"

# Generated by roxygen2: do not edit by hand

S3method(format,book)
S3method(print,book)
S3method(print,summary.book)
S3method(summary,book)
export(book)
export(clean_books)
export(clean_loans)
export(is_valid_isbn13)
export(loan_summary)
export(loans_per_month)
export(new_book)
export(normalise_isbn)
export(overdue_loans)
export(validate_book)

# More tags: @include (Collate), @template, @evalRd and @md.
pkg <- file.path(tempdir(), "other")
dir.create(file.path(pkg, "R"), recursive = TRUE)
dir.create(file.path(pkg, "man-roxygen"))
writeLines(c(
  "Package: other",
  "Title: More Tags",
  "Version: 0.0.1",
  "Description: Shows a few more roxygen2 tags.",
  "License: MIT",
  "Encoding: UTF-8"
), file.path(pkg, "DESCRIPTION"))

# A template: a file in man-roxygen/ with roxygen text, used by @template.
writeLines(r"(#' @section Loan period:
#' A loan is overdue after <%= days %> days.
)", file.path(pkg, "man-roxygen", "period.R"))

writeLines(r"(#' Base function
#' @export
base_fn <- function() 1
)", file.path(pkg, "R", "a-base.R"))

writeLines(r"(#' @include a-base.R
NULL

#' Overdue
#'
#' Plain Rd here, markdown is off: \code{x} and \emph{y}.
#' @template period
#' @templateVar days 21
#' @evalRd paste0("\\note{This page lists ", length(letters), " letters.}")
#' @export
overdue <- function() base_fn()

#' Markdown on for one block
#'
#' This has `code`, and *emphasis*.
#' @md
#' @export
md_block <- function() 1
)", file.path(pkg, "R", "b-overdue.R"))

invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
cat(readLines(file.path(pkg, "DESCRIPTION")), sep = "\n")
#> Package: other
#> Title: More Tags
#> Version: 0.0.1
#> Description: Shows a few more roxygen2 tags.
#> License: MIT
#> Encoding: UTF-8
#> Config/roxygen2/version: 8.1.1
#> Collate:
#>     'a-base.R'
#>     'b-overdue.R'
cat(readLines(file.path(pkg, "man", "overdue.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/b-overdue.R
#> \name{overdue}
#> \alias{overdue}
#> \title{Overdue}
#> \usage{
#> overdue()
#> }
#> \description{
#> Plain Rd here, markdown is off: \code{x} and \emph{y}.
#> }
#> \section{Loan period}{
#>
#> A loan is overdue after 21 days.
#> }
#>
#> \note{This page lists 26 letters.}
cat(readLines(file.path(pkg, "man", "md_block.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/b-overdue.R
#> \name{md_block}
#> \alias{md_block}
#> \title{Markdown on for one block}
#> \usage{
#> md_block()
#> }
#> \description{
#> This has \code{code}, and \emph{emphasis}.
#> }

# Messages roxygen2 prints for common mistakes in a throwaway package.
pkg <- file.path(tempdir(), "warn")
dir.create(file.path(pkg, "R"), recursive = TRUE)
writeLines(c(
  "Package: warn",
  "Title: Mistakes",
  "Version: 0.0.1",
  "Description: Shows roxygen2 messages.",
  "License: MIT",
  "Encoding: UTF-8",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))

writeLines(r"(#' Two lines for a one-line tag
#'
#' The edition is on page
#' 1. Clearly not a list, but commonmark makes one.
#' @concept first
#'   second
#' @param y An argument that does not exist
#' @param x Fine.
#' @export
one <- function(x) x

#' A method that is not exported
#'
#' @param x Anything.
#' @param ... Not used.
print.one <- function(x, ...) x

#' Unknown tag
#' @retruns A value.
#' @param x Anything.
two <- function(x) x
)", file.path(pkg, "R", "bad.R"))

msg <- capture.output(roxygen2::roxygenise(pkg), type = "message")
sub(pkg, "~/warn", msg, fixed = TRUE)
#>  [1] "First time using roxygen2. Upgrading automatically..."
#>  [2] "ℹ Setting Config/roxygen2/version to \"8.1.1\""
#>  [3] "ℹ Loading warn"
#>  [4] "✖ bad.R:5: @concept must be only 1 line long, not 2."
#>  [5] "ℹ The first line is \"first\""
#>  [6] "✖ bad.R:19: @retruns is not a known tag."
#>  [7] "✖ bad.R:16: S3 method `print.one` needs @export or @exportS3Method tag."
#>  [8] "Writing 'NAMESPACE'"
#>  [9] "Writing 'one.Rd'"
#> [10] "Writing 'print.one.Rd'"
#> [11] "Writing 'two.Rd'"

# The line that began with 1. became a list item, and the @param for the
# argument y that does not exist was written to the page anyway.
cat(readLines(file.path(pkg, "man", "one.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/bad.R
#> \name{one}
#> \alias{one}
#> \title{Two lines for a one-line tag}
#> \usage{
#> one(x)
#> }
#> \arguments{
#> \item{x}{Fine.}
#>
#> \item{y}{An argument that does not exist}
#> }
#> \description{
#> The edition is on page
#> \enumerate{
#> \item Clearly not a list, but commonmark makes one.
#> }
#> }
#> \concept{first
#>   second}

#' The shelf catalogue
#'
#' Sixteen books of a small library, as they were typed into the catalogue:
#' titles with stray blanks and inconsistent case, two spellings of one
#' author, genres in several spellings, hyphenated and bare ISBNs (one
#' missing, one with a wrong check digit) and missing years and page counts.
#' [clean_books()] tidies it.
#'
#' @format A data frame with 16 rows and 6 columns:
#' \describe{
#'   \item{title}{Title (character).}
#'   \item{author}{Author (character).}
#'   \item{isbn}{ISBN-13, hyphenated or bare (character).}
#'   \item{year}{Publication year (integer).}
#'   \item{genre}{Genre (character).}
#'   \item{pages}{Number of pages (integer).}
#' }
#' @source Synthetic data generated for this package; the ISBNs have valid
#'   check digits but are not the ISBNs of real books.
#' @family datasets
"books"

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{books}
\alias{books}
\title{The shelf catalogue}
\format{
A data frame with 16 rows and 6 columns:
\describe{
\item{title}{Title (character).}
\item{author}{Author (character).}
\item{isbn}{ISBN-13, hyphenated or bare (character).}
\item{year}{Publication year (integer).}
\item{genre}{Genre (character).}
\item{pages}{Number of pages (integer).}
}
}
\source{
Synthetic data generated for this package; the ISBNs have valid
check digits but are not the ISBNs of real books.
}
\usage{
books
}
\description{
Sixteen books of a small library, as they were typed into the catalogue:
titles with stray blanks and inconsistent case, two spellings of one
author, genres in several spellings, hyphenated and bare ISBNs (one
missing, one with a wrong check digit) and missing years and page counts.
\code{\link[=clean_books]{clean_books()}} tidies it.
}
\seealso{
Other datasets:
\code{\link{loans}}
}
\concept{datasets}
\keyword{datasets}

# How the page of a data set renders in a terminal.
tools::Rd2txt("man/books.Rd", options = list(underline_titles = FALSE))
#> The shelf catalogue
#>
#> Description:
#>
#>      Sixteen books of a small library, as they were typed into the
#>      catalogue: titles with stray blanks and inconsistent case, two
#>      spellings of one author, genres in several spellings, hyphenated
#>      and bare ISBNs (one missing, one with a wrong check digit) and
#>      missing years and page counts. ‘clean_books()’ tidies it.
#>
#> Usage:
#>
#>      books
#>
#> Format:
#>
#>      A data frame with 16 rows and 6 columns:
#>
#>      title
#>           Title (character).
#>
#>      author
#>           Author (character).
#>
#>      isbn
#>           ISBN-13, hyphenated or bare (character).
#>
#>      year
#>           Publication year (integer).
#>
#>      genre
#>           Genre (character).
#>
#>      pages
#>           Number of pages (integer).
#>
#> Source:
#>
#>      Synthetic data generated for this package; the ISBNs have valid
#>      check digits but are not the ISBNs of real books.
#>
#> See Also:
#>
#>      Other datasets: ‘loans’
#>

# Build the `books` and `loans` datasets from the CSV files in data-raw/.
books <- read.csv("data-raw/books.csv")
loans <- read.csv("data-raw/loans.csv", colClasses = "character")
loans$loan_date <- as.Date(loans$loan_date, format = "%Y-%m-%d")
loans$return_date <- as.Date(loans$return_date, format = "%Y-%m-%d")
usethis::use_data(books, loans, overwrite = TRUE)

# Internal data: the ISBN-13 check-digit weights used by is_valid_isbn13().
isbn_weights <- rep(c(1L, 3L), length.out = 13L)
usethis::use_data(isbn_weights, internal = TRUE, overwrite = TRUE)

# The usethis helpers that set up documentation files, run on a copy.
src <- normalizePath(".")
tmp <- file.path(tempdir(), "uc")
dir.create(tmp)
invisible(file.copy(src, tmp, recursive = TRUE))
pkg <- file.path(tmp, basename(src))

msg <- capture.output(
  usethis::with_project(pkg, {
    usethis::use_pkgdown()
    usethis::use_readme_rmd(open = FALSE)
    usethis::use_package_doc(open = FALSE)
  }),
  type = "message"
)
msg[!grepl("active project", msg)]
#>  [1] "✔ Adding \"^_pkgdown\\\\.yml$\", \"^docs$\", and \"^pkgdown$\" to '.Rbuildignore'."
#>  [2] "✔ Adding \"docs\" to '.gitignore'."
#>  [3] "✔ Writing '_pkgdown.yml'."
#>  [4] "☐ Edit '_pkgdown.yml'."
#>  [5] "✔ Writing 'README.Rmd'."
#>  [6] "✔ Adding \"^README\\\\.Rmd$\" to '.Rbuildignore'."
#>  [7] "☐ Update 'README.Rmd' to include installation instructions."
#>  [8] "☐ Use `devtools::build_readme()` to render 'README.Rmd'."
#>  [9] "✔ Writing 'R/shelf-package.R'."
#> [10] "☐ Run `devtools::document()` to update package-level documentation."

cat(readLines(file.path(pkg, "_pkgdown.yml")), sep = "\n")
#> url: ~
#> template:
#>   bootstrap: 5
#>
cat(readLines(file.path(pkg, "R", "shelf-package.R")), sep = "\n")
#> #' @keywords internal
#> "_PACKAGE"
#>
#> ## usethis namespace: start
#> ## usethis namespace: end
#>
#> ## mockable bindings: start
#> ## mockable bindings: end
#> NULL
head(readLines(file.path(pkg, "README.Rmd")), 4)
#> [1] "---"                     "output: github_document"
#> [3] "---"                     ""

# The package-level page that roxygen2 writes for "_PACKAGE".
invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
cat(readLines(file.path(pkg, "man", "shelf-package.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/shelf-package.R
#> \docType{package}
#> \name{shelf-package}
#> \alias{shelf}
#> \alias{shelf-package}
#> \title{shelf: Tools for a Small Library Catalogue}
#> \description{
#> Cleans a small library catalogue and its loans table, validates ISBN-13 strings, and reports overdue loans and overdue rates by genre. Ships the example 'books' and 'loans' datasets used by the documentation.
#> }
#> \author{
#> \strong{Maintainer}: Shelf Maintainers \email{maintainer@example.com} [copyright holder]
#>
#> Authors:
#> \itemize{
#>   \item Shelf Maintainers \email{maintainer@example.com} [copyright holder]
#> }
#>
#> }
#> \keyword{internal}

#' Methods for the `book` class
#'
#' `format()` renders a book as `"<title> (<author>, <year>)"`, `print()`
#' shows that line with a `<book>` marker and `summary()` returns a small
#' `summary.book` object with its own print method.
#'
#' @param x,object A `book` object (for `print.summary.book()`, a
#'   `summary.book` object).
#' @param ... Ignored, present for compatibility with the generics.
#' @returns `format.book()` returns a string; `print.book()` and
#'   `print.summary.book()` return their argument invisibly;
#'   `summary.book()` returns a list of class `summary.book` with the
#'   elements `title`, `has_isbn` and `pages`.
#' @examples
#' b <- book("Salt and Static", "Mara Quill", "978-0-01-400145-3", 2018,
#'           "Mystery", 244)
#' format(b)
#' print(b)
#' s <- summary(b)
#' class(s)
#' s
#' @family book class
#' @name book-methods
NULL

#' @rdname book-methods
#' @export
format.book <- function(x, ...) {
  year <- if (is.na(x$year)) "n.d." else x$year
  sprintf("%s (%s, %s)", x$title, x$author, year)
}

#' @rdname book-methods
#' @export
print.book <- function(x, ...) {

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/book.R
\name{book-methods}
\alias{book-methods}
\alias{format.book}
\alias{print.book}
\alias{summary.book}
\alias{print.summary.book}
\title{Methods for the \code{book} class}
\usage{
\method{format}{book}(x, ...)

\method{print}{book}(x, ...)

\method{summary}{book}(object, ...)

\method{print}{summary.book}(x, ...)
}
\arguments{
\item{x, object}{A \code{book} object (for \code{print.summary.book()}, a
\code{summary.book} object).}

\item{...}{Ignored, present for compatibility with the generics.}
}
\value{
\code{format.book()} returns a string; \code{print.book()} and
\code{print.summary.book()} return their argument invisibly;
\code{summary.book()} returns a list of class \code{summary.book} with the
elements \code{title}, \code{has_isbn} and \code{pages}.
}
\description{
\code{format()} renders a book as \code{"<title> (<author>, <year>)"}, \code{print()}
shows that line with a \verb{<book>} marker and \code{summary()} returns a small
\code{summary.book} object with its own print method.
}
\examples{
b <- book("Salt and Static", "Mara Quill", "978-0-01-400145-3", 2018,
          "Mystery", 244)
format(b)
print(b)
s <- summary(b)
class(s)
s
}
\seealso{
Other book class:
\code{\link[=book]{book()}}
}
\concept{book class}

# Documenting S4: a class with @slot, a generic and its methods.
pkg <- file.path(tempdir(), "s4demo")
dir.create(file.path(pkg, "R"), recursive = TRUE)
writeLines(c(
  "Package: s4demo",
  "Title: Documenting S4",
  "Version: 0.0.1",
  "Description: Shows how roxygen2 documents S4 classes.",
  "License: MIT",
  "Encoding: UTF-8",
  "Imports: methods",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))

writeLines(r"(#' A book (S4)
#'
#' @slot title Title of the book (a string).
#' @slot author Author (a string).
#' @slot isbn ISBN-13 without hyphens (a string).
#' @slot year Publication year (an integer).
#' @slot genre Genre (a string).
#' @slot pages Number of pages (an integer).
#' @export
setClass("Book", slots = c(
  title = "character", author = "character", isbn = "character",
  year = "integer", genre = "character", pages = "integer"
))

#' Describe an object
#'
#' @param x An object.
#' @returns A string.
#' @export
setGeneric("describe", function(x) standardGeneric("describe"))

#' @rdname describe
#' @export
setMethod("describe", "Book", function(x) x@title)

#' @param object A [Book-class] object.
#' @rdname Book-class
#' @export
setMethod("show", "Book", function(object) {
  cat("<Book>", object@title, "\n")
})
)", file.path(pkg, "R", "book.R"))

invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
list.files(file.path(pkg, "man"))
#> [1] "Book-class.Rd" "describe.Rd"
cat(readLines(file.path(pkg, "man", "Book-class.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/book.R
#> \docType{class}
#> \name{Book-class}
#> \alias{Book-class}
#> \alias{show,Book-method}
#> \title{A book (S4)}
#> \usage{
#> \S4method{show}{Book}(object)
#> }
#> \arguments{
#> \item{object}{A \link[=Book-class]{Book} object.}
#> }
#> \description{
#> A book (S4)
#> }
#> \section{Slots}{
#>
#> \describe{
#> \item{\code{title}}{Title of the book (a string).}
#>
#> \item{\code{author}}{Author (a string).}
#>
#> \item{\code{isbn}}{ISBN-13 without hyphens (a string).}
#>
#> \item{\code{year}}{Publication year (an integer).}
#>
#> \item{\code{genre}}{Genre (a string).}
#>
#> \item{\code{pages}}{Number of pages (an integer).}
#> }}
#>
cat(readLines(file.path(pkg, "man", "describe.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/book.R
#> \name{describe}
#> \alias{describe}
#> \alias{describe,Book-method}
#> \title{Describe an object}
#> \usage{
#> describe(x)
#>
#> \S4method{describe}{Book}(x)
#> }
#> \arguments{
#> \item{x}{An object.}
#> }
#> \value{
#> A string.
#> }
#> \description{
#> Describe an object
#> }
cat(readLines(file.path(pkg, "NAMESPACE")), sep = "\n")
#> # Generated by roxygen2: do not edit by hand
#>
#> export(describe)
#> exportClasses(Book)
#> exportMethods(describe)
#> exportMethods(show)

# Documenting R6: fields and methods are documented inside the class.
pkg <- file.path(tempdir(), "r6demo")
dir.create(file.path(pkg, "R"), recursive = TRUE)
writeLines(c(
  "Package: r6demo",
  "Title: Documenting R6",
  "Version: 0.0.1",
  "Description: Shows how roxygen2 documents R6 classes.",
  "License: MIT",
  "Encoding: UTF-8",
  "Imports: R6",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))

writeLines(r"(#' A shelf of books (R6)
#'
#' Keeps the titles on one shelf.
#' @export
Shelf <- R6::R6Class("Shelf",
  public = list(
    #' @field name Name of the shelf.
    name = NULL,

    #' @description
    #' Create a shelf.
    #' @param name Name of the shelf.
    #' @returns A new `Shelf`.
    initialize = function(name) {
      self$name <- name
    },

    #' @description
    #' Add a title.
    #' @param title Title to add.
    #' @returns The shelf, invisibly, so calls can be chained.
    add = function(title) {
      private$titles <- c(private$titles, title)
      invisible(self)
    }
  ),
  active = list(
    #' @field size Number of titles (read-only).
    size = function() length(private$titles)
  ),
  private = list(titles = character())
)
)", file.path(pkg, "R", "shelf.R"))

invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
list.files(file.path(pkg, "man"))
#> [1] "Shelf.Rd"
shelf_rd <- readLines(file.path(pkg, "man", "Shelf.Rd"))
length(shelf_rd)
#> [1] 94
cat(head(shelf_rd, 44), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/shelf.R
#> \name{Shelf}
#> \alias{Shelf}
#> \title{A shelf of books (R6)}
#> \description{
#> Keeps the titles on one shelf.
#> }
#> \section{Public fields}{
#>   \if{html}{\out{<div class="r6-fields">}}
#>   \describe{
#>     \item{\code{name}}{Name of the shelf.}
#>   }
#>   \if{html}{\out{</div>}}
#> }
#> \section{Active bindings}{
#>   \if{html}{\out{<div class="r6-active-bindings">}}
#>   \describe{
#>     \item{\code{size}}{Number of titles (read-only).}
#>   }
#>   \if{html}{\out{</div>}}
#> }
#> \section{Methods}{
#> \subsection{Public methods}{
#>   \itemize{
#>     \item \href{#method-Shelf-initialize}{\code{Shelf$new()}}
#>     \item \href{#method-Shelf-add}{\code{Shelf$add()}}
#>     \item \href{#method-Shelf-clone}{\code{Shelf$clone()}}
#>   }
#> }
#> \if{html}{\out{<hr>}}
#> \if{html}{\out{<a id="method-Shelf-initialize"></a>}}
#> \if{latex}{\out{\hypertarget{method-Shelf-initialize}{}}}
#> \subsection{\code{Shelf$new()}}{
#>   Create a shelf.
#>   \subsection{Usage}{
#>     \if{html}{\out{<div class="r">}}
#>     \preformatted{Shelf$new(name)}
#>     \if{html}{\out{</div>}}
#>   }
#>   \subsection{Arguments}{
#>     \if{html}{\out{<div class="arguments">}}
#>     \describe{
#>       \item{\code{name}}{Name of the shelf.}

# Documenting S7 (roxygen2 8.x with S7 0.2.2): class, generic and method.
pkg <- file.path(tempdir(), "s7demo")
dir.create(file.path(pkg, "R"), recursive = TRUE)
writeLines(c(
  "Package: s7demo",
  "Title: Documenting S7",
  "Version: 0.0.1",
  "Description: Shows how roxygen2 documents S7 classes.",
  "License: MIT",
  "Encoding: UTF-8",
  "Depends: R (>= 4.3.0)",
  "Imports: S7",
  "Config/roxygen2/markdown: TRUE"
), file.path(pkg, "DESCRIPTION"))

writeLines(r"(#' A book (S7)
#'
#' @param title Title of the book.
#' @param year Publication year.
#' @prop age Age of the book in 2026 (read-only).
#' @returns A `Book` object.
#' @export
Book <- S7::new_class("Book",
  properties = list(
    title = S7::class_character,
    year = S7::class_integer,
    age = S7::new_property(
      S7::class_integer,
      getter = function(self) 2026L - self@year
    )
  )
)

#' Describe an object
#'
#' @param x An object.
#' @param ... Not used.
#' @returns A string.
#' @export
describe <- S7::new_generic("describe", "x")

#' Describe a book
#'
#' The description of a [Book] is its title; see [describe()].
#'
#' @param x A [Book].
#' @param ... Not used.
#' @returns The title.
S7::method(describe, Book) <- function(x, ...) x@title

.onLoad <- function(libname, pkgname) {
  S7::methods_register()
}
)", file.path(pkg, "R", "book.R"))

invisible(capture.output(roxygen2::roxygenise(pkg), type = "message"))
man <- file.path(pkg, "man")
list.files(man)
#> [1] "Book.Rd"                        "describe-s7demo-Book-method.Rd"
#> [3] "describe.Rd"
cat(readLines(file.path(man, "Book.Rd")), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/book.R
#> \name{Book}
#> \alias{Book}
#> \title{A book (S7)}
#> \usage{
#> Book(title = character(0), year = integer(0))
#> }
#> \arguments{
#> \item{title}{Title of the book.}
#>
#> \item{year}{Publication year.}
#> }
#> \value{
#> A \code{Book} object.
#> }
#> \description{
#> A book (S7)
#> }
#> \section{Additional properties}{
#>
#> \describe{
#> \item{\code{@age}}{Age of the book in 2026 (read-only).}
#> }}
#>
method_rd <- list.files(man, pattern = "method", full.names = TRUE)
cat(readLines(method_rd), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/book.R
#> \name{describe,s7demo::Book-method}
#> \alias{describe,s7demo::Book-method}
#> \title{Describe a book}
#> \usage{
#> ## S7 method for class <s7demo::Book>
#> \special{describe(x, ...)}
#> }
#> \arguments{
#> \item{x}{A \link{Book}.}
#>
#> \item{...}{Not used.}
#> }
#> \value{
#> The title.
#> }
#> \description{
#> The description of a \link{Book} is its title; see \code{\link[=describe]{describe()}}.
#> }
cat(readLines(file.path(pkg, "NAMESPACE")), sep = "\n")
#> # Generated by roxygen2: do not edit by hand
#>
#> export(Book)
#> export(describe)

---
title: "Analysing library loans with shelf"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Analysing library loans with shelf}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The shelf package ships a small, deliberately messy library catalogue and
its loans, and the few functions needed to clean them and answer two
questions: which loans are overdue, and how the overdue rate differs by
genre. This vignette walks through that analysis with a fixed reference
date so that its results do not change from one build to the next.

```{r setup}
library(shelf)
today <- as.Date("2026-06-30")
```

## Cleaning the catalogue

```{r clean}
catalogue <- clean_books(books)
head(catalogue, 4)
table(catalogue$genre)
```

## Overdue loans

```{r overdue}
out <- overdue_loans(loans, today = today)
nrow(out)
head(out[order(-out$days_out), ], 5)
```

## Overdue rate by genre

```{r summary}
loan_summary(loans, catalogue, today = today)
```

## Loans per month

```{r months, fig.width = 7, fig.height = 3.5}
monthly <- loans_per_month(loans)
barplot(monthly$loans, names.arg = monthly$month, las = 2,
        main = "Loans per month", ylab = "Loans")
```

# usethis::use_vignette() on a copy of the package: a second vignette.
src <- normalizePath(".")
tmp <- file.path(tempdir(), "vig")
dir.create(tmp)
invisible(file.copy(src, tmp, recursive = TRUE))
pkg <- file.path(tmp, basename(src))

msg <- capture.output(
  usethis::with_project(
    pkg,
    usethis::use_vignette("loans-by-genre", "Overdue loans by genre")
  ),
  type = "message"
)
msg[!grepl("active project", msg)]
#> [1] "✔ Writing 'vignettes/loans-by-genre.Rmd'."
#> [2] "☐ Edit 'vignettes/loans-by-genre.Rmd'."
list.files(file.path(pkg, "vignettes"), all.files = TRUE, no.. = TRUE)
#> [1] ".gitignore"         "loans-by-genre.Rmd" "shelf.Rmd"
cat(readLines(file.path(pkg, "vignettes", "loans-by-genre.Rmd")), sep = "\n")
#> ---
#> title: "Overdue loans by genre"
#> output: rmarkdown::html_vignette
#> vignette: >
#>   %\VignetteIndexEntry{Overdue loans by genre}
#>   %\VignetteEngine{knitr::rmarkdown}
#>   %\VignetteEncoding{UTF-8}
#> ---
#>
#> ```{r, include = FALSE}
#> knitr::opts_chunk$set(
#>   collapse = TRUE,
#>   comment = "#>"
#> )
#> ```
#>
#> ```{r setup}
#> library(shelf)
#> ```
# The end of DESCRIPTION, where the helper works.
desc <- readLines(file.path(pkg, "DESCRIPTION"))
desc[seq(grep("^Suggests", desc), length(desc))]
#>  [1] "Suggests: "                 "    knitr,"
#>  [3] "    rmarkdown,"             "    testthat (>= 3.0.0),"
#>  [5] "    withr"                  "Config/testthat/edition: 3"
#>  [7] "Depends: "                  "    R (>= 4.1.0)"
#>  [9] "VignetteBuilder: knitr"     "LazyData: true"

*.html
*.R

# R CMD build renders the vignette into inst/doc of the tarball.
src <- normalizePath(".")
tmp <- file.path(tempdir(), "build")
dir.create(tmp)
invisible(file.copy(src, tmp, recursive = TRUE))
r_cmd <- \(...) {
  withr::with_dir(tmp, system2("R", c("CMD", ...),
                               stdout = TRUE, stderr = TRUE))
}
tarball <- file.path(tmp, "shelf_0.1.0.tar.gz")
in_tarball <- \(pattern) {
  grep(pattern, utils::untar(tarball, list = TRUE), value = TRUE)
}

r_cmd("build", "shelf")
#> [1] "* checking for file ‘shelf/DESCRIPTION’ ... OK"
#> [2] "* preparing ‘shelf’:"
#> [3] "* checking DESCRIPTION meta-information ... OK"
#> [4] "* installing the package (it is needed to build vignettes)"
#> [5] "* creating vignettes ... OK"
#> [6] "* checking for LF line-endings in source and make files and shell scripts"
#> [7] "* checking for empty or unneeded directories"
#> [8] "* building ‘shelf_0.1.0.tar.gz’"
#> [9] ""
in_tarball("vignettes|inst/doc|build/")
#> [1] "shelf/build/"              "shelf/build/vignette.rds"
#> [3] "shelf/inst/doc/"           "shelf/inst/doc/shelf.R"
#> [5] "shelf/inst/doc/shelf.Rmd"  "shelf/inst/doc/shelf.html"
#> [7] "shelf/vignettes/"          "shelf/vignettes/shelf.Rmd"

# The same build without the vignettes (as --no-build-vignettes asks).
unlink(tarball)
r_cmd("build", "--no-build-vignettes", "shelf")
#> [1] "* checking for file ‘shelf/DESCRIPTION’ ... OK"
#> [2] "* preparing ‘shelf’:"
#> [3] "* checking DESCRIPTION meta-information ... OK"
#> [4] "* checking for LF line-endings in source and make files and shell scripts"
#> [5] "* checking for empty or unneeded directories"
#> [6] "* building ‘shelf_0.1.0.tar.gz’"
#> [7] ""
in_tarball("vignettes|inst/doc|build/")
#> [1] "shelf/vignettes/"          "shelf/vignettes/shelf.Rmd"

# R CMD check notices that the sources have no outputs next to them.
res <- r_cmd("check", "--no-manual", "--no-tests", "--no-examples",
             "shelf_0.1.0.tar.gz")
step <- \(title) {
  i <- grep(title, res, fixed = TRUE)
  res[i:(i + 3L)]
}
step("checking files in ‘vignettes’")
#> [1] "* checking files in ‘vignettes’ ... WARNING"
#> [2] "Files in the 'vignettes' directory but no files in 'inst/doc':"
#> [3] "  ‘shelf.Rmd’"
#> [4] "* checking examples ... SKIPPED"
step("checking package vignettes")
#> [1] "* checking package vignettes ... WARNING"
#> [2] "Directory 'inst/doc' does not exist."
#> [3] "Package vignette without corresponding single PDF/HTML:"
#> [4] "  ‘shelf.Rmd’"
grep("^Status", res, value = TRUE)
#> [1] "Status: 2 WARNINGs"

# Rendering the vignettes of a source tree without building the tarball.
src <- normalizePath(".")
tmp <- file.path(tempdir(), "dev")
dir.create(tmp)
invisible(file.copy(src, tmp, recursive = TRUE))
pkg <- file.path(tmp, basename(src))

# devtools::build_vignettes() is deprecated since devtools 2.5.0; in this
# image it also stops, because the package remotes is not installed.
res <- withCallingHandlers(
  tryCatch(devtools::build_vignettes(pkg), error = \(e) conditionMessage(e)),
  warning = \(w) {
    cat("warning:", conditionMessage(w), "\n")
    invokeRestart("muffleWarning")
  }
)
#> warning: `build_vignettes()` was deprecated in devtools 2.5.0.
res
#> [1] "The package \"remotes\" is required."

# tools::buildVignettes() is the function under R CMD build.
out <- tools::buildVignettes(dir = pkg, tangle = TRUE)
#> --- re-building ‘shelf.Rmd’ using rmarkdown
#> --- finished re-building ‘shelf.Rmd’
#>
names(out)
#>  [1] "docs"      "names"     "engines"   "patterns"  "encodings" "dir"
#>  [7] "pkgdir"    "msg"       "outputs"   "sources"
basename(out$outputs)
#> [1] "shelf.html"
list.files(file.path(pkg, "vignettes"))
#> [1] "shelf.html" "shelf.R"    "shelf.Rmd"

# Finding the installed vignette of the package.
v <- vignette(package = "shelf")
class(v)
#> [1] "packageIQR"
data.frame(v$results[, c("Item", "Title"), drop = FALSE], row.names = NULL)
#>    Item                                             Title
#> 1 shelf Analysing library loans with shelf (source, html)

vig <- vignette("shelf", package = "shelf")
class(vig)
#> [1] "vignette"
names(vig)
#> [1] "Package" "Dir"     "Topic"   "File"    "Title"   "R"       "PDF"
basename(vig$File)
#> [1] "shelf.Rmd"
basename(vig$R)
#> [1] "shelf.R"

# The files in the installed doc directory; index.html is made at install time.
list.files(system.file("doc", package = "shelf"))
#> [1] "index.html" "shelf.html" "shelf.R"    "shelf.Rmd"

# browseVignettes() returns the same information (printing it opens a browser).
bv <- browseVignettes("shelf")
class(bv)
#> [1] "browseVignettes"
colnames(bv$shelf)
#> [1] "Package" "Dir"     "Topic"   "File"    "Title"   "R"       "PDF"
unname(bv$shelf[, "Title"])
#> [1] "Analysing library loans with shelf"

# The metadata lines of the source file, as R reads them.
info <- tools::vignetteInfo(system.file("doc", "shelf.Rmd", package = "shelf"))
info$title
#> [1] "Analysing library loans with shelf"
info$engine
#> [1] "knitr::rmarkdown"

# knitr registers its engines when it is loaded.
invisible(loadNamespace("knitr"))
sort(names(tools::vignetteEngine(package = "knitr")))
#>  [1] "knitr::docco_classic"          "knitr::docco_classic_notangle"
#>  [3] "knitr::docco_linear"           "knitr::docco_linear_notangle"
#>  [5] "knitr::knitr"                  "knitr::knitr_notangle"
#>  [7] "knitr::rmarkdown"              "knitr::rmarkdown_notangle"
#>  [9] "knitr::rtyp"                   "knitr::rtyp_notangle"

---
title: "Analysing library loans with shelf"
format: html
vignette: >
  %\VignetteIndexEntry{Analysing library loans with shelf}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

export NO_COLOR=1
cd "$(mktemp -d)"
cat > shelf.qmd <<'QMD'
---
title: "Analysing library loans with shelf"
format: html
vignette: >
  %\VignetteIndexEntry{Analysing library loans with shelf}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

```{r}
library(shelf)
nrow(overdue_loans(loans, today = as.Date("2026-06-30")))
```
QMD
quarto render shelf.qmd
ls

processing file: shelf.qmd
1/3
2/3 [unnamed-chunk-1]
3/3
output file: shelf.knit.md

pandoc
  to: html
  output-file: shelf.html
  standalone: true
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png

metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  title: Analysing library loans with shelf
  vignette: |
    %\VignetteIndexEntry{Analysing library loans with shelf} %\VignetteEngine{quarto::html} %\VignetteEncoding{UTF-8}

Output created: shelf.html

shelf_files
shelf.html
shelf.qmd