[Rd] NEWS.md support on CRAN

[Duncan Murdoch]

On 23/05/2015 9:25 AM, Gábor Csárdi wrote:
> On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch
> <murdoch.duncan at gmail.com <mailto: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.

I wouldn't want R builds to depend on GitHub, so this sounds more
interesting.  I took a look at that website, and it looks problematic to
me:  the parser appears to be written in Javascript, and the install
instructions (using "npm" and "bower", whatever those are) depend on
some unstated prerequisites.  In principle there's no reason not to
allow R builds to depend on these things, but adding a dependency like
that implies so much testing that I can't imagine anyone who could do it
would want to.

It's likely that a suitable parser could be written in some combination
of C and R -- Markdown is not a complicated language.

> 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.

But we do need something, and it needs to be essentially universally
available, or small enough to include in the R sources.  I think R
should eventually support Markdown as an acceptable language for
documentation (including NEWS.md, and also help files for functions),
but I think the effort required to do it now is too much.

Duncan Murdoch

> 
> Gabor
>