R: Build and Query R or Package News Information

news {utils} | R Documentation

## Build and Query R or Package News Information

### Description

Build and query the news for R or add-on packages.

### Usage

    news(query, package = "R", lib.loc = NULL, format = NULL,
         reader = NULL, db = NULL)

### Arguments

`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()`.

### Details

If `package` is `"R"` (default), a news db is built with the news since the 3.0.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

    \itemize

lists, grouped according to version using

    section

elements 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

    \subsection

elements 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:

- 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.

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.

### Value

An data frame inheriting from class `"news_db"`.

### Examples

    ## Build a db of all R news entries.
    db <- news()

    ## Bug fixes with PR number in 3.0.1.
    news(Version == "3.0.1" & grepl("^BUG", Category) & grepl("PR#", Text),
         db = db)
    ## Which categories have been in use? % R-core maybe should standardize a bit more
    sort(table(db[, "Category"]), decreasing = TRUE)
    ## Entries with version >= 3.0.0 (including "3.0.0 patched"):
    table(news(Version >= "3.0.0", db = db)$Version)

[Package utils version 3.1.2 Index]