Re: [TUHS] man-page style

[Bakul Shah <bakul@bitblocks.com>]

On Fri, 16 Nov 2018 11:55:28 -0500 Paul Winalski <paul.winalski@gmail.com> wrote:
> On 11/16/18, Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:
> >
> > I think man pages make a great reference.  But I don't think they are a
> > good teaching source for someone that doesn't know the material or what
> > the components are for.
> >
> I agree with Grant.  If you want to know what a particular command
> does and what its options are, man pages are fantastic.  If you are a
> new or casual user trying to find out what command(s) to use to
> accomplish a particular task, the man pages are an exercise in
> frustration and futility.  

When I first came to Unix, I read man pages for every one of
the commands in /bin and experimented with them and tried out
various options. Being a fan of recursion the first thing I
tried was "man man"!  Then I went through all the man pages in
other section to learn about libc functions, special devices
and so on.  I knew about "apropos" (though don't recall if it
was in v7) but I didn't really use it all that much.  Or the
inverted index.

I tend to think software has more in common with carpentry
than science or engineering and like all good craftsman,
knowing how to use all the tools in your workshop is
essential. If you get lucky you get to be an apprentice to a
good mentor but I didn't have that luxury in a startup.

>                            Other OSes have done a better job in that
> area (the VMS and DTSS HELP commands come to mind).  IMO ideally one
> should have both--a generalized "help" command for those trying to
> find out what command to use, and "man" as reference material.  UNIX
> and Linux have never had a proper help facility.  Or at least I never
> was able to find it.

I had usd VMS befoe Unix. Not for long but I don't recall its
help facility being particularly superior.

Each of us learns differently so there is no one true style.