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

[Rical Jasan <ricaljasan at pacific dot net>]

On 04/04/2017 04:26 AM, Joseph Myers wrote:
> On Tue, 4 Apr 2017, Rical Jasan wrote:
>> 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.
> 
> Respecting the locale is a simple bug; LC_ALL=C should be used in the 
> makefile when running anything that does sorting etc. as part of the build 
> process (as it already is in many places).

But I like case insensitive sorting and expect exit, _Exit, and _exit to
all be together in my manual.  :P  Anyway, "fixed" locally.

Wrt. the patchset outline, how much of that would you like to see in v3?

If I don't also supply the completion patches, I'll leave out the
checking/enforcing bits in summary.pl to avoid breaking the build.
There would then be significantly less to review, and the new content
for completing the @standards can be a follow-up in a separate patchset.

If you think the proposed syntax is acceptable, I'll also need to make a
few tweaks to what I currently have, mostly so the conversion script
doesn't use @comma{} for multiple standards or headers.  I didn't begin
addressing special cases until the bulk of the conversion was already in
place, to see how it all panned out.

The syntax I'm proposing at this point looks like:

  @item FOO
  @standards{STD, HDR}

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

  @item BAR
  @standards{STD1, HDR1}
  @standards{STD2, HDR2}

I believe that cleanly addresses both the generation of summary.texi and
the eventual rendering we'd like to have.  It does not address
canonicalization of standards names (which could be enforced later in
summary.pl), or whether or how to combine standards, those issues being
in a different scope.  Since the conversion creates the @standards from
the @comments used by summary.awk and @standards aren't rendered yet,
the status quo is maintained in that regard.

The headers and standards are essentially rendered as-is in the Summary,
with headers being wrapped in @file{}.  The Summary entries are as-is as
well, whether macros, variables, function prototypes, or what-have-you.
The entries are all @items in a @table that uses @code.

If we use the proposed syntax, there is also a choice of whether to
change the Summary accordingly, or do any extra work to keep it the
same.  Consider the following entry:

  @comment crypt
  @item char * crypt (const char *@var{key}, const char *@var{salt})

  @file{crypt.h} (BSD, SVID):  @ref{crypt}.

If we have in the manual:

  @item char * crypt (const char *@var{key}, const char *@var{salt})
  @standards{BSD, crypt.h}
  @standards{SVID, crypt.h}

The entry in summary.texi could become:

  @comment crypt
  @item char * crypt (const char *@var{key}, const char *@var{salt})

  @file{crypt.h} (BSD):  @ref{crypt}.

  @file{crypt.h} (SVID):  @ref{crypt}.

Currently, there is only a single line for every entry, so that also
changes the status quo for summary.texi, similar to ignoring locale.
This change is probably desirable, since it represents the same issue of
correlation we're trying to solve by allowing multiple @standards to
annotate a single element.  I suppose the downside is that it's a little
more verbose, but this is a reference manual.

Rical