R object documentation: Package documentation as first item

Question

I have an R package and I want to display the general information about the package as first item in the created PDF manual.

I use roxygen2 (version 7.0.2) for creating the documentation and followed the instructions given here. When I create the documentation, the items appearing in the manual are all ordered alphabetically, including the item for the general documentation. But, of course, I want to have the general documentation at the top.

It seems that putting the package documentation item first must work somehow because it works in the manual of knitr.

My setup: I created a package "TestPackage" using RStudio, with one "hello.R" file:

#' Hello world function
#'
#' Prints "Hello, world!"
#'
#'@return nothing interesting
hello <- function() {
  print("Hello, world!")
}

and one "TestPackage.R" file with the general documentation for the package.

#' A test package
#'
#' @docType package
#' @name TestPackage
NULL

When I run,

R CMD Rd2pdf TestPackage

I get a PDF manual with the first item "hello" and then the item "TestPackage".

How can I achive that the item for the package comes first?

Can you try changing the line #' @name TestPackage to #' @name TestPackage-package? — duckmayr
– duckmayr, Commented Dec 31, 2019 at 20:37
Madness! Thanks, this works! If you post it as an answer, I can accept it. Although this does the job, I also would appreciate some background info on why this works, if you can give some. — esel
– esel, Commented Jan 1, 2020 at 17:27
Those instructions you quote are a little old. See here instead: cran.r-project.org/web/packages/roxygen2/vignettes/… — user2554330
– user2554330, Commented Jan 1, 2020 at 20:03

duckmayr · Accepted Answer · 2020-01-01 17:39:16Z

2

In order to ensure that the package documentation entry is first in the manual, you need its name to be <packagename>-package (where you replace <packagename> with the name of your package). Here you could accomplish that by changing

#' @name TestPackage

to

#' @name TestPackage-package

Why is this the case? Well, as always when you run into some strange corner of R package development, the best thing you can do is to consult the Writing R Extensions manual. Here, we'd want to look at Section 2.1, Rd format (the documentation files in R are in a format called Rd; roxygen creates the Rd files in man/ for you). Specifically, in Section 2.1.1, we see

\name{name}

name typically¹⁰¹ is the basename of the Rd file containing the documentation. ... Entries in the package manual will be in alphabetic¹⁰² order of the \name entries.

That footnote 102 tells us

in the current locale, and with special treatment for LaTeX special characters and with any ‘pkgname-package’ topic moved to the top of the list.

So, you have to name the Rd file as pkgname-package to move it to the top of the manual.

answered Jan 1, 2020 at 17:39

duckmayr

17k3 gold badges41 silver badges63 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

user2554330 Over a year ago

I think this happens automatically if you use the _PACKAGE sentinel described in the "Rd (documentation) tags" vignette in roxygen2.

esel Over a year ago

Can you maybe elaborate on this? How can I use this "sentinel"?

Collectives™ on Stack Overflow

R object documentation: Package documentation as first item

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related