EVOLUTION-MANAGER
Edit File: news.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Build and Query R or Package News Information</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for news {utils}"><tr><td>news {utils}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Build and Query R or Package News Information</h2> <h3>Description</h3> <p>Build and query the news data base for <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> or add-on packages. </p> <h3>Usage</h3> <pre> 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"), ...) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>query</code></td> <td> <p>an expression for selecting news entries</p> </td></tr> <tr valign="top"><td><code>package</code></td> <td> <p>a character string giving the name of an installed add-on package, or <code>"R"</code>.</p> </td></tr> <tr valign="top"><td><code>lib.loc</code></td> <td> <p>a character vector of directory names of R libraries, or <code>NULL</code>. The default value of <code>NULL</code> corresponds to all libraries currently known.</p> </td></tr> <tr valign="top"><td><code>format</code></td> <td> <p>Not yet used.</p> </td></tr> <tr valign="top"><td><code>reader</code></td> <td> <p>Not yet used.</p> </td></tr> <tr valign="top"><td><code>db, x</code></td> <td> <p>a news db obtained from <code>news()</code>.</p> </td></tr> <tr valign="top"><td><code>doBrowse</code></td> <td> <p>logical specifying that the news should be opened in the browser (by <code><a href="browseURL.html">browseURL</a></code>, accessible as via <code><a href="help.start.html">help.start</a></code>) instead of printed to the console.</p> </td></tr> <tr valign="top"><td><code>browser</code></td> <td> <p>the browser to be used, see <code><a href="browseURL.html">browseURL</a></code>.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>potentially further arguments passed to <code>print()</code>.</p> </td></tr> </table> <h3>Details</h3> <p>If <code>package</code> is <code>"R"</code> (default), a news db is built with the news since the 3.0.0 release of R (corresponding to R's top-level ‘<span class="file">NEWS</span>’ 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 ‘<span class="file">inst/NEWS.Rd</span>’, ‘<span class="file">NEWS.md</span>’ (since <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> version 3.6.0, needs packages <a href="https://CRAN.R-project.org/package=commonmark"><span class="pkg">commonmark</span></a> and <a href="https://CRAN.R-project.org/package=xml2"><span class="pkg">xml2</span></a> to be available), ‘<span class="file">NEWS</span>’ or ‘<span class="file">inst/NEWS</span>’ (in that order). </p> <p>File ‘<span class="file">inst/NEWS.Rd</span>’ should be an Rd file given the entries as Rd <code style="white-space: pre;">\itemize</code> lists, grouped according to version using <code style="white-space: pre;">section</code> 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 <code><a href="../../base/html/strptime.html">strptime</a></code>) format date, and possibly further grouped according to categories using <code style="white-space: pre;">\subsection</code> elements named as the categories. At the very end of <code style="white-space: pre;">\section{..}</code>, the date may also be specified as <code style="white-space: pre;">(%Y-%m-%d, <note>)</code>, i.e., including parentheses. </p> <p>File ‘<span class="file">NEWS.md</span>’ should contain the news in Markdown (following the CommonMark (<a href="https://commonmark.org/">https://commonmark.org/</a>) 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. </p> <p>The plain text ‘<span class="file">NEWS</span>’ 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: </p> <ul> <li><p> 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. </p> </li> <li><p> Entries may be grouped according to category, with a category header (different from a version header) starting at the beginning of a line. </p> </li> <li><p> Entries are written as itemize-type lists, using one of <span class="samp">o</span>, <span class="samp">*</span>, <span class="samp">-</span> or <span class="samp">+</span> as item tag. Entries must be indented, and ideally use a common indentation for the item texts. </p> </li></ul> <p>Additional formats and readers may be supported in the future. </p> <p>Package <span class="pkg">tools</span> provides an (internal) utility function <code>news2Rd</code> to convert plain text ‘<span class="file">NEWS</span>’ files to Rd. For ‘<span class="file">NEWS</span>’ files in a format which can successfully be handled by the default reader, package maintainers can use <code>tools:::news2Rd(dir, "NEWS.Rd")</code>, possibly with additional argument <code>codify = TRUE</code>, with <code>dir</code> a character string specifying the path to a package's root directory. Upon success, the ‘<span class="file">NEWS.Rd</span>’ file can further be improved and then be moved to the ‘<span class="file">inst</span>’ subdirectory of the package source directory. </p> <p>The news db built is a character data frame inheriting from <code>"news_db"</code> with variables <code>Version</code>, <code>Category</code>, <code>Date</code> and <code>Text</code>, where the last contains the entry texts read, and the other variables may be <code>NA</code> if they were missing or could not be determined. </p> <p>Using <code>query</code>, one can select news entries from the db. If missing or <code>NULL</code>, the complete db is returned. Otherwise, <code>query</code> should be an expression involving (a subset of) the variables <code>Version</code>, <code>Category</code>, <code>Date</code> and <code>Text</code>, 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 <code>TRUE</code> are selected. When evaluating, <code>Version</code> and <code>Date</code> are coerced to <code><a href="../../base/html/numeric_version.html">numeric_version</a></code> and <code><a href="../../base/html/Dates.html">Date</a></code> objects, respectively, so that the comparison operators for these classes can be employed. </p> <h3>Value</h3> <p>A data frame inheriting from class <code>"news_db"</code>, with <code><a href="../../base/html/attributes.html">attributes</a></code> <code>"package"</code> (and <code>"subset"</code> if the <code>query</code> lead to proper subsetting). </p> <h3>Examples</h3> <pre> ## 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) </pre> <hr /><div style="text-align: center;">[Package <em>utils</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>