Standards References

[Carlos O'Donell]

On 10/14/2016 05:33 AM, Rical Jasan wrote:
> On 10/13/2016 11:32 PM, Carlos O'Donell wrote:
>> On 10/14/2016 01:22 AM, Rical Jasan wrote:
> To start fleshing out 1b below, would you want to use those names, or
> names from feature_test_macros(7), or both?  I think I would lean
> towards correlating the two, so rendered names might be more friendly
> like standards(7), but were connected to the names in
> feature_test_macros(7), allowing us to eventually say things like, "foo
> is standardized by Nicely Formatted Standard Name, and made available
> whenever _NFSN is defined.", or however we agree on the rendering.

I would also lean towards correlating the two.

It also does us a big disservice if we deviate from the linux man pages
project in this regard, and we should endeavour to harmonize what we can
between the glibc manual and that project.

I routinely get things committed to linux man pages and Michael is a very
quick reviewer (unlike myself :-}).

>> And enforce that all functions need a standard reference.
> 
> Good point.  For the record, I tend to use "function" as a catch-all for
> functions, data types (e.g., structs), macros, and anything else
> documented by the manual, so I consider this work to apply to all those
> things.

Agreed, that's what I assumed.
 
> Even if the licensing issue you mention below is a problem for
> src-to-doc automation, being able to say @gnuext{} (for example), like
> @theglibc{}, instead of writing a free-form sentence or paragraph to the
> same effect, will go a long way in making the documentation both more
> consistent and easier to write and maintain.

Agreed.

>> One thing to note is that there is a difference between 'the name of
>> the function comes from standard X' and 'the function implements what
>> standard X says it does', and these two don't always match. Like the
>> POSIX scheduling functions do not do what POSIX says they do, instead
>> they match more closely what Linux does. So it's not entirely clear
>> if those functions are buggy, should get fixed to comply, or should
>> not be defined if you're goal is to use only functions from a given
>> standard.
> 
> Interesting.  Is there precedence within the feature test macros, where
> the Linux standard supersedes POSIX, or vice versa, or is it possible to
> dictate that behaviour?  This seems orthogonal, like a question that
> should be answered in the implementation/headers, ultimately.  If that
> conflict already exists in practice, do you consider it buggy, broken,
> or worth omitting?  I imagine we could devise a syntax for such cases,
> though.

There is no precedence for this level of detail. You simply have to know
that the function in question doesn't implement the POSIX semantics and
live with it. It's a terrible situation.

There are a least 3 or 4 interfaces that don't match that I'm aware of,
and some have to do with thread scheduling and priority. A detailed look
in bugzilla should reveal them, I'll see if I can dig them up.

> Referring back to _NFSN/Nice Name above, but also keeping the stepwise
> progress in mind, I envision the initial macros to be fairly simple,
> like @stdfn{...} rendering as, "This function is defined by ...", which
> should make extending the framework into a more complicated scheme
> easier than it would be as things stand now, which meets the goals of
> always improving the current mess and making it easier to do better later.

Certainly. It's easier to automate processing some kind of macro than
English prose.
 
> If precedence was definite, something like @stdfn{POSIX, Linux} could
> render as, "This function is defined by POSIX, but implemented
> differently by Linux.", and maybe @stdfn{POSIX, Linux} and @stdfn{Linux,
> POSIX} would render differently.  That might not work as nicely with
> multiple, but equal, standards, though.  Like if we ever got to the
> point of, "This function was originally defined as a GNU extension, but
> standardized in POSIX.2." (which happens).

I think about first order importance. That is usually: Where is the does the
definition of the function come from and does it conform?

>>> Well, that's enough for now.  Thank you for your time.
>>
>> A final note about copyright and licensing. The manual is GFDL and the
>> source code is GPLv2, so you cannot copy any legally significant text
>> from one to the other without relicensing permission by the FSF.
> 
> When I do cull my knowledge from the sources, I don't copy/paste
> anything.  If I can't restate it in a meaningful way from my own
> understanding, I don't think I should writing the documentation for it
> anyway.  But thank you for making that explicit, as I wouldn't have been
> aware otherwise.

Thank you for your consideration.

> Should I avoid reading man pages for functions that aren't documented in
> the glibc manual but that I intend on documenting because they are
> present in the source, but absent from the manual?

IANAL.

Avoid reading what you can and write what you know.

> What about other forms of documentation, like tutorials or forums?

Worse. At least Michael has documentation about who contributed the material
and under what license, so in the event of a conflict we might rewrite it or
ask the original author to dual license.

Alex and I dual licensed the safety notes, once for glibc and once for the
man pages.

>> I believe that Joseph Myers has such an authority in GCC to do just that,
>> but we don't in glibc. It would be required if we had some closer source
>> to manual integration. We would need someone who was blessed to legally
>> run a script to update the manual from the source or vice-versa.
> 
> Crazy.  I was reading the GnuTLS manual the other day, and was having a
> helluva time finding where they documented their functions (they
> conveniently include prototypes wherever references are needed)---lo and
> behold, all they did was include some kind of magical reference to
> "include the prototype for this function here", and everywhere that
> happened, the source of the rendered text came from the source-level
> comments of the function itself.  I couldn't believe it.  They
> documented the function /in the source code/, and the generated
> documentation was based purely on that, no matter where or how many
> times it occurred within their manual.

I admire your enthusiasm for the problem :-)

> I really don't care that glibc does it differently and I'm more than
> happy to help improve things here, but I figured the infrastructures
> were just so different it was too much work to do it like that.  If I'm
> understanding you correctly, we actually can't legally synchronize our
> source code and documentation (without approval and a designated agent)?

Correct. The legal impediment is not terrible, just a step in the process
that would have to be setup. The technology to automate it could be done,
as is done in gcc, but someone has to turn the crank and be authorized,
probably a steward (GNU maintainer) at each release.

> FWIW, converting the entirety of glibc to be self-documenting from its
> own source code is not something that sounds fun.

I don't know. It has a finality to it that has it's own charms.

> So not fun, I probably couldn't resist doing it anyway...  It's hard to
> turn down a challenge.

Agreed.

>> Technically I think we violate this with the errno list generation scripts
>> we have that integrate with the manual, but perhaps we can call that
>> "not legally significant."
> 
> Oh good, we have loopholes.  :)

Right, so the API descriptions might not be legally significant, but textual
descriptions of them probably are.

-- 
Cheers,
Carlos.