Skip to content

[R-pkg-devel] How to write a 'cases' environment in .Rd files?

3 messages · Marius Hofert, Deepayan Sarkar, Ivan Krylov

Original
Marius Hofert
# 
Hi,

For quite some time my .Rd files had 'cases' environments like these:

\deqn{F(x) = \cases{
1,&if x > 0,\cr
0,&if x = 0.\cr}}{...}

Since recently, r-devel-linux-x86_64-debian-clang and r-devel-linux-x86_64-debian-gcc trigger the note 'Undefined control sequence: \cases in F(x) = \cases{...', possibly due to KaTeX rendering help pages. I looked around quite a bit but couldn't find a way to implement 'cases' environments. For example, https://katex.org/docs/supported.html#environments mentions \begin{cases} \end{cases}, so I tried

\deqn{F(x) = \begin{cases}
1,&\text{if}\ x > 0,\\
0,&\text{if} x = 0.}}{...}

but that triggers:

...
* checking PDF version of manual ... WARNING
LaTeX errors when creating PDF version.
This typically indicates Rd problems.
LaTeX errors found:
! Misplaced alignment tab character &
....

What is the proper way (is there one?) to get displayed 'cases' environments in .Rd files?

Thanks & cheers,
Marius
Deepayan Sarkar
# 
On Fri, Aug 12, 2022 at 12:14 AM Marius Hofert <marius.hofert at uwaterloo.ca>
wrote:
Yes, the PDF refmans don't support amsmath (so no \begin{pmatrix},
\begin{cases}, etc.), although \pmatrix and \cases are supported. KaTeX has
it the other way around.

Unfortunately there is no nice workaround at the moment. Even if the PDF
version begins supporting \begin{cases} by including amsmath, \cases will
stop working, and your package will need to depend on a very recent R.

Possibly the only practical workaround is to use more basic LaTeX
constructs such as \begin{array}.

Best,
-Deepayan

  
  


  


      

    

    

      
      

        


  

        

      Ivan Krylov
    

    

      
      #
    

  


  

      
On Thu, 11 Aug 2022 18:43:44 +0000

        
Marius Hofert <marius.hofert at uwaterloo.ca> wrote:

        

            

      
      
      
    

        
There is a possible workaround, but it's the opposite of beautiful. You
can use conditional text to compile one version of the formula for HTML
help and another one for PDF help:

\ifelse{html}{\eqn{\begin{cases}...}}{\eqn{\cases{...}}{ascii}}

It's as tedious as it looks. For extra style(?) points, you can put a
three-argument user-defined macro in man/macros/whatever.Rd that
forwards its arguments to one of the \ifelse branches. As far as I
remember, \newcommand{}{} has to fit on one line, but in R ? 3.6.0,
macros themselves can take multi-line arguments.

If you're targeting an earlier version of R, you can make multi-line
arguments work by forcing R to cache the parse tree of the man page
while building a source tarball with a newer R version using
\Sexpr[stage=build]{}, costing you some time during R CMD build and a
slightly larger source tarball. (It's an implementation detail that one
normally shouldn't depend upon. Thankfully, as of 2022, there won't be
any newer versions of R ? 3.5.x to break it.) Support for
man/macros/*.Rd only appeared in R-3.2.0, so I haven't researched
compatibility tricks for even older versions of R.