From xie at yihui.name  Sat May 23 17:31:32 2015
From: xie at yihui.name (Yihui Xie)
Date: Sat, 23 May 2015 10:31:32 -0500
Subject: [Rd] NEWS.md support on CRAN
In-Reply-To: <CABtg=KkjFu7Jn8xJqQjyn5bRD8nJG_aJ-QS6ET4BY+ic_d3SBw@mail.gmail.com>
References: <4819669E-8260-47B0-96BF-DC2B29E6BE21@me.com>
	<555FD2FE.8050600@gmail.com>
	<21856.13500.513608.759602@fangorn.hornik.net>
	<55606F19.3080106@gmail.com>
	<CABtg=KkjFu7Jn8xJqQjyn5bRD8nJG_aJ-QS6ET4BY+ic_d3SBw@mail.gmail.com>
Message-ID: <CANROs4c9-w_gdsoP-7VVfD3Zm94V+P1Ej-Qtiaqu6JgDCoC5nw@mail.gmail.com>

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



[Rd] NEWS.md support on CRAN
Yihui Xie