[Rd] user defined macros in Rd files

[Henrik Bengtsson]

On Sat, Oct 12, 2013 at 3:58 PM, Duncan Murdoch
<murdoch.duncan at gmail.com> wrote:
> On 13-10-12 6:49 PM, R. Michael Weylandt <michael.weylandt at gmail.com> wrote:
>>
>>
>>
>> On Oct 9, 2013, at 21:18, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
>>
>>> On 13-10-09 7:54 PM, Henrik Bengtsson wrote:
>>>>
>>>>
>>>>
>>>> On my related wishlist: A standardized mechanism to 'R CMD build' for
>>>> building man/*.Rd from any input format (e.g. roxygen and so on)
>>>> analogously how we can now build vignettes of any input format.  With
>>>> that in place, it would a be piece of cake to include macros from
>>>> external files.
>>>>
>>>> Just wanted to throw it out there.
>>>
>>>
>>> No, we certainly won't do that.  We rely on being able to process the Rd
>>> files in multiple ways.
>>>
>>
>> I'm a but confused here Duncan:
>>
>> Henrik's proposal still results in the Rd files being created and then all
>> of the cool things which get done (example checking, HTML, PDF, etc.) can
>> carry on as usual. Since those are all done from the tarball by R CMD build,
>> they can't know how the Rd files were created in the first place.
>>
>> Can you say a bit more about what would break? I'm afraid I'm missing
>> something obvious.
>
>
> I was assuming he wanted to build the help system from another format. If he
> just wants to build a standard *.Rd file from something else, then why get
> "R CMD build" involved?  Why not just do it in two steps, "make the help,
> build the tarball"?   He'll have to clarify, but the comment about vignettes
> makes me think I'm right:  you can have a vignette in any format, and you
> just need a way to convert it to HTML or PDF, it doesn't need to become a
> Sweave document first.

To clarify, my suggestion/wish was not to replace the Rd format but a
*cross-platform* and *standardized* ("the one-and-only way") mechanism
for generating Rd files (which is *the* documentation/example/...
format of R).  The analogue to vignette engines that now support any
input format and outputs PDF or HTML files, "Rd engines" would take
any input format and output Rd files, and from there it's business as
usual.

Several developers already do this (e.g. roxygen2 -> Rd) before 'R CMD
build' either manually, via make or other home-brewed approaches.  It
would great if this would be standardized, and, analogously to how
vignettes are built, doing this during 'R CMD build' is a natural
candidate.

As I said, just throwing it out as a proposal to get the
discussion/thoughts going.  I'm sure others though about this too over
the years.

Cheers,

Henrik

>
> Duncan Murdoch
>
>
>
>