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

[Rical Jasan <ricaljasan at pacific dot net>]

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.

>> This patchset uses a script to convert existing @comment-based
>> annotations to @standards.  First, the script is submitted for review,
>> then the @standards* macros are added to macros.texi.  Next, a number
>> of fixes are applied to various syntax issues and then the conversion
>> takes place.  Lastly, summary.awk is replaced by summary.pl, in order
>> to generate summary.texi from the new @standards.
> 
> I appreciate your providing the conversion script, but I'm not sure it
> should be checked in.  Are we ever going to use it again after this
> process is complete?

No.  It isn't intended to be committed; it's supplied purely for review
of the conversion patch.

Instead of manually sending an auxiliary patch I just included it in the
`git send-email' patches, since I track it locally too.  I have commit
access, and since I'll presumably be the one to push, I know not to
include it.  I thought I said "this is not intended to be committed" in
its "commit message", but it looks like that got lost along the way.

Rical