How would we make linux man pages authoritative?

[Joseph Myers]

On Fri, 22 May 2020, Carlos O'Donell via Libc-alpha wrote:

> * The C libraries have as a goal to update the API documentation in
>   the linux man page as the authoritative source of the API reference
>   and make it part of their submission process. Yes, this involves
>   committing across two projects, and some good coordination.

I don't think we should have any such expectation.

Just as for any other project, glibc should provide user documentation for 
its APIs that describes the intent of those APIs in that version of glibc, 
tagged and branched along with the corresponding sources and updated when 
those sources change.  Other projects are welcome to document those APIs 
as well if they so wish.

man pages are explicitly secondary in the GNU project.

> The glibc project retains a manual as a task-oriented guide which

"In general, a GNU manual should serve both as tutorial and reference."

> I'm trying to think of a beautiful future. If you think this future
> is ugly, please tell me so, and suggest something else :-)

Some system for automatically extracting API information from the glibc 
manual and generating man pages from it, for people who want documentation 
in that form?  I don't know if it's practical, and I'd tend to think of 
other things relating to automated processing of API information as more 
worthwhile (e.g. automatic checks that standards / feature test macros 
information in the manual agrees with the conditions on APIs in the 
headers, automatic listing of undocumented APIs with test failures when 
new ones are added outside of known whitelisted groups of APIs), but it's 
not obviously ridiculous.

-- 
Joseph S. Myers
joseph@codesourcery.com