On 04/06/2015 1:09 PM, Prof Brian Ripley wrote:> On 04/06/2015 17:00, Gavin Simpson wrote: > ... > > 1. Markdown was designed to be as readable as possible in plain text format > > (i.e. the sources, not the rendered file). There's nothing stopping you > > reading and parsing a NEWS.md in your head trivially. > ... > > That claim is made frequently, but it is not my experience. That you > can filter out markup in your head does not mean others can -- it is > very distracting to some visually impaired people (including when using > a text-to-speech reader). >I agree. I think we shouldn't be displaying raw Markdown, except possibly as a temporary measure, while we get the parsing and rendering in place. Duncan Murdoch
On 4 June 2015 at 11:16, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:> On 04/06/2015 1:09 PM, Prof Brian Ripley wrote: > >> On 04/06/2015 17:00, Gavin Simpson wrote: >> ... >> > 1. Markdown was designed to be as readable as possible in plain text >> format >> > (i.e. the sources, not the rendered file). There's nothing stopping you >> > reading and parsing a NEWS.md in your head trivially. >> ... >> >> That claim is made frequently, but it is not my experience. That you >> can filter out markup in your head does not mean others can -- it is >> very distracting to some visually impaired people (including when using >> a text-to-speech reader). >> >> I agree. I think we shouldn't be displaying raw Markdown, except > possibly as a temporary measure, while we get the parsing and rendering in > place.Just to be clear; I wasn't suggesting that R should be displaying raw Markdown. What I was getting at was even if your local setup stops you seeing a rendered version of the file (for whatever reason) reading the Markdown source is a lot easier than reading a similar file marked up using Rd. Yet for those with less restrictive setups Markdown maintains many of the benefits that the Rd markup allows. I just failed miserably, and insensitively(!), to convey that point. G> >Duncan Murdoch>-- Gavin Simpson, PhD [[alternative HTML version deleted]]
@Gavin: My aim was to point out that the ability to mix developer-facing documentation with user-facing documentation is not a good reason to want to support md. I agree with Duncan that links to within a package would be useful (not sure if NEWS.Rd supports this). I'm not so convinced that package authors that do not even add a plain text NEWS file will create a NEWS.md file. Adding NEWS.md means we now have three ways to specify the NEWS: - a plain text NEWS file; following the GNU recommendations - NEWS.Rd - NEWS.md Would it not be more elegant to have e.g. roxygen2 generate NEWS.Rd? (perhaps it is already possible, I'm not sure of that). I don't maintain CRAN, but I know what I would prefer.. Cheers, Mark ? [[alternative HTML version deleted]]