Re: Customizing @var?

On Sun, Sep 25, 2022 at 11:16:13PM -0700, Robert Dodier wrote:
> On Sun, Sep 25, 2022 at 2:55 PM Raymond Toy <[email protected]> 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?

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.