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

[Alexandre Oliva <aoliva at redhat dot com>]

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

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

> For conscientious readers, we need to include the link to make it easy for 
> them to look up the documentation.

âNeed toâ is too strong; it's surely convenient.  But there are some
texinfo macro challenges to solve to make this work; more on that below.

> For unconscientious readers, there's only so much we can do.

Well, there is: we could use terms that do *not* immediately suggest an
interpretation that might be incomplete or wrong, so that they'd have no
choice but to actually look it up if they want to know what it means.

But, well, since it's not the first time I make this point and you
dismiss it,, you clearly don't want to induce people to look up and read
the details whose inclusion you asked for and argued it was important
for them to know.  Can you explain this contradiction and why it's more
important for the manual to use terms you like than to get people to
look up the terms to find out the details you yourself considered
essential?!?

>> -- Function: void setpwent (void)
>> | MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,

> static-buffer (there's no need to make them complete phrases as long as 
> the words are complete words or well-established abbreviations, but they 
> shouldn't be glibc-specific abbreviations or run multiple words together 
> with possible overlap).

So far the only argument I've seen to support the requirements above is
âI like it better this wayâ, without any regard or even acknowledgement
to the functional advantage of the opposite.

Considering that such complete words with well-known meanings risk being
far more misleading than helpful, because they only bring a small part
of the problem to mind, I'm still not convinced that's the way to go.

I'll say that the ones you proposed do not *look* so awful as did the
ridiculously long ones I proposed so as to satisfy the requirements you
posted at first.  However, now that you've shown you're willing to
sacrifice precision to get brevity back, I must ask why not have both.

> Documenting limitations of safety only makes sense if we wish to support 
> use of the function in a particular context provided the user follows 
> particular rules.  In this case, and probably many cases for AS-Safety, I 
> think we should just say AS-Unsafe - we don't want to support this in 
> signal handlers at all, under any circumstances, and so don't need to 
> document anything about what makes it unsafe, just that it is unsafe.

Torvald values the annotations that justify (for internal consumers, not
in the formatted manual) why a function is AS-Unsafe or AC-Unsafe, as I
do.  Using macros for them that expand to nothing is fine, but what
about the documentation that currently defines them?  Should it be
removed altogether, or turned into comments?

> data-structures-inconsistent (except I'd think that is a sufficiently 
> fatal problem that the function should just be documented as 
> unconditionally AC-Unsafe

The point is to document why it is unsafe.

> (Again, this is in the AC-Unsafe context, so don't need to mention 
> asynchronous-cancellation in the keywords themselves.)

The *definitions* of the keywords are not divided in sections, because
some keywords apply to more than one section.  Since there's a single
namespace for the definitions, in cases in which the distinction is
significant, it becomes necessary to have different keywords, and then
I've resorted to bringing the context into the keyword name.


Now, on to the problem of macro expansion...

Currently, we have @safety, and @(mt|as|ac)(un)?safe, and each of them
just expands their single argument within their expansion; if their
single argument encompasses multiple keywords, they're explicitly
separated by commas and blanks, and things work just fine.

If we transition to each keyword being a macro, some of which may or may
not expand to an empty string, the commas and blanks won't look right.

Furthermore, if we're to link to the section that defines the macros,
the @safety macro would need some way to tell that at least one of the
keyword macros mentioned in arguments to its arguments expanded to a
non-empty string in order to determine whether to expand the xref.  I'm
not sure this is possible in texinfo, and it doesn't make sense to add
the xrefs manually if the macros themselves may come and go.

What now?

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