Feature proposal: New, Standard Documentation System

Les Mikesell lesmikesell at gmail.com
Mon Dec 1 16:55:01 UTC 2008


Camilo Mesias wrote:
> 2008/12/1 Les Mikesell <lesmikesell at 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 at gmail.com




More information about the fedora-devel-list mailing list