[PATCH v2 3/5] manual: Add new header and standards annotations.

[Rical Jasan]

Alright, it's time for an update and to request some direction.

I currently have a patchset that looks like:

  1) Introduce the conversion script.
  2) Create the @standards* macros.
  3) Perform some pre-conversion cleanup.
  4) Convert header and standards @comments to @standards.
  5) Replace summary.awk with summary.pl.
  6) Introduce a @standards-checking script.
  ...) Per-file commits completing @standards.
  N) Remove the conversion script.

I plan on folding the syntax-checking into summary.pl; they're separate
right now for workflow reasons.  Similarly, the conversion script can be
removed anytime after the conversion patch, but I leave it in because
it's nice to have in the working tree for reference.

As of (5), there is a near 1:1 conversion from @comment-based
annotations to @standards.  "Near", because summary.awk didn't always
get everything right.  The significant difference in summary.texi is how
missing headers or standards are rendered, now being @emph{no header} or
"???", respectively.  Some @ref nodes are correctly reported where they
were not before.  Some ordering differences are present, due to the way
the files are parsed and entries stored.  Note that the locale is
respected, so different users may have differently-ordered Summary
chapters, but summary.awk appears to have done this as well.

For the @standards macros, I've created both @standards{STD, HDR} and
@standardsx{foo, STD, HDR}.  The proposed usage is:

  @item FOO
  @standards{STD, HDR}

  @deftypefun foo
  @deftypefunx fool
  @standardsx{foo, STD, HDR}
  @standardsx{fool, STD, HDR}

  @item SEEK_SET
  @standards{C90, stdio.h}
  @standards{POSIX.1, unistd.h}
  @standards{XOPEN || POSIX.1-2008, fcntl.h}

I'm not particularly concerned with addressing the logical combinations
of standards, or canonicalizing standards names at this time.  The
@standards* macros in macros.texi are empty placeholders, so there is
plenty of time to work out the details before we flip the rendering
switch.  They'll simply look like they always have in the Summary in the
meantime.

I use the SEEK_SET example to show one possible way of dealing with
multiple headers and standards.  Note that @standardsx is used for all
elements in @*x chains, including the first non-@*x element.  What
differentiates it is the inclusion of the annotated element's name,
necessary to distinguish the elements in lists using @*x-commands.

The conversion script is written to be 1:1 with summary.awk, so multiple
header and standard annotations aren't created according to the SEEK_SET
example above.  Instead, @comma{} is used:

  @item SEEK_SET
  @standards{C90@comma{} POSIX.1@comma{} XOPEN || POSIX.1-2008, \
             stdio.h@comma{} unistd.h@comma{} fcntl.h}

It's messier, but easily identified and converted later.

My question at this point is whether I should submit (1-5,N) to get the
@standards conversion over with, while more-or-less maintaining the
status quo, or if I should not worry about maintaining that and take it
a couple steps further.  I could submit the first patchset with (1-5,N)
as-is, with some additional patches to convert @comma{}s to multiple
@standards, and add in enforcing along with the completion patches, but
I think that last bit was intended to happen in a separate patchset.

With the conversion to @standards, it becomes much easier to work on all
this; now we can `grep ^@standards', whereas it's anybody's guess which
@comments held standards or headers before, so let me know what you'd
like most to see.

Thank you,
Rical