user defined macros in Rd files

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

user defined macros in Rd files

Kasper Daniel Hansen-2
R-exts, in "2.13 User-defined macros", discusses user-defined macros.  Is
it possible to have macros defined in one file, be used by another (within
a package)?  This would increase the usefulness substantially, IMHO.

Best,
Kasper

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Yihui Xie-2
+1. As an example, there are 91 instances of \newcommand{\CRANpkg} in
R source, and this number is still growing as I see:

$ grep "\\\\newcommand{\\\\CRANpkg}" -r . | wc
     91      91   10317

Regards,
Yihui
--
Yihui Xie <[hidden email]>
Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA


On Wed, Oct 9, 2013 at 2:57 PM, Kasper Daniel Hansen
<[hidden email]> wrote:
> R-exts, in "2.13 User-defined macros", discusses user-defined macros.  Is
> it possible to have macros defined in one file, be used by another (within
> a package)?  This would increase the usefulness substantially, IMHO.
>
> Best,
> Kasper

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Duncan Murdoch-2
On 13-10-09 4:34 PM, Yihui Xie wrote:
> +1. As an example, there are 91 instances of \newcommand{\CRANpkg} in
> R source, and this number is still growing as I see:
>
> $ grep "\\\\newcommand{\\\\CRANpkg}" -r . | wc
>       91      91   10317
>

So you're saying if I ever get around to doing this, I'll have to track
down 91+ files to make use of it?  This sounds like an argument why
someone else should do it. ;-)

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Yihui Xie-2
I mean, it sounds like a better idea to define \CRANpkg only once in
one central place, and use it in base R, instead of defining it in
every single Rd file, because it seems to be generally useful (is 91 a
large number? maybe).

Similarly, when it comes to an add-on package, it will be nice if the
package author can define these macros in one place, and use them in
his/her package.

When we have to copy and paste a macro 91 times, it seems to have
defeated the purpose of a macro.

Regards,
Yihui
--
Yihui Xie <[hidden email]>
Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA


On Wed, Oct 9, 2013 at 3:55 PM, Duncan Murdoch <[hidden email]> wrote:

> On 13-10-09 4:34 PM, Yihui Xie wrote:
>>
>> +1. As an example, there are 91 instances of \newcommand{\CRANpkg} in
>> R source, and this number is still growing as I see:
>>
>> $ grep "\\\\newcommand{\\\\CRANpkg}" -r . | wc
>>       91      91   10317
>>
>
> So you're saying if I ever get around to doing this, I'll have to track down
> 91+ files to make use of it?  This sounds like an argument why someone else
> should do it. ;-)
>
> Duncan Murdoch
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Henrik Bengtsson-3
On Wed, Oct 9, 2013 at 2:04 PM, Yihui Xie <[hidden email]> wrote:

> I mean, it sounds like a better idea to define \CRANpkg only once in
> one central place, and use it in base R, instead of defining it in
> every single Rd file, because it seems to be generally useful (is 91 a
> large number? maybe).
>
> Similarly, when it comes to an add-on package, it will be nice if the
> package author can define these macros in one place, and use them in
> his/her package.
>
> When we have to copy and paste a macro 91 times, it seems to have
> defeated the purpose of a macro.

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.

/Henrik

>
> Regards,
> Yihui
> --
> Yihui Xie <[hidden email]>
> Web: http://yihui.name
> Department of Statistics, Iowa State University
> 2215 Snedecor Hall, Ames, IA
>
>
> On Wed, Oct 9, 2013 at 3:55 PM, Duncan Murdoch <[hidden email]> wrote:
>> On 13-10-09 4:34 PM, Yihui Xie wrote:
>>>
>>> +1. As an example, there are 91 instances of \newcommand{\CRANpkg} in
>>> R source, and this number is still growing as I see:
>>>
>>> $ grep "\\\\newcommand{\\\\CRANpkg}" -r . | wc
>>>       91      91   10317
>>>
>>
>> So you're saying if I ever get around to doing this, I'll have to track down
>> 91+ files to make use of it?  This sounds like an argument why someone else
>> should do it. ;-)
>>
>> Duncan Murdoch
>>
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Duncan Murdoch-2
On 13-10-09 7:54 PM, Henrik Bengtsson wrote:

> On Wed, Oct 9, 2013 at 2:04 PM, Yihui Xie <[hidden email]> wrote:
>> I mean, it sounds like a better idea to define \CRANpkg only once in
>> one central place, and use it in base R, instead of defining it in
>> every single Rd file, because it seems to be generally useful (is 91 a
>> large number? maybe).
>>
>> Similarly, when it comes to an add-on package, it will be nice if the
>> package author can define these macros in one place, and use them in
>> his/her package.
>>
>> When we have to copy and paste a macro 91 times, it seems to have
>> defeated the purpose of a macro.
>
> 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.

Duncan Murdoch

>
> /Henrik
>
>>
>> Regards,
>> Yihui
>> --
>> Yihui Xie <[hidden email]>
>> Web: http://yihui.name
>> Department of Statistics, Iowa State University
>> 2215 Snedecor Hall, Ames, IA
>>
>>
>> On Wed, Oct 9, 2013 at 3:55 PM, Duncan Murdoch <[hidden email]> wrote:
>>> On 13-10-09 4:34 PM, Yihui Xie wrote:
>>>>
>>>> +1. As an example, there are 91 instances of \newcommand{\CRANpkg} in
>>>> R source, and this number is still growing as I see:
>>>>
>>>> $ grep "\\\\newcommand{\\\\CRANpkg}" -r . | wc
>>>>        91      91   10317
>>>>
>>>
>>> So you're saying if I ever get around to doing this, I'll have to track down
>>> 91+ files to make use of it?  This sounds like an argument why someone else
>>> should do it. ;-)
>>>
>>> Duncan Murdoch
>>>
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Michael Weylandt


On Oct 9, 2013, at 21:18, Duncan Murdoch <[hidden email]> 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.

Michael

> Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Duncan Murdoch-2
On 13-10-12 6:49 PM, R. Michael Weylandt <[hidden email]> wrote:

>
>
> On Oct 9, 2013, at 21:18, Duncan Murdoch <[hidden email]> 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.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Henrik Bengtsson-3
On Sat, Oct 12, 2013 at 3:58 PM, Duncan Murdoch
<[hidden email]> wrote:

> On 13-10-12 6:49 PM, R. Michael Weylandt <[hidden email]> wrote:
>>
>>
>>
>> On Oct 9, 2013, at 21:18, Duncan Murdoch <[hidden email]> 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
>
>
>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: user defined macros in Rd files

Yihui Xie-2
In reply to this post by Duncan Murdoch-2
Hi Duncan,

Thanks a lot for eventually implementing this and making the Rd world
greener! https://github.com/wch/r-source/commit/ff3ea81ae87

Regards,
Yihui
--
Yihui Xie <[hidden email]>
Web: http://yihui.name


On Wed, Oct 9, 2013 at 3:55 PM, Duncan Murdoch <[hidden email]> wrote:

> On 13-10-09 4:34 PM, Yihui Xie wrote:
>>
>> +1. As an example, there are 91 instances of \newcommand{\CRANpkg} in
>> R source, and this number is still growing as I see:
>>
>> $ grep "\\\\newcommand{\\\\CRANpkg}" -r . | wc
>>       91      91   10317
>>
>
> So you're saying if I ever get around to doing this, I'll have to track down
> 91+ files to make use of it?  This sounds like an argument why someone else
> should do it. ;-)
>
> Duncan Murdoch
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel