by homeworld.cygnus.com with SMTP; 28 Oct 1998 04:42:18 -0000
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Message-Id: <v04020a07b25c44317eb7@[206.248.55.72]>
In-Reply-To: <XFMail.981027000322.root@garbled.net>
References: 
 <Pine.LNX.3.96.981026232759.10241A-100000@acheta.nervana.montana.edu>
Date: Tue, 27 Oct 1998 23:41:38 -0500
To: netbsd-advocacy@NetBSD.ORG
From: Kevin Schoedel <schoedel@kw.igs.net>
Subject: Re: Advocacy through Useability?

On 10/27/98 at 12:03 AM -0700, Tim Rightnour <root@garbled.net> wrote:
>On 27-Oct-98 Louis Glassy spoke unto us all:
>#  Anyway, this is something I'd like to do.  Do any of you
>#  have ideas (similar, different, etc) on what's a smart
>#  way to go about this?
>
>There is work being done I believe to convert our man pages into html with an
>in-tree tool..  This IMHO is a very good thing, and fits your first
>suggestion
>wonderfully.

If something like this is done, *please* make sure that everything
remains available via good old 'man', as plain text that I can pipe
through my chosen $PAGER, or grep, or otherwise process.

One of the major reasons I use NetBSD on my 'ten-dollar' computers, and
have given up on using Linux on my ten-times-faster Mac (NetBSD doesn't
run on it yet) is that documentation on the latter is a mess. Some
information is in man pages, some information is elsewhere in HTML
format, and other information exists only in <imho>execrable</imho> GNU
info files. Every time Linux presented me with a man page that contained
the FSF's "man pages are obsolete" blather in lieu of useful information,
I could feel my blood pressure rise....

Lynx is small and fast compared to Netscape, but it's huge and slow
compared to 'man' of preformatted pages. Skimming through a few man pages
in a row with "man foo bar baz" is much faster and easier than navigating
HTML. At work, I have man pages available in HTML (Solaris) and *never*
use them that way. Even using lynx, it's just too slow and too awkward.

Keep in mind also that not every NetBSD system can necessarily run curses
programs, particularly when newly installed. Some machines only support
serial consoles. New users may not know the correct termcap name for
their terminal, there might not even exist a termcap entry for their
terminal, and in extreme cases, it might not even be possible to run
screen-oriented programs on their terminal. If you think reading man
pages is difficult, imagine having to find or create a correct termcap
entry before being able to read any documentation!

(Something like this actually happened to me when I first installed
NetBSD, on a DECstation; there was a "pmax" termcap entry in root's home
directory but *not* in the global termcap file. I took me a while to
figure out what was going on, and being able to read documentation
certainly helped.)

I'm not opposed to having man pages and other information available in
HTML or other form; just please don't let man pages degenerate into
uselessness, as they have on Linux. Don't force people to use some
interactive program. When trying to make things better, be careful not to
make things worse.
--
Kevin Schoedel
schoedel@kw.igs.net