public inbox for libc-alpha@sourceware.org
 help / color / mirror / Atom feed
* [PATCH v2 0/5] Header & Standards Cleanup
@ 2016-12-06 10:55 Rical Jasan
  2016-12-06 10:55 ` [PATCH v2 1/5] manual: Refactor header and standards annotations Rical Jasan
                   ` (5 more replies)
  0 siblings, 6 replies; 91+ messages in thread
From: Rical Jasan @ 2016-12-06 10:55 UTC (permalink / raw)
  To: libc-alpha; +Cc: joseph, mtk.manpages, carlos

[-- Attachment #1: Type: text/plain, Size: 3043 bytes --]

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

Checking for missing or invalid annotations would yield a plethora of
errors in the manual's current state, so the first step is simply to
make annotations complete or correct, according to the expectations of
summary.awk.  This results in many new and fixed entries in the
Summary, while making subsequent work on a more comprehensive
framework easier.

A new script is introduced, check-stds.pl, which will indicate an
error for any missing or invalid annotations, and report them.

A convention for standards names is currently under discussion, and
this patchset assumes certain names will be preferred.  To that end,
some alternate spellings/representations of standards are changed in
order to reduce the variety of standards names in current use, making
future work on consistent names easier.

Over 300 new entries are added to the Summary of Library Facilities as
a result of this patchset, and many others have their entries fixed
(commonly due to a header having been displayed as a standard).
---
 manual/Makefile      |   1 +
 manual/argp.texi     |  28 +++++++
 manual/arith.texi    |  38 ++++++++--
 manual/check-stds.pl | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++
 manual/conf.texi     |  72 +++++++++---------
 manual/creature.texi |  12 +--
 manual/filesys.texi  |  91 +++++++++++++---------
 manual/ipc.texi      |  28 +++++++
 manual/lang.texi     |  20 +++++
 manual/llio.texi     | 118 +++++++++++++++++++++++-----
 manual/locale.texi   | 168 +++++++++++++++++++++++++++++++++++++++-
 manual/math.texi     |  26 +++++++
 manual/memory.texi   |  33 +++++++-
 manual/message.texi  |   6 +-
 manual/nss.texi      |  12 ++-
 manual/pattern.texi  |  36 +++++++++
 manual/platform.texi |  20 +++++
 manual/process.texi  |  16 +++-
 manual/resource.texi |  57 +++++++++-----
 manual/search.texi   |  16 +++-
 manual/signal.texi   |  33 ++++----
 manual/socket.texi   |  42 +++++-----
 manual/startup.texi  |   2 +
 manual/stdio.texi    |  59 ++++++++++++--
 manual/string.texi   |   4 +-
 manual/summary.awk   |   3 +-
 manual/sysinfo.texi  |  58 +++++++++++++-
 manual/syslog.texi   |  68 ++++++++++++++++-
 manual/terminal.texi |  37 ++++-----
 manual/time.texi     |  14 +++-
 manual/users.texi    |  41 ++++------
 31 files changed, 1128 insertions(+), 242 deletions(-)
 create mode 100755 manual/check-stds.pl

-- 
2.10.0

^ permalink raw reply	[flat|nested] 91+ messages in thread

end of thread, other threads:[~2017-06-16 13:40 UTC | newest]

Thread overview: 91+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-12-06 10:55 [PATCH v2 0/5] Header & Standards Cleanup 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
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 2/3] manual: Convert header and standards @comments to @standards 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 1/3] manual: Create empty placeholder macros for @standards Rical Jasan
2017-05-26  5:01       ` [PATCH v5 0/3] manual: Header & Standards Cleanup [conversion script] 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

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