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

[Torvald Riegel <triegel at redhat dot com>]

On Mon, 2013-11-25 at 17:34 -0200, Alexandre Oliva wrote:
> On Nov 25, 2013, "Joseph S. Myers" <joseph@codesourcery.com> wrote:
> 
> > On Sat, 23 Nov 2013, Alexandre Oliva wrote:
> >> There's a linguistics argument to be made here.
> 
> > I think the linguistics can go just as much the other way - people read 
> > text in much larger blocks than individual letters or syllables, and so 
> > code-words that aren't made of normal English words or conventional 
> > abbreviations in meaningful sequence, properly separated rather than run 
> > together, seriously disrupt readability and are quite likely to be 
> > ignored, or treated as spelling errors ("incansist" suggests "the writer 
> > doesn't know how to spell 'inconsistent'" more than it suggests "this is a 
> > technical term with a special glibc-local definition").
> 
> >> Someone who's reading the manual is there to learn something; they're
> >> learning not just definitions, but a language.  After all, cryptic
> 
> > They're learning the use of glibc functions
> 
> and types and macros and variables.
> 
> Do I really have to point out that the names of these objects we
> document are also made up terms, code-words that aren't made of normal
> English words: malloc, setpwent, popen, mcheck, getopt, argp_parse,
> mallinfo, catget, dcgettext, iswalnum, dlsym, mempcpy, wcstok,
> argz_add_sep, fcntl, cbrtl, lcong48, DTTOIF, ftw, memalign...  Do I need
> to go on to show how much of a double-standard your argument is based
> on?

It's not a double-standard if we try to make things better in areas in
which can do things differently (e.g., new terms for MT-Safety).

That we have this other kind of naming on different entities in a
different context (ie, one are function names, other are terms used in
documentation) doesn't mean that we always need to follow this approach,
nor that this other naming is actually good.

> The manual provides definitions for all of these non-English, made-up
> terms.  You can't even argue that all of them are external standards
> imposed on us, because a number of the functions I mentioned are glibc
> originals!
> 
> >> *expect* to and *want* to deal with that; they're reading the manual
> >> precisely because they want to learn what those new words mean.
> 
> > No, they want to learn how to use glibc functions.
> 
> Exactly!  They want to learn *exactly* what those odd combinations of
> letters mean!  Somehow when it's a function name among other made-up
> terms from C, that's perfectly readable,

Why do you think those are perfectly readable?

> but when it's a one-line table
> among other equally made up terms, then it can't work, and you're
> willing to sacrifice precision to avoid using them?!?

We are not sacrificing precision.  Even your made-up names aren't
self-contained definitions, and you still need to read the definition,
so where is the lack of precision?

> As a last attempt to come to an agreement, before I decide we're at an
> impasse, here's a list of keywords I'd be willing to adopt.

(I don't think an ultimatum is a good end to a discussion.  Did others
choose this option?)

> They're
> English and imprecise, as you prefer, and they're even shorter, as I
> prefer.

Are these the keywords shown to the user, or the keywords used
internally?

> Current         Proposed
> staticbuf       race

I'd prefer datarace for this.

> lockleak        lock
> selfdeadlock    lock

Merging these two seems fine from a user POV (but see further comments
below).

> asynconsist     corrupt
> incansist       corrupt

Do we have a better word for these inconsistencies?  Or just
"inconsistent" perhaps?  "corrupt" seems pretty generally applicable --
a bit like "water" :)

> asmalloc        malloc
> asi18n          i18n

Given that they will be used in the AS context, I suppose that's fine.

> shlimb          dlopen
> uplugin         plugin

No opinion so far.

> oncesafe        init
> 1stcall         init

Might be fine from a user POV (but see below).

> uunguard        const
> xguargs         race
> tempchwd        cwd
> tempsig         sig
> tempterm        term
> stimer          timer
> glocale         locale

No opinion so far (I wanted to reply quickly to the other points).

> envromt         env

Out of curiosity, why not "environment"?  Was that just to save a few
characters?

> fdleak          fd
> memleak         leak

I don't quite understand the reasons behind the renaming for these two.
If both are leaks, why not keep fdleak and memleak?

> unposix         posix
> 
> Can we all agree on these?

I think it would be unfortunate to loose some of the insight you have
been gathering (eg, loose the distinction between self-deadlock and
potentially missing lock releases).  OTOH, Joseph's comment that we only
need to use categories that the user can deal with also makes sense to
me.  Thus, can we keep the insights documented in detail, and show the
users only a reduced set of annotations (e.g., with some annotations
merged into one class as in your mapping)?