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.dun...@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-requ...@r-project.org> wrote: >> > Date: Thu, 04 Jun 2015 12:39:34 -0400 >> > From: Duncan Murdoch <murdoch.dun...@gmail.com> >> > To: Mark van der Loo <mark.vander...@gmail.com>, kurt.hor...@wu.ac.at >> > Cc: R Devel Mailing List <r-devel@r-project.org>, Dirk >> > Eddelbuettel >> > <e...@debian.org>, Imanuel Costigan <i.costi...@me.com> >> > Subject: Re: [Rd] NEWS.md support on CRAN >> > Message-ID: <55707f46.5010...@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.hor...@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.costi...@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.hor...@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@r-project.org mailing list >> >> > >> | >>>> https://stat.ethz.ch/mailman/listinfo/r-devel >> >> > >> | >> >> >> > >> | >> [[alternative HTML version deleted]] >> >> > >> | >> >> >> > >> | >> ______________________________________________ >> >> > >> | >> R-devel@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....@cbs.dk Priv: pda...@gmail.com >> >> > >> | >> >> > >> | > ______________________________________________ >> >> > >> | > R-devel@r-project.org mailing list >> >> > >> | > https://stat.ethz.ch/mailman/listinfo/r-devel >> >> > >> | >> >> > >> | ______________________________________________ >> >> > >> | R-devel@r-project.org mailing list >> >> > >> | https://stat.ethz.ch/mailman/listinfo/r-devel >> >> > >> >> >> > >> >> > > ______________________________________________ >> >> > > R-devel@r-project.org mailing list >> >> > > https://stat.ethz.ch/mailman/listinfo/r-devel >> >> > >> >> > ______________________________________________ >> >> > R-devel@r-project.org mailing list >> >> > https://stat.ethz.ch/mailman/listinfo/r-devel >> >> > >> >> >> >> ______________________________________________ >> R-devel@r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-devel > > ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel