[conspire] man pages :-), ...

[Michael Paoli]

> Date: Mon, 29 May 2017 09:16:14 -0700
> From: Rick Moen <rick at linuxmafia.com>
> To: Denny Yang <yangcdenny at gmail.com>
> Cc: conspire at linuxmafia.com
> Subject: Re: [conspire] (forw) Re:  (forw) Re: Linux server
> Message-ID: <20170529161614.GT5811 at linuxmafia.com>

> 'man' pages are an example of the documentation category called 'quick
> reference'.  They are _not_ designed to learn the material from.  They
> are refresher material in ultra-terse form.

*What*?!?!?!?! ... ;-) ... but (semi-)seriously, man pages can be a *great*
resource to learn from!  Uhm, okay, ... maybe relatively and appropriately
judiciously applied - at least these days.

And yes, heck, *much* of what I taught myself regarding Unix, and later
Linux, was from reading the man pages!  :-)  Ah, ... lovely beautiful
man pages - just exactly enough to precisely and exactly explain
everything only and exactly once, in as few words and feasible, with
not a wasted word to spare.  ;-)  Or at least so it used to (mostly)
be.  And, yes, once-upon-a-time, it was feasible to read *all* the
man pages!  ... and I did!  All the man pages for Unix 7th Edition (well
at least of the volumes I could get my hands on at the time), all the
man pages for SCO Xenix - and later SCO Unix ... altogether somewhere
in the range of 2,000 to 5,000 pages total.  ;-)  Alas, no longer feasible,
with the volume of man pages for a typical Linux distribution and
installation (at least also done with the relevant man pages), and the
rate of change ... yeah, I don't think most could keep up with all that
... or even if it's really feasible for anyone to read *all* those man
pages.  Besides, these days typical Linux man pages often do much more
in the way of further explanation, redundant rephrasing and emphasis,
and ... egad, even often have many examples - and extreme rarity in the
days of old.  Not sure if that's better or worse ... probably both
simultaneously.

So, yes, ... judiciously applied.  For the most part, man pages aren't a
tutorial, nor introduction.  Though at least *some* man page collections
*do* have an Intro man page for each volume of the man pages ... worth
reading if your man pages have that.  My fine distribution certainly
has that:
$ apropos Intro | awk '{if($1=="intro")print $1,$2;}'
intro (1)
intro (2)
intro (3)
intro (4)
intro (5)
intro (6)
intro (7)
intro (8)
$
And why awk(1) and only the first two fields, rather than the whole line?
Why spoilers!  ;-)  Would spoil about half the fun giving away such key
elements so easily in advance.  ;-)
But really, those are good pages to read - to well understand what is in
each of the different volumes of the man pages - and if you don't fully
understand it immediately, don't worry, you can eventually refer back to
it later and it will eventually all very much make perfect sense.

