[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: Feature proposal: New, Standard Documentation System

Camilo Mesias wrote:
2008/12/1 Les Mikesell <lesmikesell gmail com>:
Adding a few examples won't hurt, but man pages are not the place for
conceptual fluff.  We need some other format to hold an overview of why you
should use each program and how various program can be combined to
accomplish different results.  Man pages should just contain a reference for
that program's use, because you won't look there until you already know why
you want to run it.

Don't forget you can have manpages for conceptual fluff (try man
selinux / which selinux), and you can find out what command you need
to do using 'apropos'. Example: apropos security

But I would never have thought to use 'man' on a meta-package name, so that's only useful after some user training (or the tutorial where such information really belongs anyway). And 'apropos security' should probably list every program with any security related aspect. That is, if it worked like it should, there would be too many results to be useful.

The man system really has been round the block a few times...

And it only really worked when it was accompanied by a separate tutorial and overview and the list of programs was small enough to browse with xman or search with 'man -k'. The pages themselves are generally fine once you get to the point of wanting refernce details, but now that there are many thousands of choices you need to know where to start.

  Les Mikesell
   lesmikesell gmail com

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]