This is the mail archive of the mailing list for the glibc project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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

On Nov 20, 2013, "Joseph S. Myers" <> 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


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
You must be the change you wish to see in the world. -- Gandhi
Be Free! --   FSF Latin America board member
Free Software Evangelist      Red Hat Brazil Compiler Engineer

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]