From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 58179 invoked by alias); 16 May 2017 09:55:12 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 57933 invoked by uid 89); 16 May 2017 09:55:11 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-14.9 required=5.0 tests=AWL,BAYES_00,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,KAM_ASCII_DIVIDERS,RP_MATCHES_RCVD,SPF_PASS autolearn=ham version=3.3.2 spammy=ado, insight, respected, Facilities X-HELO: smtp.pacific.net From: Rical Jasan To: libc-alpha@sourceware.org Cc: Joseph Myers , Carlos O'Donell , Michael Kerrisk Subject: [PATCH v3 0/7] manual: Header & Standards Cleanup Date: Tue, 16 May 2017 09:55:00 -0000 Message-Id: In-Reply-To: <20161206105525.21117-1-ricaljasan@pacific.net> References: <20161206105525.21117-1-ricaljasan@pacific.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="------------2.12.2" X-SW-Source: 2017-05/txt/msg00471.txt.bz2 This is a multi-part message in MIME format. --------------2.12.2 Content-Type: text/plain; charset=UTF-8; format=fixed Content-Transfer-Encoding: 8bit Content-length: 8275 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} 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. summary.pl contains all the machinery to perform syntax-checking and report errors, but since the manual is still largely incomplete with regards to header and standards annotations, it is not turned on. The script has been written so that once the manual is completely annotated, a simple two-line patch will begin enforcing @standards. 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. Analysis of the generated summary.texis is not straightforward because summary.awk respected the user's locale, and while summary.pl does too, the C locale is now imposed in the Makefile, which will result in consistent ordering across builds. Further, summary.pl has improved detection of the names of annotated elements, which affects sorting; specifically, extraneous syntax is removed from function pointers (3), functions that return pointers where the "*" character is attached to the element name (2), and structs, which no longer include "struct" for purposes of indexing and sorting (47). Overall, nine new entries are present, due to either partial header and standard annotations being completed (5; albeit with "???", since the conversion can't know what should go there) or seeming idiosyncrasies in summary.awk (4). Forty-eight entries are no longer present. While this number seems high, there are a variety of reasons, a few of which are actually more correct, and most of which will be addressed by future clean up requiring more than the basic mechanical changes in this patchset. The absent count is based on unique entries, so isn't entirely representative of the changes. In particular, due to the difference in name detection, some entries are duplicates now (7). One example is mallinfo, for which summary.awk used "mallinfo" (the function) and "struct mallinfo" (the data type). summary.pl sorts both by "mallinfo", so they are now adjacent. The entries are immediately distinguishable, however, as the Summary shows the prototypes, not merely the names of the elements. One entry is present in both the absent (1) and new counts: error_print_progname. summary.awk detected it as "(void)", while summary.pl extracts "error_print_progname". The legitimate absences (5) are all due to the fact summary.pl ignores everything in @ignore context, whereas summary.awk did not. The remaining absences will be addressed in future patches. There is an annotated @item in a @table (1), which is recognized as an error because that is not a generally annotatable context. There is also a block of annotated @vindex commands (20), which summary.awk picked up but summary.pl does not because @standards are expected to be rendered at some point, and @vindex commands are not rendered; instead, such a situation provokes an error. Lastly, due to the way summary.pl handles errors, partially annotated elements are no longer present (14). Instead of attempting to determine what was and wasn't annotated, the affected blocks of @*x commands are deferred until they are fixed, so that summary.pl does not require modification once it begins enforcing syntax (such partial annotation errors are reported as a group). The conversion of existing @comment-based annotations to @standards is the immediate goal of this patchset, expected to be followed by another patchset completing annotations and making summary.pl begin enforcing the presence and syntax of @standards, helping establish a minimum and mandatory baseline for complete documentation. The follow-up patchset is expected to require a greater level of review, due to both volume and the fact new @standards will need a higher level of scrutiny. In the long term, @standards are expected to be rendered in place, similar to @safety. Some discussion has already taken place around this, but by defining @standards* to be empty macros, time and care may be taken about how that is done, allowing it to be switched on everywhere when ready. A related discussion which has also begun is the canonicalization of standards names, which may also influence the completion patchset. summary.pl has been written with extending the syntax of @standards in mind, and it should be straightforward to introduce additional checks such as validating the names of standards used in annotations. So, without further ado, here is my @standards proposal. Thank you, Rical Jasan --- Rical Jasan (7): manual: Provide one-off standards conversion script. manual: Create empty placeholder macros for @standards. manual: Fix up invalid header and standards syntax. manual: Refactor errno @comments. manual: Convert @tables of annotated @items to @vtables. manual: Convert header and standards @comments to @standards. manual: Replace summary.awk with summary.pl. manual/Makefile | 7 +- manual/argp.texi | 126 +++----- manual/arith.texi | 789 ++++++++++++++++-------------------------------- manual/charset.texi | 96 ++---- manual/conf.texi | 671 ++++++++++++++--------------------------- manual/convert-stds.pl | 186 ++++++++++++ manual/creature.texi | 45 +-- manual/crypt.texi | 68 ++--- manual/ctype.texi | 116 +++---- manual/debug.texi | 9 +- manual/errno.texi | 802 +++++++++++++++++++------------------------------ manual/filesys.texi | 391 ++++++++---------------- manual/getopt.texi | 24 +- manual/header.texi | 2 +- manual/job.texi | 33 +- manual/lang.texi | 221 +++++--------- manual/llio.texi | 333 +++++++------------- manual/locale.texi | 39 +-- manual/macros.texi | 7 + manual/math.texi | 639 +++++++++++++-------------------------- manual/memory.texi | 152 ++++------ manual/message.texi | 30 +- manual/pattern.texi | 247 ++++++--------- manual/pipe.texi | 16 +- manual/process.texi | 69 ++--- manual/resource.texi | 173 ++++------- manual/search.texi | 45 +-- manual/setjmp.texi | 33 +- manual/signal.texi | 258 ++++++---------- manual/socket.texi | 352 ++++++++-------------- manual/startup.texi | 52 ++-- manual/stdio.texi | 495 ++++++++++-------------------- manual/string.texi | 301 +++++++------------ manual/summary.awk | 133 -------- manual/summary.pl | 423 ++++++++++++++++++++++++++ manual/sysinfo.texi | 77 ++--- manual/syslog.texi | 15 +- manual/terminal.texi | 303 +++++++------------ manual/threads.texi | 18 +- manual/time.texi | 151 ++++------ manual/users.texi | 283 ++++++----------- 41 files changed, 3202 insertions(+), 5028 deletions(-) create mode 100755 manual/convert-stds.pl delete mode 100644 manual/summary.awk create mode 100755 manual/summary.pl -- 2.12.2 --------------2.12.2--