Re: Defining convenience wrapper for @def... categories

[Gavin Smith]

On Fri, Jan 20, 2023 at 09:13:13PM +0100, Arsen Arsenović wrote:
> Hi,
> 
> I'm working on the GCC manual again (finally!), and I'm trying to
> harmonize it on using definition commands for built-ins et al.  For
> writing convenience, as well as consistency, I'd like to define aliases
> for commonly-used categories (for instance, I'd like to define a
> @defbuiltin = @deftypefn {Built-in Function} ...).
> 
> I tried the obvious:
> 
>   @c Convenience macro for defining builtins, in similar spirit
>   @c to @deftypefun for functions.
>   @macro defbuiltin
>   @deftypefn {Built-in Function}
>   @end macro
> 
>   @macro defbuiltinx
>   @deftypefnx {Built-in Function}
>   @end macro
> 
> The above, however, is not a drop-in replacement for the fully expanded
> form, since something like
> 
>   @defbuiltin {size_t} __builtin_object_size ...
> 
> ... breaks, where the expanded equivalent does not

Yes: unfortunately, macro expansion in texinfo.tex is not reliable
in all contexts.

You can work around it by making the macro take an argument and expand to
the whole line.  I believe this is what the groff manual does.

The following works:

  @macro defbuiltin {rest}
  @deftypefn {Built-in Function} \rest\
  @end macro
  
  @defbuiltin size_t __builtin_object_size @dots{}
  explanation
  @end deftypefn

as does

  @defbuiltin{{size_t} __builtin_object_size @dots{}}
  explanation
  @end deftypefn

This is not perfect of course, but it is the best we can do for now, short
of inventing new language features.

The following does not work because the argument to @defbuiltin is
taken as "size_t" only:

  @defbuiltin {size_t} __builtin_object_size @dots{}
  explanation
  @end deftypefn

> This also requires that the command is terminated by @end deftypefn,
> which exposes the detail of the implementation of the macro, and hence
> is a bit ugly.

You can also define a macro for the @end line:

  @macro defbuiltin {rest}
  @deftypefn {Built-in Function} \rest\
  @end macro
  
  @macro enddefbuiltin
  @end deftypefn
  @end macro
  
  @defbuiltin{{size_t} __builtin_object_size @dots{}}
  explanation
  @enddefbuiltin

> What's the idiomatic way to make such an alias?  Is there any currently?

I don't know if this counts as idiomatic or recommended, just that there
doesn't seem to be any other better way of doing it.