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>, Torvald Riegel <triegel at redhat 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>
- Date: Fri, 22 Nov 2013 03:04:44 -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> <orob5fv8nl dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311201555320 dot 28804 at digraph dot polyomino dot org dot uk> <orli0itbm5 dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311211322040 dot 14539 at digraph dot polyomino dot org dot uk>
On Nov 21, 2013, "Joseph S. Myers" <firstname.lastname@example.org> 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
asynconsist's mnemonic is not just async-inconsist, it's
async-signal-[may-get]-inconsistent-[data], incansist's is
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
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