[TUHS] man-page style

[Theodore Y. Ts'o]

On Mon, Nov 19, 2018 at 01:40:43PM -0500, Clem Cole wrote:
> As is often in these disagreements, I suspect agree more than disagree.
> But some of the absolute edges/where you start or stop is where we pick
> different things.
> 
> > For what it's worth, that's a Debian packaging standard.  All
> > executables are supposed to have a man page.
> 
> Right, thank you and I applaud them for that...   As you and others have
> pointed out, Debian != Gnu

Well, technically Debian's Linux is named "Debian GNU/Linux".  It's
not recognized by the FSF as free (Debian cares about allowing users
to have Laptops which aren't paperweights, even if it does mean making
available firmware for which source is not available), so they
recommend distributions such as gNewSense, which is a Debian-based
fork that is now inactive.

Personally, I find debates about whether or not Debian != GNU to be
much like the bickering between the Judean People's Front versus
People's Front of Judea, the latter of which sends a crack squad to
commit mass suicide at the end of the movie "Life of Brian".  :-)

Unless the claim is the only thing which is GNU is HURD?

> > In some cases it may be
> > no more than a short summary of the options and then a reference to
> > the info manual if you want to learn more.
> 
> I think that's somewhat backwards in he spirit of 'UNIX'...  the man and
> info pages should reference the manual in /usr/doc/foo/
> I think the question really comes to what we see 'info' as.    It >>seems<<
> to me that you look at info as the 'manual' for the program which many of
> us do not; to me info, like man is a quick reference.

The info pages are *in* /usr/share/doc/... on a Debian system.  And if
you were to take a look at the info files for, say, GNU Make, it very
much is a full manual.

Note: In Debian, "info make" will show the man page if you don't have
the info pages installed, which are part of the make-doc package.
Perhaps this is why you think info is a quick reference?

> Ah, I think this is were you not hearing what I'm saying...   the 'primary
> manual' as you call it is the document in /usr/doc/make in this case.  But
> [as others have pointed out, writing that >well<< can be hard]. FWIW:
> Feldman's description of make in /usr/doc of Seventh Edition pales compared
> to Steve Talbots - but Talbiot was a professional tech writer and while
> Feldman's writing is better than my own, he does not write as well as
> Talbot IMO.

In the case of the info pages for make, the FSF may very well have
been able to engage a professional tech writer to help with writing
the GNU make manual.  The FSF does make money selling dead-tree
editions of the make manual.  It doesn't make a lot of money, since
the exact same version is installed in /usr/share/doc/... as as an
info file, but there are those who prefer thumbing through a dead-tree
copy of a manual instead of reading it a screen.

> info should just be a different interface to man.  No more, not less -- the
> reference - not the manual.

Info is optimized for significantely large pieces of documentation
than man pages.  So for example, Perl tries to document everything via
multiple man pages, but since man uses a simple text pager, and it
deosn't have hyperlinks, I don't actually find Perl's attempt to be
either a reference *or* a manual to be terribly useful.  I would much
*prefer* if the perl manual were available as a set of info pages,
since having internal hypertext links and a real indexing mechanism
would make it far superior than trying to navigate perl's man page
hierarchy.

As it is, I tend to just give up and use Google plus various web
pages, including StackExchange, but that doesn't work well if I'm
off-line.  Info pages work just *fine* off-line.  Or, as you've
pointed out many people do, I'll take existing perl scripts and copy
snippets out of them, using the cargo-cult school of programming.  But
using perl's man pages is mostly an exercise in frustration.

						- Ted