vigindex: Generate a vignette topical index.
In rvlenth/vigindex: Index of Topics in Package Vignettes

Description Usage Arguments Details Value Index tags Links

Read indexing tags from a set of R-Markdown vignettes and create a new vignette with topic names and links to the tagged locations.

vigindex(dir = "vignettes", vignettes = dir(dir, pattern = "*.Rmd"),
  target = "vignette-topics.Rmd", navigation = c("auto", "none", "fourths",
  "letters"), ...)

compile_vi(dir = "vignettes", vignettes = dir(dir, pattern = "*.Rmd"))

add_navigation(tree, navigation = c("auto", "none", "fourths", "letters"))

write_vi(tree, dir = getwd("vignettes"), target = "vignette-topics.Rmd",
  taglines, ...)

`dir`	character name of directory where vignettes are stored
`vignettes`	character vector of names of files to index. These files should contain tags for entries in the index; see the section below on index tags.
`target`	name to store the result (in the same directory). If `target` already exists, it will be replaced, except that the initial part of it will be kept as-is. Also, `target` is excluded from being indexed, even if it is listed in `vignettes`.
`navigation`	character value determining whether links/anchors should be added to assist in jumping to other places in the index. If `"none"`, no navigation is added; if `"fourths"`, navigation points are placed at four roughly equally-spaced ponts in the index. If `"letters"`, they are placed at the beginning of each new beginning letter. If `"auto"`, it is determined by the number of main entries.
`...`	additional arguments. In particular, extra arguments in `vigindex` are passed to `write_vi`.
`tree`	An index tree such as is returned by `compile_vi`; see details under Value.
`taglines`	character vector of lines that are added to the end of the index. If not supplied, it adds a promotional link for the vigindex package.
`style`	Additional text to place at the beginning of the index. If missing, no additional visible text is added, but a standard `<style> ... </style>` string is added that should make the formatting more attractive (e.g., no bullets).

The vigindex function does everything in one call; in ordinary package development, using it with the default areguments will index all of the package's vignettes and create an index source file named "vignette-topics.Rmd". If the user wants more control over the process, they may call (in order): compile_vi, add_navigation (optionally), and write_vi.

If the target file does not exist, one is created. The user may edit the target file once created. The function looks for a line of the form <div class="vigindex" ...>. Everything after this div line will be replaced by a new set of indexing information each time vigindex is run. Everything before the div line is retained.

vigindex and write_vi return nothing, but the contents of target are created or altered, and a message indicates when it is complete.

compile_vi returns a tree structure with the compiled index. It consists of a named list of nodes. The names serve as sorting keys for the nodes. Each node is in turn a named list with three elements: text is a vector of character strings for the entry and any subentries. link is the character link to associate with the last element of text. And children is a named list of nodes of the same form as tree, containing any subsentries.

add_navigation returns an amended tree with entries for navigation links.

Indexing tags are placed within HTML comments in the vignette source files, following a special format illustrated in the following example:

### Everything you want to know about owls {#owls}
<!-- @index **Birds**!Owls; `print.owls` -->
#'     ... lines of text ...
#### Popular owls {#pop.owls}
<!-- @index birds!owls!!Screech; birds!owls!Great horned
            Birds!Owls!Barred -->
    ... lines of text ...
<!-- @index Raptors; birds!Owls!others@zzz        -->

Entries on the same line are separated by ;, and subentries are delineated by !. Sorting is done without regard to capitalization or formatting, but a different sorting key may be appended after an @ symbol. Accordingly, with the above examples, the first main entry will be Birds (in boldface and capitalized per its first appearance), with a subentry for Owls, in turn with subentries for Barred, Great horned, Screech, and others (last because of the @zzz). The next main entry will be print.owls, and finally, Raptors.

Links in the generated index will be to the latest anchor (of the form {#anchor}) found in the document, or to the top of the file if no anchors occur before the index tag.

See vignette("example", package = "vigindex") for examples and more details.

rvlenth/vigindex documentation built on May 9, 2019, 8:12 p.m.