Re: [RFC] Canonical Standards Names

[Rical Jasan <ricaljasan at pacific dot net>]

On 06/20/2017 06:55 AM, Joseph Myers wrote:
> A key thing to sort out is to what extent the @standards information 
> should include information about function origins, e.g. BSD, beyond the 
> information about which formal standards, corresponding to feature test 
> macros supported in glibc, have a given function or other feature.

I think it would be pushing @standards a little far to try and use it to
document history.  Texinfo macros are pretty limited, and I worry about
the real estate when we get around to rendering.

In the case of multiple standards/headers, there are some existing examples:

  @deftypefun {char *} ecvt ...
  @standards{SVID, stdlib.h}
  @standards{Unix98, stdlib.h}

I'm not sure if that's what you're getting at, but I would contrast that
with the pending CHAR_BIT patch [1]:

  @deftypevr Macro int CHAR_BIT
  @standards{C90, limits.h}
  ... POSIX.1-2008 requires this to be 8.

which, with more exhaustive @standards might be:

  @deftypevr Macro int CHAR_BIT
  @standards{C90, limits.h}
  @standards{POSIX.1-2001, limits.h}

but would still require clarification in the description to provide any
real explanation of origins and evolution.  I don't think @standards is
a substitute for that sort of textual context; however, it serves the
purpose of formalizing succinct annotations used by automated processes
for generating the manual rather well (better than @comments, at least).

With the exhaustive approach, one would see all the annotations in the
Summary, and at least know any relevant standards at a glance.  I would
expect the link to the description to be followed for more information.


Another related issue to address is when standards conflict, or have
some sort of interdependency.  There are at least a handful where the
feature test macros imply something like:

  @item YESSTR
  @standards{GNU || (XOPEN && !POSIX.1-2001), langinfo.h}

Whether there is a better way to express that, others will have to
evaluate.  Even if we took the more "exhaustive" approach above, I think
we'd still have to at least allow for the negation syntax:

  @item YESSTR
  @standards{GNU , langinfo.h}
  @standards{XOPEN , langinfo.h}
  @standards{!POSIX.1-2001 , langinfo.h}

and the description would definitely need to expound upon that, as the
relationship is not nearly as clear.  With that in mind, the combined
syntax might be more intuitive/insightful, and easier to explain.


While discussing syntax options, which I'm glad this opened up, I don't
want to lose sight of the purpose of my initial post, which was to
obtain a working list of standards names to use while completing
@standards, which should be independent of the syntax (but does all need
to be addressed before we move too far forward).


Whenever the standards names come up you seem to go to the syntax
issues, though.  Are you thinking of different sets of "canonical"
standards that we might use for different purposes?  I was wondering if
there were certain forms that might be tied more closely to (when we're
talking about) feature test macros, and others that might be preferred
when we're referring to a standard's publication, for example.  The
"standards" are known by so many names, and sometimes the most explicit
or definitive reference to the standards document itself may not be the
most succinct (if we're concerned with screen real estate) or widely
recognized.


Rical


[1] https://sourceware.org/ml/libc-alpha/2017-06/msg00915.html