13

I'm in the process of documenting some of my functions for an R package I'm making.

I'm using roxygen markup, though that is largely irrelevant to my question.

I have put equations into my documentation using \deqn{...}. My question is: Is there a way to cross-reference this equation later on?

For example, in my Rd file:

\deqn{\label{test}
 y = mx + b
}

Can I later do something like:

Referring to equation \ref{test}, ...

I've tried \eqref{test}, \ref{test} (which both get "unknown macro" and don't get linked ), and also \link{test} (which complains it can't find function test because it's really just for linking to other functions).

Otherwise I fear I may have to do something hacky and add in the -- (1) and Refer to equation (1) manually within the \deqn etc in the Rd file...

Update

General answer appears to be "no". (awww...)

However, I can write a vignette and use "normal" latex/packages there. In any case, I've just noticed that the matrix equations I spent ages putting into my roxygen/Rd file look awful in the ?myFunction version of the help (they show up as just-about literal latex source). Which is a shame, because they look beautiful in the pdf version of the help.

@Iterator has pointed out the existence of conditional text, so I'll do ASCII maths in the .Rd files, but Latex maths in the pdf manual/vignette.

Community
  • 1
  • 1
mathematical.coffee
  • 55,977
  • 11
  • 154
  • 194
  • Interesting question, and, indeed, manually referencing equation #s is not sustainable. Given that the `.Rd` format is just the most basic LaTeX, and does not support the AMS extensions, I'm not sure if this is feasible. It may be that you have to use a vignette for it. – Iterator Feb 21 '12 at 23:42
  • At the moment I have a whole bunch of "In the equation above..." "In the large matrix equation..." - it's a bit awkward! (I don't have too many equations per Rd file though - I might lower myself to hacking a "--(1)" into the `deqn` and then just say "Refer to equation 1" in the text..but it feels so wrong!) – mathematical.coffee Feb 21 '12 at 23:52
  • 1
    Maybe a vignette is a better way to go? I am not yet particularly familiar with the .Rd format, but I'm not particularly attracted to a documentation format that appears to be a subset of LaTeX. Your question is good, but, IMO, that's because it points out either a flaw in the .Rd approach or a flaw in the documentation for the .Rd approach. (I'm also going to begin documenting a lot of code & equations, so I have a similar question in my queue of questions to investigate.) – Iterator Feb 21 '12 at 23:59
  • FWIW: See [this info on vignettes](http://cran.r-project.org/doc/manuals/R-exts.html#Writing-package-vignettes): "By including the PDF version in the package sources it is not necessary that the vignette PDFs can be re-built at install time, i.e., the package author can use ... LaTeX extensions which are only available on his machine." That's all that I need to read to be sold on this. :) – Iterator Feb 22 '12 at 00:03
  • I think I will write a vignette for the maths part, but I'm still deciding whether I'd like the `?myFunction` to show the maths as well -- I'll either say "For further information on the maths, see the vignette", or I'll put in the maths there too with the clunky "In the above equation..". – mathematical.coffee Feb 22 '12 at 00:04
  • (Cont'd) It's also not unheard of to not entirely document things in the .Rd format. Hadley Wickham has a few functions or packages where the help file refers to his site for full documentation. That seems reasonable, too. – Iterator Feb 22 '12 at 00:07
  • Hmm, looking at the documentation, it seems that equations in the console are constrained to looking only slightly better than raw LaTeX. That's unfortunate. I guess my own interests are resolved. :) – Iterator Feb 22 '12 at 00:16
  • gaaaah, that only just occured to me (I have matrix equations in my documentation) -- they display as literal latex in the `?myFunction` (I use the terminal). So I'll go with ASCII maths for the .Rd and proper maths in the vignette. It's a shame, though - I use roxygen so by using latex maths in the .Rd (well, in the .r file actually) I automatically get a beautiful PDF manual auto-compiled. Shame I can't say "if .Rd version, use this code; if pdf version, use this code". – mathematical.coffee Feb 22 '12 at 00:16
  • Well, there is [conditional text](http://cran.r-project.org/doc/manuals/R-exts.html#Conditional-text) - I think that may be one way to do it. – Iterator Feb 22 '12 at 00:19
  • Umm, to be clarify (okay, to be pedantic): I don't think we know that the general answer is no. At least I don't know that. I just know that it looks like there is frustration to be had in shoehorning LaTeX conveniences into .Rd files. :) – Iterator Feb 22 '12 at 00:27

1 Answers1

6

I'm compiling my comments above into an answer, for the benefit of others.

First, I do not actually know whether or not .Rd supports tagging of equations. However, the .Rd format is such a strict subset of LaTeX, and produces very primitive text output, that shoehorning extensive equations into its format could be a painful undertaking without much benefit to the user.

The alternative is to use package vignettes, or even externally hosted documentation (as is done by Hadley Wickham, for some of his packages). This will allow you to use PDFs or other documentation, to your heart's content. In this way, you can include screenshots, plots, all of the funkiest LaTeX extensions that only you have, and, most significantly, the AMS extensions that we all know and love.

Nonetheless, one can specify different rendering of a given section of documentation (in .Rd) based on the interface, such as text for the console, nice characters for HTML, etc., and conditional text supports that kind of format variation.

It's a good question. I don't know the answer regarding feasibility, but I had similar questions about documenting functions and equations together, and this investigation into what's feasible with .Rd files has convinced me to use PDF vignettes rather than .Rd files.

Iterator
  • 20,250
  • 12
  • 75
  • 111
  • Ah, you beat me to it - I see that the update has the same conclusions. :) – Iterator Feb 22 '12 at 00:28
  • 1
    While I love Hadley's documentation itself, I'm not a fan of the fact that all his help files say "refer to the website" -- it annoys me to no end when I go `?somefunction` and then have to go open up a web browser and copy/paste the URL in. In the case of `ggplot2` I think this is justified, given how graphic-dependent the documentation is, but it's not a path I'd like to go down. – mathematical.coffee Feb 22 '12 at 01:13
  • 1
    I agree about that for even elementary documentation. Still, I am currently using LaTeX-enabled wikis for software documentation, with support for forums, bug tracking, and more, so even a static PDF is a step backwards. :) There is something to be said about having documentation that evolves separately from code, such as being able to offer up new examples of usage or revisions of the documentation based on feedback. There's a balance to be found between offering a quick reference and supporting comprehensive documentation. – Iterator Feb 22 '12 at 01:19