This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v4 0/5] manual: Header & Standards Cleanup
- From: Zack Weinberg <zackw at panix dot com>
- To: Rical Jasan <ricaljasan at pacific dot net>, libc-alpha at sourceware dot org
- Cc: Joseph Myers <joseph at codesourcery dot com>, Carlos O'Donell <carlos at redhat dot com>, Michael Kerrisk <mtk dot manpages at gmail dot com>
- Date: Fri, 19 May 2017 17:05:34 -0400
- Subject: Re: [PATCH v4 0/5] manual: Header & Standards Cleanup
- Authentication-results: sourceware.org; auth=none
- References: <cover.1494920105.git.ricaljasan@pacific.net> <20170519093353.6158-1-ricaljasan@pacific.net>
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.
> 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?
I do not feel qualified to review Perl code; I haven't used the language
for anything nontrivial in many years. Because of this I am not going
to review your patch 1 or 5.
> In order to provide insight on the differences between summary.awk and
> summary.pl, and how @standards will differ from the @comment-based
> annotations, some analysis of the immediate and expected long-term
> differences follows.
I also appreciate your providing this analysis and I think temporary
omission of certain entries from the summary files is fine. I'd like an
answer to the above very high-level question before we proceed with the
conversion, though.
zw