NEWS.md support on CRAN

classic Classic list List threaded Threaded
50 messages Options
123
Reply | Threaded
Open this post in threaded view
|

NEWS.md support on CRAN

Imanuel Costigan
Are there any plans for CRAN to support NEWS files in markdown? Bit of a hassle to go the the package’s Github (or other like) site to read NEWS.
______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Duncan Murdoch-2
On 22/05/2015 8:49 PM, Imanuel Costigan wrote:
> Are there any plans for CRAN to support NEWS files in markdown? Bit of a hassle to go the the package’s Github (or other like) site to read NEWS.

Not as far as I know.  There have been discussions about increasing the
support of Markdown, but so far the conclusion has been that it's too
hard to do -- the support is not stable enough on all the platforms
where R runs.

Markdown is allowed for vignettes (because the package author processes
those), so I'd suggest putting your news into a vignette instead of a
news file.  Put in a token news file that points to the vignette so
users can find it.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Imanuel Costigan
What about treating it as a plain text file (i.e. no need for CRAN to support parsing)?

> On 23 May 2015, at 11:08 am, Duncan Murdoch <[hidden email]> wrote:
>
> On 22/05/2015 8:49 PM, Imanuel Costigan wrote:
>> Are there any plans for CRAN to support NEWS files in markdown? Bit of a hassle to go the the package’s Github (or other like) site to read NEWS.
>
> Not as far as I know.  There have been discussions about increasing the
> support of Markdown, but so far the conclusion has been that it's too
> hard to do -- the support is not stable enough on all the platforms
> where R runs.
>
> Markdown is allowed for vignettes (because the package author processes
> those), so I'd suggest putting your news into a vignette instead of a
> news file.  Put in a token news file that points to the vignette so
> users can find it.
>
> Duncan Murdoch
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Yihui Xie-2
In reply to this post by Duncan Murdoch-2
What I do is to use inst/NEWS.Rd as a placeholder that points to the
NEWS.md on Github, e.g.
http://cran.rstudio.com/web/packages/knitr/index.html

Regards,
Yihui
--
Yihui Xie <[hidden email]>
Web: http://yihui.name


On Fri, May 22, 2015 at 8:08 PM, Duncan Murdoch
<[hidden email]> wrote:

> On 22/05/2015 8:49 PM, Imanuel Costigan wrote:
>> Are there any plans for CRAN to support NEWS files in markdown? Bit of a hassle to go the the package’s Github (or other like) site to read NEWS.
>
> Not as far as I know.  There have been discussions about increasing the
> support of Markdown, but so far the conclusion has been that it's too
> hard to do -- the support is not stable enough on all the platforms
> where R runs.
>
> Markdown is allowed for vignettes (because the package author processes
> those), so I'd suggest putting your news into a vignette instead of a
> news file.  Put in a token news file that points to the vignette so
> users can find it.
>
> Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Kurt Hornik-5
In reply to this post by Duncan Murdoch-2
>>>>> Duncan Murdoch writes:

> On 22/05/2015 8:49 PM, Imanuel Costigan wrote:
>> Are there any plans for CRAN to support NEWS files in markdown? Bit of a hassle to go the the package’s Github (or other like) site to read NEWS.

> Not as far as I know.  There have been discussions about increasing the
> support of Markdown, but so far the conclusion has been that it's too
> hard to do -- the support is not stable enough on all the platforms
> where R runs.

There are actually two issues here.

For CRAN, we could in principle take inst/NEWS.md files, convert these
to HTML using pandoc, and use the HTML for the package web page.  (Would
need the CRAN incoming checks to be taught about inst/NEWS.md.)

However, we cannot use such files for utils::news() because we do not
(yet?) know how to reliably parse such files and extract the news items
(and hence cannot really compute on the news information).

Btw, currently only one package on CRAN has inst/NEWS.md (another one
has NEWS.md at top level).

Best
-k

> Markdown is allowed for vignettes (because the package author processes
> those), so I'd suggest putting your news into a vignette instead of a
> news file.  Put in a token news file that points to the vignette so
> users can find it.

> Duncan Murdoch

> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Duncan Murdoch-2
On 23/05/2015 4:05 AM, Kurt Hornik wrote:

>>>>>> Duncan Murdoch writes:
>
>> On 22/05/2015 8:49 PM, Imanuel Costigan wrote:
>>> Are there any plans for CRAN to support NEWS files in markdown? Bit of a hassle to go the the package’s Github (or other like) site to read NEWS.
>
>> Not as far as I know.  There have been discussions about increasing the
>> support of Markdown, but so far the conclusion has been that it's too
>> hard to do -- the support is not stable enough on all the platforms
>> where R runs.
>
> There are actually two issues here.
>
> For CRAN, we could in principle take inst/NEWS.md files, convert these
> to HTML using pandoc, and use the HTML for the package web page.  (Would
> need the CRAN incoming checks to be taught about inst/NEWS.md.)
>
> However, we cannot use such files for utils::news() because we do not
> (yet?) know how to reliably parse such files and extract the news items
> (and hence cannot really compute on the news information).

