From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 168 invoked from network); 13 Jun 1998 19:52:22 -0000 Received: from math.gatech.edu (list@130.207.146.50) by ns1.primenet.com.au with SMTP; 13 Jun 1998 19:52:22 -0000 Received: (from list@localhost) by math.gatech.edu (8.8.5/8.8.5) id PAA17260; Sat, 13 Jun 1998 15:35:12 -0400 (EDT) Resent-Date: Sat, 13 Jun 1998 15:33:26 -0400 (EDT) Message-Id: <199806131933.PAA02543@cauchy.math.gatech.edu> To: zsh-users@math.gatech.edu Subject: Re: adding examples to man pages In-Reply-To: Your message of "Sat, 13 Jun 1998 21:12:33 +0200." <19980613211233.A5224@math.fu-berlin.de> Date: Sat, 13 Jun 1998 15:33:18 -0400 From: Richard Coleman Resent-Message-ID: <"ogAr63.0.FC4.4GjWr"@math> Resent-From: zsh-users@math.gatech.edu X-Mailing-List: archive/latest/1607 X-Loop: zsh-users@math.gatech.edu X-Loop: zsh-workers@math.gatech.edu Precedence: list Resent-Sender: zsh-workers-request@math.gatech.edu > > The manual is woefully short of examples; it's > > almost exclusively limited to descriptive text. > > Indeed - the manuals need more examples. > Is there a good reason for not including them? > (Other than "minimal size"?) It's primarily historical. Back when I started as maintainer, the man page for zsh was one big man page (about 90 pages long). The man page was so big and cumbersome, no one was enthusiastic about adding examples to make it longer. When I split the man page into several smaller man pages, I always intended to go back and add more examples. But I never got that far. The only man page with any real examples is the one for zshcomptl. But that's because Peter rewrote the whole thing. But the man pages have generally gotten better with time. They are much more readable than they were in the past. With the addition of some examples, they would be fine. The man page which is in the most need of examples is zshexpn. In particular, we need a few examples to show people that the modifiers in the History/Modifiers section, also work with globbing, and parameter expansion (since these are some of the most useful modifiers that zsh has). -- Richard Coleman coleman@math.gatech.edu