So, ... read *all* the man pages?  These days?  Heavens no.  Slightly more
sane approaches?  Look what's on your PATH, e.g:
$ echo $PATH
/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/sbin:/usr/local/bin:/usr/games:/usr/local/games:/home/m/michael/bin
$
Okay, y'all can ignore stuff under my home directory there, but most
notably /bin and /sbin (if they're distinct from /usr/bin and /usr/sbin),
and /usr/bin and /usr/sbin ... if you're only interested in "user" stuff
and not "sysadmin" stuff, you can largely ignore the stuff in the /sbin
directories and mostly just focus on stuff in the /bin directories.  But
if you're aiming to be a sysadmin, you'll want to be more/particularly
familiar with the stuff in the /sbin directories, and will *also* want
to be reasonably familiar with most of what's in the /bin directores
also (yes, some you'll need to know, and also, users *will* ask you
questions ... you needn't know *all* the answers, but ought be at least
somewhat familiar with at least most all software installed on the
system ... even if it's nothing you'd be an expert in (uhm, yeah,
sysadmin probably isn't expected to be an expert in DNA gene sequencing
software or weather modeling software or theoretical astrophysics
simulations ... but if those are software packages quite used by your
users on the systems, you probably ought have a hint what programs
and what they're about).  So, anyway, have a look around ... see stuff
you're not familiar with?  Try to guess what it is.  Then start checking
your guess a bit.  Depending on your distro's package manager and its
data and metadata, that may give you some ways to quickly get substantial
hints/information, e.g.:
$ ls -l /usr/bin/editcap
-rwxr-xr-x 1 root root 43096 Jan 22 09:03 /usr/bin/editcap
$ dpkg -S /usr/bin/editcap
wireshark-common: /usr/bin/editcap
$ dpkg -l wireshark-common | grep '^ii'
ii  wireshark-common 2.2.6+g32dac6a-2+deb9u2 amd64        network  
traffic analyzer - common files
$
So, ... with a name like editcap, you'd think it would likely edit ...
*something* ... with those additional hints, what do you think it would
edit or operate on?
And, of course, man pages themselves.  Don't need to read the whole thing,
that can also be *very* long, e.g.:
$ 2>>/dev/null man perlfunc | wc -l
8220
$
Yeah, that'd be about 125 pages of reading for just that one man page
(or about 343 screens full of text).  How 'bout something much more
concise:
$ man perlfunc
PERLFUNC(1)            Perl Programmers Reference Guide            PERLFUNC(1)

NAME
        perlfunc - Perl builtin functions
... okay, have a reasonable idea now?  Want to read more, go for it, want to
check on something else?  Jump to it!
$ man find
FIND(1)                     General Commands Manual                    FIND(1)

NAME
        find - search for files in a directory hierarchy

SYNOPSIS
        find  [-H]  [-L]  [-P]  [-D  debugopts]  [-Olevel]  [starting-point...]
        [expression]
Lovely ... have a rough idea of what it might be useful for?  Good!
Want more details - read more of it.
Most man pages are arranged in quite standard sections, and generally in a
quite specific order.

The title bit give you command and the manual volume it's in.  Note that
sometimes the same item may exist in multiple volumes - sometimes quite
different in those differing contexts - e.g. one might be a user command,
in other context a file format, in yet another a system call or standard
library call.

NAME - generally give you the name of the command or whatever, and a terse
description - these are also generally the words/terms one can find/search
it under with apropos(1) or for some *nix flavors, man -k.  That's the
digital equivalent of searching it in ye olde hardcopy permuted index (don't
know what that is?  Try a search on: Unix man pages permuted index
and you'll likely find out).

SYNOPSIS - generally a terse summary of syntax usage - if often doesn't
include all the options - some man pages don't even explicitly show
any of the options here

DESCRIPTION - kind'a self-explanatory.

There are typically many additional sections - I won't describe most of them
here, but I'll mention one other of note - typically around the very
end, if present at all: SEE ALSO - a generally useful listing of additional
related references - often many/most/all of them are other related man pages.

So ... perusing some command and man pages can be a relatively quick way
to get at least an inkling, if not perhaps as much as rough understanding,
of what the system is or may be capable of, and via what commands and
facilities, etc.

And, sure, not as general and thorough as doing some introduction /
tutorial materials, and may not make the connectedness as readily
apparent - at least early on, but one will often find cool and interesting
things one might not otherwise have found (e.g. that's how I happened
upon the quite handy utility tac ... and once I had a peek at the man
page, it was also highly clear why it was named as it was - and then also
quite usefully memorable).

And somewhat related - Linux Standard Base (LSB) - one can likewise peruse
documentation there - for the most part, much of it quite similar to
man pages.

And a bit more broad - POSIX / SUS - can peruse documentation there,
quite standard, and ought be highly applicable across any reasonably
compliant *nix - and that generally includes most major Linux
distributions (one may also note that that a whole lot of LSB is
essentially: "It's just like it's specified in POSIX", or:
"It's just like it's specified in POSIX, except for: ..."

Also of note, some specific bits of documentation to round out some gaps
in the above ... but without going all the way to more general tutorials
and introductions and such.  Read some stuff about the
"Unix design philosophy".  Doesn't exactly 100% apply to everything on
Linux these days, but much of it is still quite to highly applicable.
Also, read and learn about shell.  Bash (and its man page) can be a bit
overwhelming - a whole lot 'o stuff there.  Can start much more simply,
read the man page for dash(1) instead - that's basically a minimally
compliant POSIX shell - so it leaves out a whole lot 'o bells, whistles,
interactive goop, and cruft. And ...
$ echo $(man dash | col -b | wc -c)/$(man bash | col -b | wc -c)\*100 | bc -l
20.30429459960344258700
$
It's only about 20% the size of the humongous bloated bash(1) man page.
(Want to regain some of your life back?  Have it to spend reading more
exciting and more interesting and varied man pages, rather than 5x as many
pages just to cover the bloated bash shell? - yeah, you can always
skim/search that bash man page later ... if/when you really need/want to.)

Oh, ... and Filesystem Hierarchy Standard (FHS):
http://www.pathname.com/fhs/
Be sure to read (or at least skim) that (can reread it later more carefully
and in more detail ... even refer to it on multiple occasions!  :-)).

Oh, and of course man has a man page for itself, so:
$ man man
is an excellent place to start ... notably to also know how to get
the relevant man page, and sometimes specifically from the man volume(s)
of interest.  Also good to have at least a quick peek at the man page for
apropos, presuming your distribution has that.

So ... there 'ya go.  Read some man pages!  :-)  A *fine* place to start! ...
well, with some caveats and a wee bit 'o guidance, context, and some
relevant related suggestions and some materials to round things out a wee
bit.

"Of course" there are also good tutorials, guides, books, etc. to be found,
including on-line - good to *also* utilize such.  But, though I'd (also)
make good strong case for man pages (yeah man pages! :-)), and some
related bits and a few key references to fill in some gaps.