[Rd] NEWS.md support on CRAN

Fri Jun 5 19:25:23 CEST 2015

Sorry, "require" was the wrong word - "suggest" is better. I actually
didn't realize when I first wrote a package that I should create a
NEWS file because I was following the `package.skeleton()` route and
that wasn't something that was generated automatically. I suspect
other new package authors might be in the same place (i.e., just not
aware that such a file is helpful for end users).

Thomas J. Leeper
http://www.thomasleeper.com

On Fri, Jun 5, 2015 at 6:32 PM, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
> On 05/06/2015 8:16 AM, Thomas J. Leeper wrote:
>>
>> It's disappointing that many packages do not have a NEWS file. Perhaps
>> CRAN should require NEWS or CHANGELOG, as long as the system is being
>> reformed to potentially accommodate markdown anyway.
>
>
> I think we should all be careful about suggesting work for other people.
> This would be a huge amount of work, probably hundreds of hours in
> aggregate, for all those package authors and the CRAN maintainers.
>
> On the other hand, we can gently nudge package authors to better practices.
> When we talk in public about R packages, we should point out that we use a
> certain list of characteristics to judge their quality.  My list includes:
>
>  - Is it on CRAN?
>  - Does it have an overview vignette?
>  - Is it updated fairly regularly?
>  - Do most of the help pages include examples?
>  - Will it install on my OS without much trouble?
>
> Your list could include
>
>  - Does it have a readable NEWS file?
>
> I do use packages which have negative answers to some of those questions,
> but they definitely influence my choice when I'm looking at a package for
> the first time.
>
> Duncan Murdoch
>
>>
>> -Thomas
>>
>> Thomas J. Leeper
>> http://www.thomasleeper.com
>>
>>
>> On Fri, Jun 5, 2015 at 12:00 PM,  <r-devel-request at r-project.org> wrote:
>> > Date: Thu, 04 Jun 2015 12:39:34 -0400
>> > From: Duncan Murdoch <murdoch.duncan at gmail.com>
>> > To: Mark van der Loo <mark.vanderloo at gmail.com>, Kurt.Hornik at wu.ac.at
>> > Cc: R Devel Mailing List <r-devel at r-project.org>,       Dirk
>> > Eddelbuettel
>> >         <edd at debian.org>, Imanuel Costigan <i.costigan at me.com>
>> > Subject: Re: [Rd] NEWS.md support on CRAN
>> > Message-ID: <55707F46.5010108 at gmail.com>
>> > Content-Type: text/plain; charset=utf-8; format=flowed
>> >
>> > On 04/06/2015 11:05 AM, Mark van der Loo wrote:
>> >> FWIW (and a bit late in the discussion, I know), I for one do not care
>> >> about having NEWS in md format at all.
>> >>
>> >> The solution the Yihui uses (linking to GH from NEWS.Rd) is really
>> >> annoying
>> >> for people with no direct Internet access. For example, I work at an
>> >> institute that handles a lot of private data and most VM's with R on it
>> >> have no direct internet access for that reason (of course internet is
>> >> accessible but through an application running on a separate VM).
>> >>
>> >> Moreover, I as a user also do not care at all about links to GH #issues
>> >> and
>> >> which @user did what for each issue. These are details that are useful
>> >> for
>> >> people developing the package or for people who reported a bug. As a
>> >> user I
>> >> just want to read a short description like "bugfix: function f crashed
>> >> on
>> >> input y", or "function g is deprecated" without having to first
>> >> navigate to
>> >> another website.
>> >>
>> >> The most important thing about the NEWS is that it is easy to find (so
>> >> in a
>> >> fixed place), and aimed at users, not developers. It should come with
>> >> the
>> >> software, so it is also available when GH is offline or replaced with
>> >> something new (since hey, didn't we all have a sourceforge or google
>> >> code
>> >> account in our younger days?).
>> >>
>> >> In short, I think that added value of NEWS.md is fairly limited but it
>> >> does
>> >> increase the risk of dispersing the NEWS all over the web.
>> >
>> > I'd disagree a little bit:  NEWS should be both for users and
>> > developers.  The advantage I see to NEWS.md support is that it will
>> > encourage people who are more comfortable writing in Markdown to include
>> > the news in the package, rather than having a link to external news (as
>> > Yihui did), or no news at all (as many packages do).
>> >
>> > It's pretty easy to have plain text news, but links in the news are
>> > helpful.  Links to bug reports are of most use to developers, but other
>> > links are useful to users.  For example, though I don't think anyone is
>> > making use of this, it should be possible to have links from NEWS.Rd (or
>> > NEWS.md when it is fully supported) directly into R's help system.  That
>> > would be especially useful for users.  It would probably even work on
>> > isolated systems, as long as they don't block access to the local http
>> > server.
>> >
>> > Duncan Murdoch
>> >>
>> >> Best,
>> >> Mark
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> Op wo 3 jun. 2015 om 08:32 schreef Kurt Hornik <Kurt.Hornik at wu.ac.at>:
>> >>
>> >> > >>>>> Duncan Murdoch writes:
>> >> >
>> >> > > On 02/06/2015 11:05 AM, Dirk Eddelbuettel wrote:
>> >> > >> Hi Kurt,
>> >> > >>
>> >> > >> On 1 June 2015 at 14:02, Kurt Hornik wrote:
>> >> > >> | >>>>> peter dalgaard writes:
>> >> > >> |
>> >> > >> | >> On 30 May 2015, at 01:20 , Imanuel Costigan
>> >> > >> <i.costigan at me.com>
>> >> > wrote:
>> >> > >> | >>
>> >> > >> | >> So I assume this commit means NEWS.md is now no longer on
>> >> > blacklist?
>> >> > >> | >>
>> >> > >> |
>> >> > >> | > ....in the development version. Not true of released versions.
>> >> > >> |
>> >> > >> | Now also in r-patched.
>> >> > >>
>> >> > >> Nice.
>> >> > >>
>> >> > >> Now, is there a way for package authors to preview how a .md would
>> >> > >> be
>> >> > >> rendered?  I wrote mine with GitHub in mind, and they render fine.
>> >> > >> I
>> >> > looked a
>> >> > >> recently-uploaded README.md of mine on CRAN, and it got some of
>> >> > >> the
>> >> > pandoc-y
>> >> > >> parts wrong --- and looks unprofessional.
>> >> > >>
>> >> > >> I would like to avoid that.  How can I?
>> >> >
>> >> > > In the short term, you should probably try to run pandoc with the
>> >> > > same
>> >> > > version and options as CRAN.  Kurt, can you say what these are?  If
>> >> > > you
>> >> > > (Dirk) know pandoc options that emulate Github, it would probably
>> >> > > make
>> >> > > sense for CRAN to use those.
>> >> >
>> >> > Sure.  We currently have
>> >> >
>> >> > pandoc 1.12.4.2
>> >> > Compiled with texmath 0.6.6.1, highlighting-kate 0.5.8.5.
>> >> >
>> >> > which we use with --email-obfuscation=references.
>> >> >
>> >> > Best
>> >> > -k
>> >> >
>> >> > > In the longer term, the plan is to include our own parser and
>> >> > > renderer.
>> >> > > At that point this would be easy.
>> >> >
>> >> > > Duncan Murdoch
>> >> > >>
>> >> > >> Dirk
>> >> > >>
>> >> > >>
>> >> > >> | -k
>> >> > >> |
>> >> > >> | > -pd
>> >> > >> |
>> >> > >> |
>> >> > >> | >>
>> >> >
>> >> > https://github.com/wch/r-source/commit/9ffe87264a1cd59a31a829f72d57af0f1bfa327a
>> >> > >> | >>
>> >> > >> | >> Sent from my iPad
>> >> > >> | >>
>> >> > >> | >> On 23 May 2015, at 6:05 pm, Kurt Hornik
>> >> > >> <Kurt.Hornik at wu.ac.at>
>> >> > 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).
>> >> > >> | >>>
>> >> > >> | >>> 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
>> >> > >> | >>>
>> >> > >> | >>>> ______________________________________________
>> >> > >> | >>>> R-devel at r-project.org mailing list
>> >> > >> | >>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>> >> > >> | >>
>> >> > >> | >> [[alternative HTML version deleted]]
>> >> > >> | >>
>> >> > >> | >> ______________________________________________
>> >> > >> | >> R-devel at r-project.org mailing list
>> >> > >> | >> https://stat.ethz.ch/mailman/listinfo/r-devel
>> >> > >> |
>> >> > >> | > --
>> >> > >> | > Peter Dalgaard, Professor,
>> >> > >> | > Center for Statistics, Copenhagen Business School
>> >> > >> | > Solbjerg Plads 3, 2000 Frederiksberg, Denmark
>> >> > >> | > Phone: (+45)38153501
>> >> > >> | > Email: pd.mes at cbs.dk  Priv: PDalgd at gmail.com
>> >> > >> |
>> >> > >> | > ______________________________________________
>> >> > >> | > R-devel at r-project.org mailing list
>> >> > >> | > https://stat.ethz.ch/mailman/listinfo/r-devel
>> >> > >> |
>> >> > >> | ______________________________________________
>> >> > >> | R-devel at r-project.org mailing list
>> >> > >> | https://stat.ethz.ch/mailman/listinfo/r-devel
>> >> > >>
>> >> >
>> >> > > ______________________________________________
>> >> > > R-devel at r-project.org mailing list
>> >> > > https://stat.ethz.ch/mailman/listinfo/r-devel
>> >> >
>> >> > ______________________________________________
>> >> > R-devel at r-project.org mailing list
>> >> > https://stat.ethz.ch/mailman/listinfo/r-devel
>> >> >
>> >>
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>