man pages

Seth W.Klein sk at sethwklein.net
Fri May 2 18:51:48 PDT 2003


Ken Moffat <ken at kenmoffat.uklinux.net> wrote:
> On Fri, 2 May 2003, Sam Halliday wrote:
> 
> > [... about BSD man pages ...]
> >
> > i tried looking at this and the man page width needs editing somewhat to
> > get them to display. also, reformating the pages to the linux man is
> > going to take some time (they use unix cat? directories for a start);

The source should be available somewhere.

> > [....]
> 
>  The "programs not the same" is the biggest danger. No_documentation is
> slightly better than documentation which is plain wrong.  If people
> think they can fix missing man pages, there is a "missing man pages"
> project, or they can rework the info text into a man page and offer it
> back to the maintainers.  Even better, packages such as diffutils now
> use help2man to create the man pages, which ought to keep them in sync
> with the code.  (Damn, that means my man pages for cmp and so forth
> have been replaced.)

The help2man produced pages that i've seen are no replacement for
a proper manual page because they don't include examples.

The major problem, however, is simply the GNU project. Their
documentation is generally wordy, messy, inaccurate, or just plain
missing. I'm thinking of real examples as i name each of those.

For instance, the FreeBSD tar(1) page contains an example of moving
a directory tree through a pipe using tar. Very useful and not some-
thing a new admin might think of. I've looked for this in the tar
info page. If it's there, i can't find it. And there is no GNU tar(1)
man page.

Many (most?) *nix users prefer man format. Well written man format
encourages the author to be concise which makes updates practical;
it is easy to search and easy to skim; it is formatted for display
in a manner that aids comprehension. Large subjects like perl have
(or should have) an index page.

I think the productive solution (and you may mention this to all
the lusers wasting their time flaming people on Slashdot) is for
users to take a project, whip the info page into something resembling
concise, accurate documentation with useful examples, and beat the
project maintainers about the head with a printed copy of the BSD
man pages 'till they accept the new info page. GRUB and tar are
probably excellent places to start.

How to fix the auto-generated/unmaintained/missing man pages without
forking the projects or the documentation, i don't know, but there's
probably a way.

cheers,
Seth W. Klein
-- 
sk at sethwklein.net                         http://www.sethwklein.net/
Maintainer, LFS FAQ             http://www.linuxfromscratch.org/faq/
-- 
Unsubscribe: send email to listar at linuxfromscratch.org
and put 'unsubscribe lfs-dev' in the subject header of the message



More information about the lfs-dev mailing list