From mboxrd@z Thu Jan  1 00:00:00 1970
From: ralph@inputplus.co.uk (Ralph Corderoy)
Date: Sun, 24 Sep 2017 23:54:43 +0100
Subject: [TUHS] Another "craft" discussion topic - mindless tool
	proliferation
In-Reply-To: <20170919233525.k3otv5as6xi2rqht@thunk.org>
References: <201709191701.v8JH1vck032168@darkstar.fourwinds.com>
 <20170919233525.k3otv5as6xi2rqht@thunk.org>
Message-ID: <20170924225443.E33121F975@orac.inputplus.co.uk>

Hi Ted,

> If you take a look at how perl handles its man pages, with 188 man
> pages in section 1:

Yes, I went there the other day looking for something and was dismayed.
The main reason being I learnt Perl thoroughly back when it was
4.something from its single perl(1) lovingly crafted by Larry Wall.  

Given Perl is, no was, an amalgam of Unix programming, this was
perfectly possible to anyone that already new C, sh, sed, awk, grep,
etc., and the man page ran smoothly, assuming all that background
knowledge.

Perl 5 broke this a bit with its addition of classes, and the shift to
POD;  still overseen by Wall.  Since then, with Larry's attention
elsewhere, it seems they've revelled in TMTOWTDI and the documentation
has bloated so it appeared to me, looking for a reference, that there
several possible man pages where it might be.  Looking through those, a
lot of content seem duplicated, but slightly different, and I quickly
gave up.

> I find that info system, with its hypertext linking, to be far more
> convenient.

One nice thing about info(1) in the last few years is they've ditched
printing to stderr what bit of formatting they're doing, removing the
need for a `Gg' in `info libc | less' to make it do that work by seeking
to the end and then erase the clutter by jumping back to the beginning.

> And the question is whether man is a sufficient way to provide
> documentation.

As others have pointed out, it wasn't the sole source of documentation;
papers for bigger programs used to provide the introduction and overview
leaving the man page to mop up as a reference.

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy