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

[Alexandre Oliva <aoliva at redhat dot com>]

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

> On Thu, 21 Nov 2013, Alexandre Oliva wrote:
>> 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

> I think we should generally go for longer text that makes sense on its own 
> rather than non-English keywords.  (Although having a cross-reference to 
> the detailed definitions *also* makes sense.)

These come across as contradictory requirements.

If keywords make sense on their own, readers won't look up their
detailed definitions, and miss out on the details you regard as
essential for them to be aware of.

You can't have it both ways, unless the longer text is the detailed
definition itself.  Which, if you ask me, would be a bit excessive, to
put it mildly ;-)


Could you pretty please :-) come to an agreement with yourself :-) in
this regard (you too, Torvald :-) before I get myself into a wild goose
chase trying to address conflicting requirements?  (I'm not mad or
annoyed by them, thus the many smileys, it's just that pulling me in one
direction and its opposite won't help us make progress ;-)



ATM I'm leaning towards turning the keywords into macros that expand to
whatever we agree upon when we do.  Should we stick to the short
mnemonic-but-nonsensical-on-their-own keywords, it might make sense to
document what they stand for, as in, what their spelling meant to bring
to mind, not the more formal definition.

E.g., envromt is not just a shorthand for environment, it's actually
environment-[is]-read-only-[if]-multi-thread;
asynconsist's mnemonic is not just async-inconsist, it's
async-signal-[may-get]-inconsistent-[data], incansist's is
[may-leave-data-in]-inconsistent-[state-if]-cancelled-asynchronously.

Although we could use these longer expansions in texinfo-compiled
versions of the manual, I'm concerned it will be quite inconvenient to
have to scroll down a full page between the prototype of some functions
and the description of their behavior.  This is unfortunately *not* an
exaggeration.

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