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

[Alexandre Oliva <aoliva at redhat dot com>]

On Nov 20, 2013, "Joseph S. Myers" <joseph@codesourcery.com> wrote:

> (I'd also say that the stable API case should be the case that's concise 
> in the Texinfo source as well as in the formatted manual - say @safety for 
> stable API cases, @currentimplementationsafety for observed properties of 
> the current implementation that may not reflect intent.)

I sort of liked Torvald's idea of adding the Preliminary word to the
notes I've added so far.  I could go for something like

@safety{@prelim{}@mt...}
or
@prelimsafety{@mt...}

Any preferences?

These would, in either case, expand to:

Preliminary: | MT-... |...

Or maybe we could use some other non-English keyword that users would
look up (say NanAPIp, for Not an API promise, or FS-Unsafe, standing for
Future Stability Unsafe :-), or make it a âSee alsoâ trailer (this would
be much noisier IMHO).


Another possibility is for @mtsafe{} to expand to e.g. MTS* (with the
*), and when we make it part of the stable API, we switch to a shorter
macro, say @mts{}, that drops the *.  That's a bit subtle, but the fact
that we'd not be using such well-known terms as MT-Safe would direct
users towards looking them up, and there we'd explicitly state the
distinction the star stands for.

> Only when a sufficent part of that is present at the sites of individual 
> function documentation, so that someone doing "info <function>" sees the 
> prominent note about how the documentation is something different from 
> normal documentation of a stable API.

I was hoping the non-English keywords would address that: when first
encountering them, users would have to look them up, and then they'd
find the caveat documentation.

-- 
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