This is the mail archive of the libc-alpha@sourceware.org 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 22, 2013, "Joseph S. Myers" <joseph@codesourcery.com> wrote:

> On Fri, 22 Nov 2013, Alexandre Oliva wrote:
>> > 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.

> I'd like extended names, which are links to their definitions.

Do you acknowledge that this will not get users to follow the links so
as to look at the precise definitions?

> In the absence of being able to do that in Texinfo, follow the list of
> keywords (which should still be extended names) with something like
> "See [ref] for detailed definitions.".

Do you acknowledge that this will make some parts of the manual, such as
users.texi, nearly unusable, because of the amount of noise you're
forcing into them?

Please confirm you hate our users so much ;-) that you want to impose
the following abomination on them.  Can you even find the original
documentation in this horribly noisy haystack?  Do you realize this
wouldn't even be the worst part of the manual in this regard? :-(

 -- Function: void setpwent (void)
     | MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
     may-read-from-the-global-locale-object || AS-Unsafe
     calls-the-dynamic-loader,
     calls-functions-from-plugins-external-to-libc,
     calls-memory-allocation-functions,
     may-deadlock-with-itself-in-asynchronous-signal-handlers
     || AC-Unsafe
     may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously, 
     may-leave-locks-held-if-cancelled-asynchronously,
     may-leak-file-descriptors-upon-asynchronous-cancellation,
     may-leak-memory-upon-asynchronous-cancellation |
     For detailed definitions, see also *note Safety Keywords::.

     This function initializes a stream which `getpwent' and
     `getpwent_r' use to read the user database.

 -- Function: struct passwd * getpwent (void)
     | MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
     may-read-from-the-global-locale-object || AS-Unsafe
     calls-the-dynamic-loader,
     calls-functions-from-plugins-external-to-libc,
     calls-memory-allocation-functions,
     may-deadlock-with-itself-in-asynchronous-signal-handlers
     || AC-Unsafe
     may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously, 
     may-leave-locks-held-if-cancelled-asynchronously,
     may-leak-file-descriptors-upon-asynchronous-cancellation,
     may-leak-memory-upon-asynchronous-cancellation |
     For detailed definitions, see also *note Safety Keywords::.

     The `getpwent' function reads the next entry from the stream
     initialized by `setpwent'.  It returns a pointer to the entry.  The
     structure is statically allocated and is rewritten on subsequent
     calls to `getpwent'.  You must copy the contents of the structure
     if you wish to save the information.

     A null pointer is returned when no more entries are available.

 -- Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER,
          size_t BUFLEN, struct passwd **RESULT)
     | MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
     may-read-from-the-global-locale-object || AS-Unsafe
     calls-the-dynamic-loader,
     calls-functions-from-plugins-external-to-libc,
     calls-memory-allocation-functions,
     may-deadlock-with-itself-in-asynchronous-signal-handlers
     || AC-Unsafe
     may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously, 
     may-leave-locks-held-if-cancelled-asynchronously,
     may-leak-file-descriptors-upon-asynchronous-cancellation,
     may-leak-memory-upon-asynchronous-cancellation |
     For detailed definitions, see also *note Safety Keywords::.

     This function is similar to `getpwent' in that it returns the next
     entry from the stream initialized by `setpwent'.  Like
     `fgetpwent_r', it uses the user-supplied buffers in RESULT_BUF and
     BUFFER to return the information requested.

     The return values are the same as for `fgetpwent_r'.


 -- Function: void endpwent (void)
     | MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
     may-read-from-the-global-locale-object || AS-Unsafe
     calls-the-dynamic-loader,
     calls-functions-from-plugins-external-to-libc,
     calls-memory-allocation-functions,
     may-deadlock-with-itself-in-asynchronous-signal-handlers
     || AC-Unsafe
     may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously, 
     may-leave-locks-held-if-cancelled-asynchronously,
     may-leak-file-descriptors-upon-asynchronous-cancellation,
     may-leak-memory-upon-asynchronous-cancellation |
     For detailed definitions, see also *note Safety Keywords::.

     This function closes the internal stream used by `getpwent' or
     `getpwent_r'.


Would you mind if I introduced the short names as macros that expanded
to themselves, and so that you could then turn them into this mess, so
that I don't have my name associated with it?  Yeah, I really feel that
strongly about how horrible the above looks.  I can only imagine you
didn't think it through, but if you like the way that looks, we'll have
to agree to disagree.

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


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