This is the mail archive of the
mailing list for the glibc project.
Re: Consensus on MT-, AS- and AC-Safety docs.
- From: Alexandre Oliva <aoliva at redhat dot com>
- To: "Joseph S. Myers" <joseph at codesourcery dot com>
- Cc: "Carlos O'Donell" <carlos at redhat dot com>, GNU C Library <libc-alpha at sourceware dot org>, Rich Felker <dalias at aerifal dot cx>, Torvald Riegel <triegel at redhat dot com>
- Date: Wed, 20 Nov 2013 05:23:26 -0200
- Subject: Re: Consensus on MT-, AS- and AC-Safety docs.
- Authentication-results: sourceware.org; auth=none
- References: <528A7C8F dot 8060805 at redhat dot com> <Pine dot LNX dot 4 dot 64 dot 1311182312130 dot 8831 at digraph dot polyomino dot org dot uk>
On Nov 18, 2013, "Joseph S. Myers" <firstname.lastname@example.org> wrote:
> it's that it is insufficiently clear at the sites
> where the safety properties are documented that they are only observed
> properties of the current implementation and not necessarily part of the
> glibc API - as far as I can see, someone going straight to the
> documentation for a function would miss the carefully explained caveats.
I'm a bit confused by the statement above.
The latter part talks about the notes attached to individual functions,
whereas the first part seems to be talking about the definitions of the
properties in intro.texi. The definitions are preceded by this caveat:
Although we strive to abide by the standards, in some cases our
implementation is safe even when the standard does not demand safety,
and in other cases our implementation does not meet the standard
safety requirements. At this point, we document the result of an
assessment of the properties of our implementation, so the safety
documentation in this manual is not to be regarded as a promise of
future behavior: in future releases, functions that are documented as
safe may become unsafe, and safety constraints may be removed or
introduced. We envision turning the results of the assessment into a
set of promises as stable as our interfaces, but we are not there yet.
which would presumably alleviate your concerns. As for the latter
concern, the keywords are hardly intuitive, so my expectation is that
people would look them up and find the caveat. Of course, this will
only be the case if the function actually carries any note; if it's all
safe ATM, someone might indeed be misled into believing we promise it's
safe forever, based on the usual meaning of the (MT|AS|AC)-Safe terms
and the expectation that our documentation is binding.
One way that occurs to me to avoid this incorrect assumption is to use
non-standard terms, defined elsewhere in the manual, instead of the
well-known *-Safe terms. We could then set the expectations correctly
in the definition of the terms. E.g., @mtsafe could expand to MT-C (to
be read with a strong Australian accent ;-), and then MT-C could be
defined in intro.texi as MT-Safe with the current implementation, but
subject to change.
As we committed to a safe implementation, we'd use a different macro
that indicated the commitment by expanding to MT-Safe.
It might make sense to rename the current @mtsafe macro to @mtc,
globally, and save @mtsafe for future commit(ment)s ;-)
Then, there's the possibility you suggested, that @safety expands
additional text (maybe an xref to the section that defines the terms).
I think this would clutter the manual too much; it would likely become
background noise. Unless it was a prefix such as | MTASC-Unstable |,
while @apisafety would turn that into | MTASC-API | or nothing.
It might be even nicer if the keywords and the *Safe terms themselves
could be made active links to their definitions, but I don't think this
can be done in texinfo. I'd love to be proven wrong. Anyone?
Alexandre Oliva, freedom fighter http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/ FSF Latin America board member
Free Software Evangelist Red Hat Brazil Compiler Engineer