This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[PATCH v3 0/7] manual: Header & Standards Cleanup


This is a multi-part message in MIME format.
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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]