On Sun, Sep 25, 2022 at 11:16:13PM -0700, Robert Dodier wrote:
> On Sun, Sep 25, 2022 at 2:55 PM Raymond Toy <toy.raymond@gmail.com> wrote:
>
> > someone wanted @var{foo}) to be <foo> instead of FOO. It's been that way for quite some time now.
>
> I was somehow under the impression that the unnamed person was me, but
> on reviewing the Git log, it looks like it was actually Vadim
> Zhytnikov (commit d37e1b4, dated 2004-12-20). Let us give credit where
> credit is due.
I don't understand, has building the Maxima docs been broken since 2004?
Has anything changed more recently to break them?
No, the docs have not been broken since 2004. I've only used texinfo 6.8, and the docs currently build fine for the ones I've tested. (There's the English manual, and some older, but still working, German, Spanish, and Portuguese translations. There a partial Russian and Japanese translation, that still work.)
There has never been much customizability of Info output, including for
@var. Info is a very limited format and customization possibilities are
also limited.
The manual states (Info node (texinfo)@var),
> In some documentation styles, metasyntactic variables are shown with
> angle brackets, for example:
>
> ..., type rm <filename>
>
> However, that is not the style that Texinfo uses.
In a @table command, the context might make it clear that they are
function parameters (I'm not sure what exactly the context is here, or
how exactly @var is being used), so @table @asis or @table @code,
or @table @t, might be just as good.
> > This works fine. I used @definfoenclose var,<,> and @var{foo} now produces <FOO> instead of <foo>. Perhaps that's ok to whoever redefined @var.
>
> I dunno, <FOO> with a deprecation warning seems like the worst of both
> worlds -- still has an annoying message, and the output is, um,
> debatable again.
It is inteference with the builtin definition of @var which is why it is
being uppercased. It's not advisable to redefine existing Texinfo commands.
'@definfoenclose Var,<,>' avoids this problem (although
I don't recommend using @definfoenclose at all), although at the expense
of a warning like "@Var should not appear in @table".
I'd like to remove @definfoenclose as a Texinfo command although we'd
have to consider carefully what breakages this might cause. It might not
be practical any time soon to remove it.
Maxima isn't using @definfoenclose now.
At some point, someone did add a new @mvar to display <foo>, but that got reverted. I think it would be a bit confusing to authors to know when to use @mvar vs @var. I'm not really clear myself, but presumably in the maxima manual, @var would never be used and @mvar would be used instead. But anyway, that change was reverted and there would be resistance to go back to that.