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)