| news {utils} | R Documentation |
Build and Query R or Package News Information
Description
Build and query the news data base for R or add-on packages.
Usage
news(query, package = "R", lib.loc = NULL, format = NULL,
reader = NULL, db = NULL)
## S3 method for class 'news_db'
print(x, doBrowse = interactive(),
browser = getOption("browser"), ...)
Arguments
query |
an optional expression for selecting news entries. |
package |
a character string giving the name of an installed
add-on package, or |
lib.loc |
a character vector of directory names of R libraries,
or |
format |
Not yet used. |
reader |
Not yet used. |
db, x |
a news db obtained from |
doBrowse |
logical specifying that the news should be opened in
the browser (by |
browser |
the browser to be used, see |
... |
potentially further arguments passed to |
Details
If package is "R" (default), a news db is built with the
news since the 4.0.0 release of R, corresponding to the
‘NEWS’ file in the R.home("doc") directory.
"R-3" or "R-2" give the news for R 3.x.y
or R 2.x.y respectively. Otherwise, if the given add-on package can
be found in the given libraries, it is attempted to read its news in
structured form from files ‘inst/NEWS.Rd’, ‘NEWS.md’ (since
R version 3.6.0, needs packages commonmark and
xml2 to be available), ‘NEWS’ or ‘inst/NEWS’ (in
that order). See section ‘NEWS Formats’ for the file
specifications.
Using query, one can select news entries from the db. If
missing or NULL, the complete db is returned. Otherwise,
query should be an expression involving (a subset of) the
variables Version, Category, Date and
Text, and when evaluated within the db returning a logical
vector with length the number of entries in the db. The entries for
which evaluation gave TRUE are selected. When evaluating,
Version and Date are coerced to
numeric_version and Date objects,
respectively, so that the comparison operators for these classes can
be employed.
Value
A data frame inheriting from class "news_db", with
character variables Version, Category, Date,
Text and HTML, where the last two each contain the
entry texts read (in plain-text and HTML format, respectively), and
the other variables may be NA if they were missing or could not
be determined. The data frame has
attributes "package" (and "subset" if the
query lead to proper subsetting).
NEWS Formats
‘inst/NEWS.Rd’
File ‘inst/NEWS.Rd’ should be an Rd file given the entries as Rd
\itemize lists, grouped according to version using
\section elements. Section titles start with a suitable prefix
followed by a space and the version
number, and optionally end with a (parenthesized) ISO
8601 (%Y-%m-%d, see strptime) format date
(optionally including a note), for example:
\section{Changes in version 2.0 (2020-02-02, <note>)}{
\itemize{
\item ....
}
}
The entries can be further grouped according to categories using
\subsection elements named as the categories.
The ‘NEWS.Rd’ file is assumed to be UTF-8-encoded (but an
included \encoding specification takes precedence).
‘NEWS.md’
File ‘NEWS.md’ should contain the news in Markdown (following the CommonMark (https://commonmark.org/) specification), with the primary heading level giving the version number after a prefix followed by a space, and optionally followed by a space and a parenthesized ISO 8601 format date. Where available, secondary headings are taken to indicate categories. To accommodate for common practice, news entries are only split down to the category level.
‘NEWS’
The plain text ‘NEWS’ files in add-on packages use a variety of different formats; the default news reader should be capable to extract individual news entries from a majority of packages from the standard repositories, which use (slight variations of) the following format:
Entries are grouped according to version, with version header “Changes in version” at the beginning of a line, followed by a version number, optionally followed by an ISO 8601 format date, possibly parenthesized.
Entries may be grouped according to category, with a category header (different from a version header) starting at the beginning of a line.
Entries are written as itemize-type lists, using one of ‘o’, ‘*’, ‘-’ or ‘+’ as item tag. Entries must be indented, and ideally use a common indentation for the item texts.
Package tools provides an (internal) utility function
news2Rd to convert plain text ‘NEWS’ files to Rd. For
‘NEWS’ files in a format which can successfully be handled by the
default reader, package maintainers can use
tools:::news2Rd(dir, "NEWS.Rd"),
possibly with additional argument codify = TRUE,
with dir a character string specifying the path to a package's
root directory. Upon success, the ‘NEWS.Rd’ file can further be
improved and then be moved to the ‘inst’ subdirectory of the
package source directory.
Additional formats and readers may be supported in the future.
Examples
## Build a db of all R news entries.
db <- news()
## Bug fixes with PR number in 4.0.0.
db4 <- news(Version == "4.0.0" & grepl("^BUG", Category) & grepl("PR#", Text),
db = db)
nrow(db4)
## print db4 to show in an HTML browser.
## News from a date range ('Matrix' is there in a regular R installation):
if(length(iM <- find.package("Matrix", quiet = TRUE)) && nzchar(iM)) {
dM <- news(package="Matrix")
stopifnot(identical(dM, news(db=dM)))
dM2014 <- news("2014-01-01" <= Date & Date <= "2014-12-31", db = dM)
stopifnot(paste0("1.1-", 2:4) %in% dM2014[,"Version"])
}
## Which categories have been in use? % R-core maybe should standardize a bit more
sort(table(db[, "Category"]), decreasing = TRUE)
## Entries with version >= 4.0.0
table(news(Version >= "4.0.0", db = db)$Version)
## do the same for R 3.x.y, more slowly
db3 <- news(package = "R-3")
sort(table(db3[, "Category"]), decreasing = TRUE)
## Entries with version >= 3.6.0
table(news(Version >= "3.6.0", db = db3)$Version)