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

[Arsen Arsenović]

Hi Gavin,

Gavin Smith <gavinsmith0123@gmail.com> writes:

> 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

Yes, this is quite nice.

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

Hmm, even if we choose to do that, I can't think of a concise but
consistent way of defining categories.  Best I can come up with is, e.g.
@defcategory{bn}, which'd declare @defbntypefun, analogously for others.

> 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

Yup, so said the diagnostic message :)

>> 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

Ah!  I didn't even think to try this because I thought that it'd result
in a mismatched start/end.  This is nice.

>> 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.

This seems to work like a charm, so as long as it's not exploiting some
bug/UB, it should be fine.

BTW, I noticed that here, like with @ftable's @itemx, each "alternative"
becomes a separate index target, at least in HTML and Info.  I'm
thinking of implementing a transform that "bubbles" @\([-a-zA-Z]\)*x
indices to their respective @\1, do you think these should get the same
transform?

Thanks again, have a great evening!
-- 
Arsen Arsenović

signature.asc
Description: PGP signature