news {utils} | R Documentation |
Build and query the news for R or add-on packages.
news(query, package = "R", lib.loc = NULL, format = NULL, reader = NULL, db = NULL)
query |
an expression for selecting news entries |
package |
a character string giving the name of an installed
add-on package, or "R" . |
lib.loc |
a character vector of directory names of R libraries,
or NULL . The default value of NULL corresponds to all
libraries currently known. |
format |
Not yet used. |
reader |
Not yet used. |
db |
a news db obtained from news() . |
If package
is "R"
(default), a news db is built with the
news since the 2.10.0 release of R (corresponding to R's top-level
‘NEWS’ file). 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’ or
‘inst/NEWS’ (in that order).
File ‘inst/NEWS.Rd’ should be an Rd file given the entries as Rd
\itemizelists, grouped according to version using
sectionelements with names starting with a suitable prefix (e.g, “Changes in version” followed by a space and the version number, and optionally followed by a space and a parenthesized ISO 8601 (%Y-%m-%d, see
strptime
) format date, and
possibly further grouped according to categories using
\subsectionelements named as the categories.
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:
Additional formats and readers may be supported in the future.
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.
The news db built is a character data frame inheriting from
"news_db"
with variables Version
, Category
,
Date
and Text
, where the last contains the entry texts
read, and the other variables may be NA
if they were missing or
could not be determined.
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.
An data frame inheriting from class "news_db"
.
## Build a db of all R news entries. db <- news() ## Bug fixes with PR number in 2.11.0. news(Version == "2.11.0" & grepl("^BUG", Category) & grepl("PR#", Text), db = db) ## Entries with version >= 2.10.1 (including "2.10.1 patched"): table(news(Version >= "2.10.1", db = db)$Version)