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 [[alternative HTML version deleted]]
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
On Sat, May 23, 2015 at 11:31 AM, Yihui Xie <xie at yihui.name> wrote:> 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).Indeed. Although the GitHub API I linked can build a HTML that includes these links, and that's already pretty good. [...]> 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. >I agree. The only package with inst/NEWS.md on CRAN is in fact mine (crayon), and I put NEWS.md (and README.md) in inst/ so that 1) R CMD check and CRAN are both happy (CRAN was unhappy about non-valid HTML build by Pandoc from README.md), and 2) they are included in the package. Gabor [[alternative HTML version deleted]]
On 23/05/2015 11:31 AM, Yihui Xie wrote:> I agree. It is not worth all the trouble just to save the "bit of > hassle to go to the package's Github site".I'm sorry, but in my opinion this is not negotiable. R needs to run on systems without Internet connections. It's not just a "bit of hassle". R is used in places where not everyone has good Internet all the time. 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.Yes, NEWS.md would allow richer content than NEWS does. That's true if it is hosted on Github or not. (So does NEWS.Rd, but it is so inconvenient to write, that I think a local copy of NEWS.md would be a better solution.) Duncan Murdoch> 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
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 >
On Sat, May 23, 2015 at 8:00 PM, Duncan Murdoch <murdoch.duncan at gmail.com> wrote: [...]> 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. >markdown-it is already in an R package, so all you need is devtools::install_github("jeroenooms/markdownit") to try it. Actually an even better alternative is 'sundown' ( https://github.com/vmg/sundown), which already has R bindings, in the 'markdown' package. I should have suggested this in the first place, sorry for missing it. [...] Gabor [[alternative HTML version deleted]]
John MacFarlane, the author of Pandoc, has been working on a project ( http://commonmark.org/) to define a standard reference for Markdown*. There are already two reference implementations, one in javascript, the other in C: https://github.com/jgm/cmark Regards, baptiste * There was some initial controversy with the original author of markdown, but in the long term it's probably one of the more reliable sources to follow. On 24 May 2015 at 12:00, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:> 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 > > > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel >[[alternative HTML version deleted]]