BUG: NEWS.md are not found by utils::news()

[HenrikBengtsson]

Background

About NEWS.md files in packages:

• They're included in package during build

• They're listed on CRAN (after being converted to HTML)

Issue

However, utils::news() don't report on them, e.g.

> p <- system.file(package = "batchtools")
> news(package = "batchtools")
NULL
> system.file("NEWS.md", package = "batchtools", mustWork = TRUE)
[1] "/home/hb/R/x86_64-pc-linux-gnu-library/3.4/batchtools/NEWS.md"

Suggestion

Without having to worry about parsing NEWS.md and converting its format to HTML etc, it could be displayed as is, that is, just as if it was named NEWS.

Troubleshooting

The problem comes from the fact that tools:::.build_news_db() does not look for NEWS.md:

> f <- tools:::.build_news_db(package = "batchtools")
> f
NULL

It doesn't look hard to do that (UPDATE: It's actually not straightforward; see comment below);

> tools:::.build_news_db
function (package, lib.loc = NULL, format = NULL, reader = NULL) 
{
    dir <- system.file(package = package, lib.loc = lib.loc)
    nfile <- file.path(dir, "NEWS.Rd")
    if (file_test("-f", nfile)) 
        return(.build_news_db_from_package_NEWS_Rd(nfile))
    nfile <- file.path(dir, "NEWS")
    if (!file_test("-f", nfile)) 
        return(invisible())
    if (!is.null(format)) 
        .NotYetUsed("format", FALSE)
    if (!is.null(reader)) 
        .NotYetUsed("reader", FALSE)
    reader <- .news_reader_default
    reader(nfile)
}
<bytecode: 0x36c6e00>

See also

• R-devel thread 'NEWS.md support on CRAN', on May 23-27, 2015, https://stat.ethz.ch/pipermail/r-devel/2015-May/thread.html#71215

[HenrikBengtsson]

Hmm... it's more complicated than I thought, because tools:::.news_reader_default() does quite some parsing, which clashes with the Markdown format causing the output be a single NEWS entry, e.g.

> f <- system.file("NEWS.md", package = "batchtools")
> n <- tools:::.news_reader_default(f)
> str(n)
Classes 'news_db' and 'data.frame':	1 obs. of  4 variables:
 $ Version : chr NA
 $ Date    : chr NA
 $ Category: chr NA
 $ Text    : chr "# batchtools 0.9.2\n\n* Full support for array jobs on Slurm and TORQUE.\n* Array jobs have been disabled for S"| __truncated__

[HenrikBengtsson]

Support for NEWS.md has been added to R-devel (wch/r-source@edad482), e.g.

> f <- tools:::.build_news_db(package = "batchtools")
> str(f)
Classes ‘news_db_from_md’, ‘news_db’ and 'data.frame':	10 obs. of  5 variables:
 $ Version : chr  "0.9.10" "0.9.9" "0.9.8" "0.9.7" ...
 $ Date    : chr  NA NA NA NA ...
 $ Category: chr  "" "" "" "" ...
 $ Text    : chr  "  - Exported functions findConfFile() and findTemplateFile().\n  - Dropped support for providing a template fil"| __truncated__ "  - RDS files are explicitly stored in version 2 to ensure backward\n    compatibility with R versions prior to"| __truncated__ "  - Renamed column \"memory\" in the status table to \"mem.used\" to avoid\n    name clashes with the resource "| __truncated__ "  - Added a workaround for a test to be compatible with testthat v2.0.0.\n  - Better and more customizable hand"| __truncated__ ...
 $ HTML    : chr  "<ul>\n<li>Exported functions <code>findConfFile()</code> and <code>findTemplateFile()</code>.</li>\n<li>Dropped"| __truncated__ "<ul>\n<li>RDS files are explicitly stored in version 2 to ensure backward compatibility with R versions prior t"| __truncated__ "<ul>\n<li>Renamed column &quot;memory&quot; in the status table to &quot;mem.used&quot; to avoid name clashes w"| __truncated__ "<ul>\n<li>Added a workaround for a test to be compatible with testthat v2.0.0.</li>\n<li>Better and more custom"| __truncated__ ...
 - attr(*, "bad")= logi  FALSE FALSE FALSE FALSE FALSE FALSE ...
> head(f, 2)
                       Changes in version 0.9.10                        

  - Exported functions findConfFile() and findTemplateFile().
  - Dropped support for providing a template file directly as string. A
    valid file is now always required.
  - Fixed writing to TMPDIR instead of the R session's temporary
    directory.

                        Changes in version 0.9.9                        

  - RDS files are explicitly stored in version 2 to ensure backward
    compatibility with R versions prior to 3.5.0.
  - Package fs is now used internally for all file system operations.
  - Support for per-site configuration files and templates to be set up
    by system administrators.
  - The print of getStatus() now includes a time stamp.
  - chunk() now optionally shuffles the ids before chunking.
  - Support for setting per-job resources in submitJobs().
  - Example templates now include resources for blas.threads and
    omp.threads.
  - Some bug fixes regarding read-only registries.

[Eluvias]

It doesn't seem that NEWS.md is included in the help documentation. (R v3.6.0)

For example fs package has NEWS.md in its root directory.

news(package = "fs")

But here is missing:

help(package = "fs")

[HenrikBengtsson]

Thanks. Looks like a bug/oversight to me. Could you please report this on the R-devel mailing list?