Re: The future of the manual (was Re: [PATCH] Add getcpu)

[Florian Weimer <fweimer at redhat dot com>]

* Zack Weinberg:

> I get the impression that Florian either believes that the existing
> manual is no longer useful, or has some kind of principled objection
> to adding new material to it.  Either would be reason to open a
> new_discussion about changing this rule.
>
> Florian, would you mind, at your convenience, explaining why you do
> not want to add new material to the manual?

First of all, from my perspective, it's not about Texinfo at all.  I
actually prefer Texinfo to quite a few of the documentation markup
languages out there.

Visibility of the manual is poor compared to the man-pages project.
Academic citations are far fewer than for man7.org.  I don't know why
this is.

Debian only ships a very old version of the manual, in the non-free
section, so Debian users have to rely on the web version.

I recently discovered ‘C-h S sprintf RET’ in Emacs, which takes you
directly to the documentation of the printf function, similar to ‘M-x
man RET sprintf RET’.  But the manual is structured poorly to support
this kind of usage.  For example, the subsection about sprintf does not
give you a link to the format strings accepted by sprintf.

All in all, it makes me feel that the manual is for a really small
audience, which makes work on it not very satisfying.  I think we should
rather contribute to the man7.org manual pages and make sure that the
information found there is up to our standards.

And of course, the GFDL is problematic (it's the reason why Debian
doesn't ship the manual, and why we can't add Javascript code to improve
the web version, similar to what OpenJDK did), and so is the
U.S. regulatory notice.  I feel someone needs to make a stand here,
otherwise things will never change.

I had a lengthy chat about this with Carlos yesterday, and my position
has mellowed somewhat.  But I still find the situation frustrating.

Thanks,
Florian