From h.wickham at gmail.com  Thu Feb  1 17:12:58 2018
From: h.wickham at gmail.com (Hadley Wickham)
Date: Thu, 1 Feb 2018 08:12:58 -0800
Subject: [Rd] Best practices in developing package: From a single file
In-Reply-To: <aacda07a-836c-313d-5cc9-c32a5d178f7f@gmail.com>
References: <CAPtbhHwLXvdCX+1PJvEAyjWtcaVf=k4kL2fgXNhxLqfBhoJg-Q@mail.gmail.com>
 <1517329742.15543.15.camel@braverock.com>
 <aef83954-b118-6f8f-6d4f-d2a9758121cc@gmail.com>
 <CY4PR2001MB10641A6B87B06111469FDBD0BEE40@CY4PR2001MB1064.namprd20.prod.outlook.com>
 <23152.57287.697853.990831@rob.eddelbuettel.com>
 <CAPekMCkWYvdGJ=wXA3bGFs655xsV6RUFCCjFpcpZ4rjmB8u-VQ@mail.gmail.com>
 <a8fbf26f-5a4c-3526-68a5-e062a596313c@gmail.com>
 <CABdHhvGGCpjFa-dPiK6fHLfVzCzZ3PboGSH9c8Jy+daW14vSNg@mail.gmail.com>
 <89bbc3b2-b173-961d-5cd2-fc83c05600dc@gmail.com>
 <aacda07a-836c-313d-5cc9-c32a5d178f7f@gmail.com>
Message-ID: <CABdHhvHojfnMfOp9P7bm6zPCXz00M3XxidFMXyzqHUw7yy9oQw@mail.gmail.com>

On Thu, Feb 1, 2018 at 4:29 AM, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
> On 31/01/2018 6:59 AM, Duncan Murdoch wrote:
>>
>> On 30/01/2018 11:39 PM, Hadley Wickham wrote:
>
>  [ lots deleted ]
>>>
>>> Personally, I don't find writing in comments any harder than writing
>>> in .Rd files, especially now that you can write in markdown and have
>>> it automatically translated to Rd formatting commands.
>>
>>
>> I didn't know about the possibility of Markdown.  That's a good thing.
>> You didn't say what editor you use, but RStudio is a good guess, and it
>> also makes it easier to write in comments.
>
>
> I've taken a look at the Markdown support, and I think that is fantastic.
> I'd rather it wasn't inline in the .R file (does it have to be?), but I'd
> say it tips the balance, and I'll certainly experiment with using that for
> new projects.

Please do let me know how it goes - often a fresh set of eyes reveals
problems that an experienced user is blind to.

> The only negative I see besides forcing inline docs is pretty minor:  I can
> see that supporting Rd markup within the Markdown text will on rare
> occasions cause lots of confusion (because users won't know why their
> backslashes are doing funny things).  I'd suggest that (at least optionally)
> you should escape anything that looks like Rd markup, so a user can put text
> like \item into the middle of a paragraph and not have the Rd parser see it.

Yes, that would certainly be nice. It's a little challenging because
we're using the commonmark parser, but it should be possible somehow.

Hadley

-- 
http://hadley.nz



[Rd] Best practices in developing package: From a single file
Hadley Wickham