readNEWS {tools} | R Documentation

## Read R's NEWS file or a similar one

### Description

Read/check R's ‘NEWS’ file or a similarly formatted one. This was an experimental feature added in R 2.4.0: as from R 2.12.0 the preferred format is ‘NEWS.Rd’.

### Usage

    readNEWS(file = file.path(R.home(), "NEWS"), trace = FALSE,
             chop = c("first", "1", "par1", "keepAll"))
    checkNEWS(file = file.path(R.home(), "NEWS"))

### Arguments

`file` | the name of the file which the data are to be read from. Alternatively, `file` can be a `connection`, which will be opened if necessary, and can also be a complete URL. For more details, see the `file` argument of `read.table`.
`trace` | logical indicating if the recursive reading should be traced, i.e., print what it is doing.
`chop` | a character string specifying how the news entries should be chopped; `chop = "keepAll"` saves the full entries.

### Details

`readNEWS()` reads a pre-R-2.12.0-style ‘NEWS’ file; `checkNEWS()` checks for common errors in formatting. Currently it detects an incorrect number of spaces before the `"o"` item marker.

If non-ASCII characters are needed, the ‘NEWS’ file may be encoded in UTF-8 with a byte-order mark (BOM) at the beginning, which `readNEWS()` will recognize. Other encodings will display incorrectly on some systems. However, BOMs are discouraged on many systems and not all editors recognize them, so ‘NEWS’ files should normally be written in ASCII.

### Value

`readNEWS()` returns an (S3) object of class `"newsTree"`; effectively a `list` of lists which is a tree of NEWS entries.

`checkNEWS()` returns `TRUE` if no suspected errors are found, or prints a message for each suspected error and returns `FALSE`.

Note that this was only ever experimental and may be removed soon, since the NEWS-file format is not longer supported (but there are examples ‘ONEWS’, ‘OONEWS’ and perhaps in packages).

### Examples

    NEWStr  <- readNEWS(trace = TRUE)# chop = "first" ( = "first non-empty")
    ## keep the full NEWS entry text i.e. "no chopping":
    NEWStrA <- readNEWS(chop = "keepAll")
    object.size(NEWStr)
    object.size(NEWStrA) ## (no chopping) ==> about double the size

    str(NEWStr, max.level = 3)

    str(NEWStr[[c("2.3", "2.3.1")]], max.level=2, vec.len=1)

    NEWStr [[c("2.3", "2.3.1", "NEW FEATURES")]]
    NEWStrA[[c("2.4", "2.4.0", "NEW FEATURES")]]

    # Check the current NEWS file

    stopifnot(checkNEWS())

[Package tools version 2.15.1 Index]