[Rd] R-devel Digest, Vol 148, Issue 5

[Thomas J. Leeper]

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.

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