[sf-lug] man pages, info, tutorials, books ... [was: SF-LUG meeting of Monday, 15 August 2016]

[Michael Paoli]

> From: "Rick Moen" <rick at linuxmafia.com>
> Subject: Re: [sf-lug] SF-LUG meeting of Monday, 15 August 2016
> Date: Tue, 16 Aug 2016 12:01:16 -0700

> Sadly, man pages are generically a poor vehicle for learning about
> software -- because that's just not the _type_ of documentation they
> are.

Dang, I thought man pages were (and are) fantastic for learning stuff!
;-)

I mean, after all, I did - at least once upon a time - read *all* the
man pages - cover-to-cover.  :-)  Okay, I did also have the man page
permuted index to help me out a bit ... and apropos(1).  Okay, there
were also a few relatively teensy tutorials I also used.  But that was
mostly it.  (Okay, I'm weird that way ... and besides, once upon a time,
that was mostly all that was available).

Okay, by the time I started to get to Linux, I did actually get *one*
Linux book (_Running Linux_, 2nd edition) - that was mostly to help me
bridge the Unix/Linux differences (and they were arguably more
different/distinct around 1998, compared to today).  And I did have some
Unix books by then ... but all those Unix books came *after* I'd done my
first cover-to-cover reading of all the man pages.  Of course nowadays,
a full cover-to-cover reading of all the man pages is infeasible - if
not "impossible".  The total volume of material, plus rate of change
atop that ... just can't do it these days.

Oh, my favorite "browser" for perusing man pages?  My viewman program:
$ expand -t 4 < ~/bin/viewman
#!/bin/sh

tmpdir="${TMPDIR-/tmp}/vm.$$"

trap '' 1 2 3 15
mkdir "$tmpdir" || exit
trap 'rm -rf '\'"$tmpdir"\' 0 1 2 3 15
2>&1 man ${1+"$@"} |
     2>&1 tr '\255' - |
     col -b |
     >"$tmpdir/vm.$$" 2>&1 sed -ne '/[^  ]/p'
vi -R "$tmpdir/vm.$$"
$

It's also especially handy for searching/jumping around within friggin'
huge man pages - e.g. perlfunc(1).

Oh, and you also made mention of info - the thing that always drove me
nuts with info, is yet another different interface for navigating
hyperlinks.  But I deal with that relatively easily ... I don't navigate
info hyperlinks.  I use my handy dandy ... you might guess it by now,
viewinfo:
$ expand -t 4 < ~/bin/viewinfo
#!/bin/sh

tmpdir="${TMPDIR-/tmp}/vi.$$"

trap '' 1 2 3 15
mkdir "$tmpdir" || exit
trap 'rm -rf '\'"$tmpdir"\' 0 1 2 3 15
2>>/dev/null info --subnodes --output=- ${1+"$@"} |
     2>&1 tr '\255' - |
     col -b |
     >"$tmpdir/vi.$$" 2>&1 sed -ne '/[^  ]/p'
vi -R "$tmpdir/vi.$$"
$