R news 构建和查询 R 或包新闻信息

说明

建立并查询新闻数据库R或add-on 包。

用法

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"), ...)

参数

query	用于选择新闻条目的可选表达式。
package	给出已安装的 add-on 软件包名称的字符串，或 "R" 或 "R-3" 或 "R-2" 。
lib.loc	R 库的目录名称的字符向量，或 NULL 。 NULL 的默认值对应于当前已知的所有库。
format	尚未使用。
reader	尚未使用。
db , x	从 news() 获得的新闻数据库。
doBrowse	逻辑上指定新闻应在浏览器中打开(通过 browseURL ，可通过 help.start 访问)而不是打印到控制台。
browser	要使用的浏览器，请参阅browseURL。
...	可能会传递给 print() 的更多参数。

细节

如果package是"R"(默认)，自 4.0.0 版本以来，使用新闻构建新闻数据库R，对应于‘NEWS' 文件中R.home("doc")目录。"R-3"或者"R-2"提供新闻R3.x.y 或R分别为 2.x.y。否则，如果可以在给定的库中找到给定的 add-on 包，则尝试从文件‘中以结构化形式读取其新闻研究所/NEWS.Rd', 'NEWS.md' (自从R版本3.6.0，需要包commonmark和xml2可用)，‘NEWS' 或者 '研究所/新闻' (以该顺序)。有关文件规格，请参阅“新闻格式”部分。

使用 query ，可以从数据库中选择新闻条目。如果丢失或 NULL ，则返回完整的数据库。否则， query 应该是涉及变量 Version 、 Category 、 Date 和 Text (的子集)的表达式，并且在数据库内求值时返回一个逻辑向量，其长度为中的条目数数据库。选择评价为TRUE的条目。求值时，Version 和 Date 分别被强制为 numeric_version 和 Date 对象，以便可以使用这些类的比较运算符。

值

继承自类 "news_db" 的 DataFrame ，带有字符变量 Version 、 Category 、 Date 、 Text 和 HTML ，其中最后两个各自包含读取的条目文本(在 plain-text 和 HTML 中)格式)，如果其他变量丢失或无法确定，则可能是NA。数据帧具有attributes "package"(如果query导致正确的子集化，则还有"subset")。

新闻格式

'研究所/NEWS.Rd’

文件 '研究所/NEWS.Rd' 应该是一个 Rd 文件，条目为 Rd⁠\itemize⁠列表，根据版本分组⁠\section⁠元素。节标题以合适的前缀开头，后跟空格和版本号，并且可以选择以(带括号的)ISO 8601 (%Y-%m-%d，请参阅strptime) 格式化日期(可选地包括注释)，例如：

    \section{Changes in version 2.0 (2020-02-02, <note>)}{
      \itemize{
        \item ....
      }
    }
  

条目可以根据类别进一步分组，使用⁠\subsection⁠命名为类别的元素。这 'NEWS.Rd' 文件被假定为 UTF-8 编码(但包含⁠\encoding⁠规范优先)。

'NEWS.md’

文件 'NEWS.md’ 应包含 Markdown 格式的新闻(在 CommonMark 之后(https://commonmark.org/) 规范)，主标题级别在前缀后给出版本号，后跟一个空格，并且可以选择后跟一个空格和带括号的 ISO 8601 格式日期。如果有的话，会采用二级标题来指示类别。为了适应常见做法，新闻条目仅分为类别级别。

'NEWS’

纯文本‘NEWSadd-on 包中的文件使用多种不同的格式；默认新闻阅读器应该能够从标准存储库的大多数包中提取单个新闻条目，标准存储库使用以下格式(略有变化)：

• 条目根据版本进行分组，版本标题 “Changes in version” 位于行的开头，后跟版本号，可选地后跟 ISO 8601 格式日期(可能带有括号)。

• 条目可以根据类别进行分组，类别标题(与版本标题不同)从行的开头开始。

• 条目被写入itemize-type列表，使用‘⁠o⁠', '⁠*⁠', '⁠-⁠' 或者 '⁠+⁠’作为项目标签。条目必须缩进，并且最好对项目文本使用通用缩进。

包tools提供(内部)效用函数news2Rd转换纯文本‘NEWS’文件发送至路。为了 'NEWS' 文件的格式可以被默认阅读器成功处理，包维护者可以使用tools:::news2Rd(dir, "NEWS.Rd")，可能还有额外的参数codify = TRUE， 和dir指定包根目录路径的字符串。成功后，‘NEWS.Rd’ 文件可以进一步改进，然后移动到‘安装' 包源目录的子目录。

将来可能会支持其他格式和阅读器。

例子

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

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

## print db4 to show in an HTML browser.

## 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 >= 4.0.0
table(news(Version >= "4.0.0", db = db)$Version)


## do the same for R 3.x.y, more slowly
db3 <- news(package = "R-3")
sort(table(db3[, "Category"]), decreasing = TRUE)
## Entries with version >= 3.6.0
table(news(Version >= "3.6.0", db = db3)$Version)