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

[Alexandre Oliva <aoliva at redhat dot com>]

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?

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, 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?!?


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.  They're
English and imprecise, as you prefer, and they're even shorter, as I
prefer.

Current         Proposed
staticbuf       race
lockleak        lock
selfdeadlock    lock
asynconsist     corrupt
incansist       corrupt
asmalloc        malloc
asi18n          i18n
shlimb          dlopen
uplugin         plugin
oncesafe        init
1stcall         init
uunguard        const
xguargs         race
tempchwd        cwd
tempsig         sig
tempterm        term
stimer          timer
glocale         locale
envromt         env
fdleak          fd
memleak         leak
unposix         posix

Can we all agree on these?

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