"See also" help is doubling all the `@` signs

cbm755 commented 8 months ago

See also: syms, assumptions, @@sym/assume, @@sym/assumeAlso.

Code looks like:

%% @seealso{@@sym/ellipticK, @@sym/ellipticE, @@sym/ellipticPi}

I thought it had to be like that to escape the @ command in texinfo... maybe it changed...?

cbm755 commented 8 months ago

They need doubled in Octave 5.2.2 on Ubuntu 20.04, where

makeinfo --version
texi2any (GNU texinfo) 6.7

cbm755 commented 8 months ago

My Fedora 39 system has:

makeinfo --version
texi2any (GNU texinfo) 7.0.3

In the Octave source, I found this change:

Author: Rik <rik@octave.org>
Date:   Wed Dec 29 08:41:33 2021 -0800

    doc: Allow links to old-style class files (@class/) in Texinfo @seealso macro.

    * mk-doc-cache.pl: Replace '@' with '@@' when expanding @seealso macro to
    @xseealso macro.  Also, many code formatting tweaks for clarity.

    * __makeinfo__.m: Replace '@' with '@@' when expanding @seealso macro to
    @xseealso macro.

cbm755 commented 8 months ago

Seems this was for 8.1.0, so probably we should change everything... Older Octave's will see this kind of warning:

>>> help @sym/ellipticF
/tmp/octave-help-yKmv1e:197: unknown command `sym' (possibly involving @xseealso)
/tmp/octave-help-yKmv1e:197: unknown command `sym' (possibly involving @xseealso)
warning: help: Texinfo formatting filter exited abnormally; raw Texinfo source of help text follows...
'@sym/ellipticF' is a function from the file /mnt/@sym/ellipticF.m

The alternative is to nudge upstream to support help sym.ellipticF so we don't have to do this change more than once. And just leave the double @@ in the official docs (or use Octave 7.3.0 to generate them).

gnu-octave / symbolic

"See also" help is doubling all the `@` signs #1288