[Rd] NEWS.md support on CRAN

[Yihui Xie]

I agree. It is not worth all the trouble just to save the "bit of
hassle to go to the package's Github site". In fact, the release notes
on Github are more meaningful than a plain text NEWS.md or even a
converted NEWS.html from Pandoc, e.g. you can include bug report
numbers and attribute to users by @username (they all have hyperlinks
attached on them, so it is easy to see more details of bugs/features
if one really cares). Personally, I feel it is very worthwhile going
to Github and reading the release notes there. I'd be unhappy with
converting NEWS.md to NEWS.html by Pandoc. I know not all people use
Github, but I feel if a package author has a NEWS.md, chances are this
package is on Github.

Re Kurt's analysis of NEWS.md on CRAN, I guess that is because R CMD
check will warn against NEWS.md at the top level. I know a lot of
packages on Github have the NEWS.md file, and it has been removed from
the tarball to make R CMD check happy.

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Web: http://yihui.name


On Sat, May 23, 2015 at 8:25 AM, Gábor Csárdi <csardi.gabor at gmail.com> wrote:
> On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch <murdoch.duncan at gmail.com>
> wrote:
> [...]
>
>> I think the harder problem is display.  CRAN can run pandoc, but can
>> users who install the package from source?  I would expect some obscure
>> platforms (like Windows ;-) would not have it available.
>>
> [...]
>
> I don't think pandoc is the best way to go with NEWS.md (and README.md,
> actually). I would be surprised if many package maintainer built their
> NEWS/README files with pandoc. They just look at them at GitHub (or another
> similar service).
>
> GitHub has API for building HTML from MarkDown:
> https://developer.github.com/v3/markdown/
> It can build GitHub-flavored MarkDown, in which case you get links to
> GitHub issues, etc. or just plain MarkDown, like a GitHub README.
>
> If you don't want to rely on their service, then there are a multitude of
> lightweight MarkDown parsers available, e.g.
> https://github.com/markdown-it/markdown-it is a good one IMO.
>
> Pandoc is great for vignettes, but you don't need its full power for
> READMEs and especially not for NEWS files. In fact most NEWS.md files look
> good as text.
>
> Gabor