20 Sep
2017
20 Sep
'17
7:02 a.m.
On Tue, Sep 19, 2017 at 05:47:42PM -0700, Lyndon Nerenberg wrote:
+1. Man pages should be short things that remind you how to run the program.
Putting a user guide in man pages is nuts, and in today's world texinfo is
just as nuts. Put it on the web and move on. But don't give me the see
texinfo man page, I hate that crap.
On Sep 19, 2017, at 4:35 PM, Theodore Ts'o
<tytso(a)mit.edu> wrote:
If you take a look at how perl handles its man pages, with 188 man
pages in section 1:
... you quickly recognize the difference between a manpage (i.e. reference page) and a
user manual. Perl's (and other's) attempts to pack a 200 page user guide into a
block of manpages is a misuse of what manpages represent.
texinfo was a good move in the direction towards online, cross-referenced, user
documentation. But so often that lead to manpages that consisted of the single line
"see the texinfo doc"; the documentation authors completely missing the point.