From: Rical Jasan <ricaljasan@pacific.net>
To: Zack Weinberg <zackw@panix.com>, libc-alpha@sourceware.org
Cc: Joseph Myers <joseph@codesourcery.com>,
Carlos O'Donell <carlos@redhat.com>,
Michael Kerrisk <mtk.manpages@gmail.com>
Subject: Re: [PATCH v4 0/5] manual: Header & Standards Cleanup
Date: Mon, 22 May 2017 09:03:00 -0000 [thread overview]
Message-ID: <d3e90a38-b516-7e7e-4f6e-1f54c4f47de9@pacific.net> (raw)
In-Reply-To: <a04f7709-9e70-7bf1-fa8c-2626b1323b08@panix.com>
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
next prev parent reply other threads:[~2017-05-22 9:03 UTC|newest]
Thread overview: 91+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-12-06 10:55 [PATCH v2 0/5] " Rical Jasan
2016-12-06 10:55 ` [PATCH v2 1/5] manual: Refactor header and standards annotations Rical Jasan
2016-12-06 13:49 ` Zack Weinberg
2016-12-06 15:33 ` Joseph Myers
2016-12-19 10:37 ` Rical Jasan
2016-12-19 13:48 ` Joseph Myers
2017-02-07 6:46 ` Rical Jasan
2016-12-06 10:55 ` [PATCH v2 4/5] manual: Enforce header and standard requirements Rical Jasan
2016-12-06 10:55 ` [PATCH v2 2/5] manual: Convert @tables of variables to @vtables Rical Jasan
2016-12-06 13:50 ` Zack Weinberg
2016-12-06 15:46 ` Joseph Myers
2016-12-07 15:18 ` Nix
2016-12-08 1:38 ` Rical Jasan
2016-12-21 10:08 ` Rical Jasan
2016-12-21 12:42 ` Joseph Myers
2016-12-06 10:56 ` [PATCH v2 3/5] manual: Add new header and standards annotations Rical Jasan
2016-12-06 13:23 ` Zack Weinberg
2016-12-06 14:27 ` Andreas Schwab
2016-12-06 16:24 ` Joseph Myers
2016-12-06 19:23 ` Zack Weinberg
2016-12-06 21:42 ` Joseph Myers
2016-12-07 16:32 ` Joseph Myers
2016-12-08 2:56 ` Rical Jasan
2016-12-08 14:02 ` Joseph Myers
2016-12-12 9:01 ` Rical Jasan
2016-12-14 18:18 ` Joseph Myers
2016-12-14 23:30 ` Rical Jasan
2016-12-15 9:58 ` Rical Jasan
2016-12-15 13:01 ` Joseph Myers
2017-02-07 5:13 ` Rical Jasan
2017-02-07 16:41 ` Joseph Myers
2017-02-08 8:50 ` Rical Jasan
2017-02-08 13:52 ` Joseph Myers
2017-02-12 6:01 ` Rical Jasan
2017-04-04 3:58 ` Rical Jasan
2017-04-04 11:26 ` Joseph Myers
2017-04-05 3:08 ` Rical Jasan
2017-06-16 13:40 ` Zack Weinberg
2017-06-16 8:28 ` Rical Jasan
2016-12-06 11:42 ` [PATCH v2 5/5] manual: Clean up miscellaneous standards Rical Jasan
2017-05-16 9:55 ` [PATCH v3 0/7] manual: Header & Standards Cleanup Rical Jasan
2017-05-16 9:55 ` [PATCH v3 1/7] manual: Provide one-off standards conversion script Rical Jasan
2017-05-16 9:55 ` [PATCH v3 2/7] manual: Create empty placeholder macros for @standards Rical Jasan
2017-05-16 9:55 ` [PATCH v3 3/7] manual: Fix up invalid header and standards syntax Rical Jasan
2017-05-16 11:51 ` Joseph Myers
2017-05-17 4:49 ` Rical Jasan
2017-05-17 10:03 ` Joseph Myers
2017-05-18 8:10 ` Rical Jasan
2017-05-16 10:27 ` [PATCH v3 7/7] manual: Replace summary.awk with summary.pl Rical Jasan
2017-05-16 10:28 ` [PATCH v3 6/7] manual: Convert header and standards @comments to @standards Rical Jasan
2017-05-16 10:28 ` [PATCH v3 5/7] manual: Convert @tables of annotated @items to @vtables Rical Jasan
2017-05-16 11:53 ` Joseph Myers
2017-05-18 8:11 ` Rical Jasan
2017-05-16 10:29 ` [PATCH v3 4/7] manual: Refactor errno @comments Rical Jasan
2017-05-16 11:06 ` Joseph Myers
2017-05-17 4:44 ` Rical Jasan
2017-05-17 13:21 ` Zack Weinberg
2017-05-17 13:31 ` Zack Weinberg
2017-05-18 9:42 ` Rical Jasan
2017-05-18 12:32 ` Zack Weinberg
2017-05-19 9:46 ` Rical Jasan
2017-05-19 20:50 ` Zack Weinberg
2017-05-19 6:20 ` Rical Jasan
2017-05-18 9:58 ` Rical Jasan
2017-05-19 9:33 ` [PATCH v4 0/5] manual: Header & Standards Cleanup Rical Jasan
2017-05-19 9:33 ` [PATCH v4 2/5] manual: Create empty placeholder macros for @standards Rical Jasan
2017-05-19 21:02 ` Zack Weinberg
2017-05-20 6:05 ` Rical Jasan
2017-05-19 9:34 ` [PATCH v4 1/5] manual: Provide one-off standards conversion script Rical Jasan
2017-05-19 9:34 ` [PATCH v4 5/5] manual: Replace summary.awk with summary.pl Rical Jasan
2017-05-19 9:34 ` [PATCH v4 3/5] manual: Convert errno @comments to new @errno macro Rical Jasan
2017-05-19 21:03 ` Zack Weinberg
2017-05-20 6:05 ` Rical Jasan
2017-05-19 9:36 ` [PATCH v4 4/5] manual: Convert header and standards @comments to @standards Rical Jasan
2017-05-19 21:05 ` [PATCH v4 0/5] manual: Header & Standards Cleanup Zack Weinberg
2017-05-22 9:03 ` Rical Jasan [this message]
2017-05-24 13:12 ` Rical Jasan
2017-05-24 13:29 ` Zack Weinberg
2017-05-26 5:01 ` [PATCH v5 0/3] " Rical Jasan
2017-05-26 5:01 ` [PATCH v5 0/3] manual: Header & Standards Cleanup [conversion script] Rical Jasan
2017-05-26 5:01 ` [PATCH v5 3/3] manual: Replace summary.awk with summary.pl Rical Jasan
2017-05-26 5:01 ` [PATCH v5 2/3] manual: Convert header and standards @comments to @standards Rical Jasan
2017-05-26 5:01 ` [PATCH v5 1/3] manual: Create empty placeholder macros for @standards Rical Jasan
2017-05-31 9:23 ` [PATCH v5 0/3] manual: Header & Standards Cleanup Rical Jasan
2017-06-08 11:46 ` [PING] " Rical Jasan
2017-06-08 13:41 ` Zack Weinberg
2017-06-09 2:31 ` Rical Jasan
2017-06-15 8:47 ` Rical Jasan
2017-06-15 8:32 ` Rical Jasan
2017-06-15 18:01 ` Joseph Myers
2017-06-16 4:38 ` Rical Jasan
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=d3e90a38-b516-7e7e-4f6e-1f54c4f47de9@pacific.net \
--to=ricaljasan@pacific.net \
--cc=carlos@redhat.com \
--cc=joseph@codesourcery.com \
--cc=libc-alpha@sourceware.org \
--cc=mtk.manpages@gmail.com \
--cc=zackw@panix.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).