[Rd] NEWS.md support on CRAN

[Duncan Murdoch]

On 23/05/2015 10:26 PM, Imanuel Costigan wrote:
> 
>> On 24 May 2015, at 12:07 pm, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
>>
>> On 23/05/2015 9:15 PM, Imanuel Costigan wrote:
>>> While a parsed HTML version of the NEWS.md file would be nice, I would like something much simpler: being able to "see” this file in the Help pane in RStudio 
>>
>> That isn't really any simpler.  RStudio is just displaying HTML whenever
>> it shows you anything in the Help pane.
> 
> Ok yes, point taken. My post was more in relation to a short-term “fix” of being able to save the NEWS.md file in the package’s top level directory. Users could still be able to read it as a plain text file in their R session (esp. if they don’t have web access) AND be able to see the pretty marked up version on Github if they wished. At the moment, it isn’t possible to make this work without triggering CRAN errors (by storing it in the top-level) or losing the NEWS.md file from top level directory of the package (by saving to inst/) and making it less conventional / accessible on Github. Ideally, one should be able to get the best of both: save this in top-level directory and when necessary, just present it as a text file (at least until such time as Markdown is officially supported). 
> 
>>
>>
>> or being about to run something like show_news(“packagename”). Duncan
>> mentioned issues with the news() function being able to process metadata
>> represented in the Md file. What is the motivation of this structure?
>>
>> I don't understand your question.  What issues did I mention?  Or are
>> you talking about Kurt's post, who first mentioned news()?  And what
>> structure are you talking about?
> 
> Yes I was referring to Kurt’s comments. As I understand it, the short-term “fix” I outlined above wouldn’t work because news() expects a certain structure and can’t extract the elements that it expects from  Markdown files yet. What I am asking is why it isn’t possible / desirable for news() to simply print to the console the contents of `system.file(“NEWS.md”, package = “packagename”)`? For example, `news(package = “devtools”)` returns nothing because it uses “NEWS.md”. 

Short term fixes are generally a bad way to design software.  We should
do this right if we do it at all.  It might require people using Github
to change the way they do things, if that turns out to make more sense
than accommodating them.

Duncan Murdoch

>>
>> Duncan Murdoch
>>
>>
>>>
>>>
>>>> On 24 May 2015, at 10:51 am, Baptiste Auguie <baptiste.auguie at gmail.com> wrote:
>>>>
>>>> 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
>>>>
>>>
>>
>