Re: Consensus on MT-, AS- and AC-Safety docs.

[Alexandre Oliva <aoliva at redhat dot com>]

On Nov 18, 2013, "Joseph S. Myers" <joseph@codesourcery.com> 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