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

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.3.2 Index]