libc manual compliments

[karl at freefriends dot org (Karl Berry)]

Some kudos on the libc manual I thought I'd pass along as a break from
the usual bug reports :).

karl


Date: Mon, 25 Jun 2007 23:51:47 -0400
From: "roger via RT" <webmasters@gnu.org>
Apparently-To: <karl@freefriends.org>
Subject: [gnu.org #337662] Simple Code Snippet Examples of Usage 


A NEW TICKET HAS BEEN CREATED, REPLIES GO TO REQUESTORS BY DEFAULT.

Mon Jun 25 23:51:46 2007: Request 337662 was acted upon.
Transaction: Ticket created by roger@eskimo.com
       Queue: webmasters
     Subject: Simple Code Snippet Examples of Usage
       Owner: Nobody
  Requestors: roger@eskimo.com
         CCs: 
      Status: new
 Ticket <URL: http://rt.gnu.org/Ticket/Display.html?id=337662 >


There's not too many times I say this... usually, only in bed with a
pretty girl do I show this much gratitude.

I find the "Simple Code Examples" of library/function usage on both,
gnu.org and man pages extremely valuable!

ie:
http://www.gnu.org/software/libc/manual/html_node/Waiting-for-I_002fO.html

The code snippet is simple, yet complete and demonstrates the function's
usage as simple as a "Hello World" program.

Another command last month I learned was getdelim.
ie:
$ man getdelim

Again, simplet and yet complete.  As easy as a "Hello World" program.

I can do > 2 hours of searching Google for examples without finding how
a function works because the examples of littered with uncommon
variables and syntax.  They're also usually polluted with the authors 20
years of experience no newbie gives two cents for except to utterly
confuse the learner into an abyss.  When I finally happen to find these
html/man files, usually by accident, I can then learn the
library/function within < 5 minutes!

(Note: I think not all functions, such as the man file for select() has
a simple example. But the html page above did.  After an hour, finally
found the web page.)

(Feel free to repost this compliment to whomever is integrating the
simple complete code examples into the man pages & web page. :-)

--
Roger
http://www.eskimo.com/~roger/index.html
Key fingerprint = 8977 A252 2623 F567 70CD 1261 640F C963 1005 1D61

Mon Jun 25 20:25:14 PDT 2007