Re: [PATCH v4 0/5] manual: Header & Standards Cleanup

[Rical Jasan <ricaljasan@pacific.net>]

On 05/22/2017 02:03 AM, Rical Jasan wrote:
> On 05/19/2017 02:05 PM, Zack Weinberg wrote:
>> On 05/19/2017 05:33 AM, Rical Jasan wrote:
>>> There exists a convention for annotating which headers and standards a
>>> given function, variable, etc., provided by the glibc come from,
>>> guaranteeing their automatic inclusion in the Summary of Library
>>> Facilities, where they are indexed along with their headers and
>>> standards.  The convention is based upon expectations present in
>>> summary.awk, though that script does not do any enforcing, merely
>>> indexing what it can find.  It is roughly:
>>>
>>>   @comment HEADER(S)
>>>   @comment STANDARD(S)
>>>   @(def|item|vindex)
>>>
>>> It would be nice to use something other than ad-hoc @comments for such
>>> annotations, and also provide a framework for ensuring annotations
>>> exist and are correctly formatted.  To that end, a new set of macros
>>> are proposed: @standards and @standardsx.
>>>
>>> Examples of intended use are:
>>>
>>>   @item FOO
>>>   @standards{STD, HDR}
>>>
>>>   @defvar BAR
>>>   @standards{STD1, HDR1}
>>>   @standards{STD2, HDR2}
>>>
>>>   @deftypefun foo
>>>   @deftypefunx fool
>>>   @standardsx{foo, STD, HDR}
>>>   @standardsx{fool, STD, HDR}
>>
>> Very high-level question: why can't this third case be
>>
>>     @deftypefun foo
>>     @deftypefunx fool
>>     @standards{STD, HDR}
>>
>> or, when foo was in C89 but foof/fool were added in C99 (for instance)
>>
>>     @deftypefun foo
>>     @deftypefunx foof
>>     @deftypefunx fool
>>     @standards{STD1, HDR}
>>     @standardsx{foof, STD2, HDR}
>>     @standardsx{fool, STD2, HDR}
>>
>> That is, @standards sets the default for the entire @deftypefun{x}
>> group, and then @standardsx can override specific cases if necessary.
>> This should make at least some @deftypefun{x} groups less repetitive.
> 
> There is no technical reason we can't or shouldn't do that.
> 
> After exploring this and examining my process a bit, I think it stemmed
> from the initial step of getting the conversion script working (needing
> to put all discovered annotations somewhere), but I can adjust it
> accordingly.  The conversion script will need to be a little smarter,
> and summary.pl's checks will need to be changed, but the above approach
> will avoid wasting a lot of rendered space (e.g., fromfp, et al.), so
> I'm in favour.

The only exceptional case is tgamma, et al.:

  @comment math.h
  @comment XPG, ISO
  @deftypefun double tgamma (double @var{x})
  @comment math.h
  @comment XPG, ISO
  @deftypefunx float tgammaf (float @var{x})
  @comment math.h
  @comment XPG, ISO
  @deftypefunx {long double} tgammal (long double @var{x})

The first element in the list has multiple annotations, so there is no
"default".

Once we get around to completing annotations, there may be others we
would like to annotate similarly.  For now, I have the conversion script
leaving the entire tgamma block as @standardsx without a default @standards:

  @deftypefun double tgamma (double @var{x})
  @deftypefunx float tgammaf (float @var{x})
  @deftypefunx {long double} tgammal (long double @var{x})
  @standardsx{tgamma, XPG, math.h}
  @standardsx{tgamma, ISO, math.h}
  @standardsx{tgammaf, XPG, math.h}
  @standardsx{tgammaf, ISO, math.h}
  @standardsx{tgammal, XPG, math.h}
  @standardsx{tgammal, ISO, math.h}

I like using @standards in @*x lists because it more closely follows the
usual Texinfo syntax, but it's still not exactly the same with
@standardsx being optional, so I don't see a reason to not allow the
all-@standardsx syntax as well, if it gets us what we need.

At this point, the generated summary.texi is the same as v4, but I
wanted to bring this up before I finish v5 in case anybody had any other
thoughts.

Rical