It would be quite easy to modify the news() parser to parse a suitably
described Markdown format.  The main change from the current text parser
would be to expect a prefix on the line introducing each version or
category.

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 could add it
to Rtools on Windows, but I think platforms that normally install tools
from source will have more trouble, because it has an unusual
prerequisite (Haskell).  We could fall back to displaying the NEWS.md
file without processing, but that makes lots of code more complicated.

>
> Btw, currently only one package on CRAN has inst/NEWS.md (another one
> has NEWS.md at top level).

I'd guess if someone solved the problems mentioned above, it would
become more popular.  Many people would convert their text NEWS to
NEWS.md if it would display better; that's a lot easier than converting
to NEWS.Rd.

Duncan Murdoch



>
> Best
> -k
>
>> Markdown is allowed for vignettes (because the package author processes
>> those), so I'd suggest putting your news into a vignette instead of a
>> news file.  Put in a token news file that points to the vignette so
>> users can find it.
>
>> Duncan Murdoch
>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Dirk Eddelbuettel

On 23 May 2015 at 08:14, Duncan Murdoch 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 could add it
| to Rtools on Windows, but I think platforms that normally install tools
| from source will have more trouble, because it has an unusual
| prerequisite (Haskell).  We could fall back to displaying the NEWS.md
| file without processing, but that makes lots of code more complicated.

If you had spare time, you could coordinate with JJ.  He somehow managed to
get pandoc to build as a standalone binary without any runtime requirements
so that it could be included with RStudio.  And so it has been for quite some
time.  Every machine with an RStudio installation has pandoc.

Maybe we could consider carrying this over from RStudio into Rtools?
Similarly, on OS X and Linux maybe we could add a layer that would R allow to
query an RStudio instance, if present, to tell it where its pandoc is, if no
suitable pandoc binary is in the path.  Just thinking out loud...

Dirk

--
http://dirk.eddelbuettel.com | @eddelbuettel | [hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Brian Ripley
In reply to this post by Duncan Murdoch-2
On 23/05/2015 13:14, Duncan Murdoch wrote:

> On 23/05/2015 4:05 AM, Kurt Hornik wrote:
>>>>>>> Duncan Murdoch writes:
>>
>>> On 22/05/2015 8:49 PM, Imanuel Costigan wrote:
>>>> Are there any plans for CRAN to support NEWS files in markdown? Bit of a hassle to go the the package’s Github (or other like) site to read NEWS.
>>
>>> Not as far as I know.  There have been discussions about increasing the
>>> support of Markdown, but so far the conclusion has been that it's too
>>> hard to do -- the support is not stable enough on all the platforms
>>> where R runs.
>>
>> There are actually two issues here.
>>
>> For CRAN, we could in principle take inst/NEWS.md files, convert these
>> to HTML using pandoc, and use the HTML for the package web page.  (Would
>> need the CRAN incoming checks to be taught about inst/NEWS.md.)
>>
>> However, we cannot use such files for utils::news() because we do not
>> (yet?) know how to reliably parse such files and extract the news items
>> (and hence cannot really compute on the news information).
>
> It would be quite easy to modify the news() parser to parse a suitably
> described Markdown format.  The main change from the current text parser
> would be to expect a prefix on the line introducing each version or
> category.
>
> 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 could add it
> to Rtools on Windows, but I think platforms that normally install tools
> from source will have more trouble, because it has an unusual
> prerequisite (Haskell).  We could fall back to displaying the NEWS.md
> file without processing, but that makes lots of code more complicated.

pandoc is only viable on platforms with a pre-compiled binary, which
does not even cover all the CRAN check platforms.  (It is not easy to
compile ab initio from source even on a mainstream Linux, but they
mostly have pandoc binaries.)

The next problem is that using pandoc as the de facto standard for .md
depends on the version of pandoc, and .md seems to have no way to
specify the version required.  (If it does, people are failing to use it
....)


--
Brian D. Ripley,                  [hidden email]
Emeritus Professor of Applied Statistics, University of Oxford
1 South Parks Road, Oxford OX1 3TG, UK

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Gábor Csárdi
In reply to this post by Duncan Murdoch-2
On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch <[hidden email]>
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]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Yihui Xie-2
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 <[hidden email]>
Web: http://yihui.name


