Re: [gentoo-user] Re: Gentoo's advantage: 'optimized for your system' -- huh?

[Stroller]

On 6 Feb 2009, at 03:08, Jesús Guerrero wrote:
> El Vie, 6 de Febrero de 2009, 4:03, Stroller escribió:
>>
>> My experience is that only after learning the syntax of manpages (is
>> that itself documented?) do I find most of them tremendously easy to
>> navigate to find the one specific option I'm looking for.
>
> If all the problem about man pages is navigation another pager
> can be used.

I didn't really mean "navigate" like that.

And in the quote above I wasn't criticising navigation of manpages.

I just mean that if there's one option I want to find (I don't know -  
list by date order in `ls` for instance) then I just find it  
tremendously EASY to find that in a man page. You can search for a  
word using the normal old "/" of `less` and 9 times out of 10 you find  
the command flag very quickly (if not immediately).

If you're new to a command that's been recommended to you, or an app  
you've just installed, then I find the "Synopsis" section is  
tremendously useful, but it has to be said that:

        less [-[+]aBcCdeEfFgGiIJKLmMnNqQrRsSuUVwWX~]
             [-b space] [-h lines] [-j line] [-k keyfile]
             [-{oO} logfile] [-p pattern] [-P prompt] [-t tag]
             [-T tagsfile] [-x tab,...] [-y lines] [-[z] lines]
             [-# shift] [+[+]cmd] [--] [filename]...

doesn't make any sense to the untrained eye. It just looks like  
gobbledegook. There's maybe a Linux n00b manual that explains the  
syntax of man's "Synopsis", but I'm sure I only learned to translate  
the likes of the above after reading man pages for commands that I  
already knew - learned through inference, osmosis and newsgroups.

> If the problem is "contents" then that's nothing to do with
> man, but with whomever made (or didn't made) the page.

Yes, but there's a problem with the MAJORITY of contents, perhaps of  
the majority of people writing manpages? It just seems to be a culture  
of the way man pages are written. They make perfect sense only with  
experience - don't get me wrong, I love 'em and at least to a degree I  
think that's how it should be.

But I think the criticism of someone who finds man pages difficult to  
read "your own inadequate ability to read technical documents, ...your  
own capacity for comprehension" is a tad unfair.

Take a look at this:

DESCRIPTION
        Less is a program similar to more (1), but which allows  
backward  move-
        ment in the file as well as forward movement.  Also, less does  
not have
        to read the entire input file before  starting,  so  with   
large  input
        files  it  starts  up  faster than text editors like vi (1).   
Less uses
        termcap (or terminfo on some systems), so it can run on  a   
variety  of
        terminals.   There is even limited support for hardcopy  
terminals.  (On
        a hardcopy terminal, lines which should be printed at the   
top  of  the
        screen are prefixed with a caret.)

        Commands  are based on both more and vi.  Commands may be  
preceded by a
        decimal number, called N in the descriptions below.  The  
number is used
        by some commands, as indicated.

The first sentence could far better be written "Less is a program for  
scrolling up & down through textfiles" - actually this highlights the  
typical manpage charm of greater obscurity through complete  
correctness. The second sentence doesn't seem valuable enough (these  
days) for the main summary - it would be more useful to mention the  
ability to search - and the 3rd sentence is more relevant to the 1970s  
than today (the bracketed section which follows is more relevant to  
the 16th century). Most newcomers to `less` will never have used  
`more` or `vi`, and the last two sentences - well, there's just  
something wrong with them. They're not very readable. I had to read  
them twice myself - who the heck would think to use a NON-decimal  
number, anyway?

Stroller.