Re: adding examples to man pages

[Richard Coleman <coleman@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