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 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, x` | a news db obtained from `news()`.
`doBrowse` | logical specifying that the news should be opened in the browser (by `browseURL`, accessible as via `help.start`) instead of printed to the console.
`browser` | the browser to be used, see `browseURL`.
`...` | potentially further arguments passed to `print()`.

### 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.md’ (since R version 3.6.0, needs packages commonmark and xml2 to be available), ‘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. At the very end of `\section{..}`, the date may also be specified as `(%Y-%m-%d, <note>)`, i.e., including parentheses.

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 heading are taken to indicate categories. To accommodate for common practice, news entries are only split down to the category level.

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

A data frame inheriting from class `"news_db"`, with `attributes` `"package"` (and `"subset"` if the `query` lead to proper subsetting).

### Examples

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

    ## Bug fixes with PR number in 3.0.1.
    db3 <- news(Version == "3.0.1" & grepl("^BUG", Category) & grepl("PR#", Text),
                db = db)

    ## 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 >= 3.0.0 (including "3.0.0 patched"):
    table(news(Version >= "3.0.0", db = db)$Version)

[Package utils version 3.6.1 Index]