On Sat, May 23, 2015 at 8:25 AM, Gábor Csárdi <[hidden email]> wrote:

> On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch <[hidden email]>
> 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

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Gábor Csárdi
On Sat, May 23, 2015 at 11:31 AM, Yihui Xie <[hidden email]> 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]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Duncan Murdoch-2
In reply to this post by Yihui Xie-2
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 <[hidden email]>
> Web: http://yihui.name
>
>
> On Sat, May 23, 2015 at 8:25 AM, Gábor Csárdi <[hidden email]> wrote:
>> On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch <[hidden email]>
>> 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

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Duncan Murdoch-2
In reply to this post by Gábor Csárdi
On 23/05/2015 9:25 AM, Gábor Csárdi wrote:

> On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch
> <[hidden email] <mailto:[hidden email]>> 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
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Gábor Csárdi
On Sat, May 23, 2015 at 8:00 PM, Duncan Murdoch <[hidden email]>
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]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

baptiste.auguie
In reply to this post by Duncan Murdoch-2
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 <[hidden email]> wrote:

> On 23/05/2015 9:25 AM, Gábor Csárdi wrote:
> > On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch
> > <[hidden email] <mailto:[hidden email]>> 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
> >
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Imanuel Costigan
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 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?


> On 24 May 2015, at 10:51 am, Baptiste Auguie <[hidden email]> 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 <[hidden email]> wrote:
> On 23/05/2015 9:25 AM, Gábor Csárdi wrote:
> > On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch
> > <[hidden email] <mailto:[hidden email]>> 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
> >
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Duncan Murdoch-2
In reply to this post by baptiste.auguie
On 23/05/2015 8:51 PM, Baptiste Auguie 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

It sounds as though there are at least two possibilities for parsers
that could be included in R:  Sundown and commonmark.  The "markdown"
package does some of what R would need to make use of Sundown, but not
all:  we really do need an R object representation of the parse tree,
for functions like news() to work with in the short term, and the help
system in the longer term.  To allow NEWS.md to be used, we'd also need
someone to work out the conventions for what's allowed (probably very
similar to the conventions for NEWS or NEWS.Rd), and write code to work
with those files.

Does anyone want to work on this?

Duncan Murdoch


>
> 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 <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     On 23/05/2015 9:25 AM, Gábor Csárdi wrote:
>     > On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch
>     > <[hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>>
>     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
>     >
>
>     ______________________________________________
>     [hidden email] <mailto:[hidden email]> mailing list
>     https://stat.ethz.ch/mailman/listinfo/r-devel
>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Duncan Murdoch-2
In reply to this post by Imanuel Costigan
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.


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?

Duncan Murdoch


>
>
>> On 24 May 2015, at 10:51 am, Baptiste Auguie <[hidden email]> 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 <[hidden email]> wrote:
>> On 23/05/2015 9:25 AM, Gábor Csárdi wrote:
>>> On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch
>>> <[hidden email] <mailto:[hidden email]>> 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
>>>
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Imanuel Costigan
In reply to this post by Duncan Murdoch-2
I’d suggest going with CommonMark if this will be the basis of broader support for Markdown as it is well defined whereas GruberMarkdown is defined by broad conventions with specifics determined by parsers.

> On 24 May 2015, at 12:01 pm, Duncan Murdoch <[hidden email]> wrote:
>
> On 23/05/2015 8:51 PM, Baptiste Auguie 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
>
> It sounds as though there are at least two possibilities for parsers
> that could be included in R:  Sundown and commonmark.  The "markdown"
> package does some of what R would need to make use of Sundown, but not
> all:  we really do need an R object representation of the parse tree,
> for functions like news() to work with in the short term, and the help
> system in the longer term.  To allow NEWS.md to be used, we'd also need
> someone to work out the conventions for what's allowed (probably very
> similar to the conventions for NEWS or NEWS.Rd), and write code to work
> with those files.
>
> Does anyone want to work on this?
>
> Duncan Murdoch
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: NEWS.md support on CRAN

Imanuel Costigan
In reply to this post by Duncan Murdoch-2

> On 24 May 2015, at 12:07 pm, Duncan Murdoch <[hidden email]> 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”.

>
> Duncan Murdoch
>
>
>>
>>
>>> On 24 May 2015, at 10:51 am, Baptiste Auguie <[hidden email]> 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 <[hidden email]> wrote:
>>> On 23/05/2015 9:25 AM, Gábor Csárdi wrote:
>>>> On Sat, May 23, 2015 at 8:14 AM, Duncan Murdoch
>>>> <[hidden email] <mailto:[hidden email]>> 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
>>>>
>>>
>>> ______________________________________________
>>> [hidden email] mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
123