Documentation change requests

[Peter Stephenson <p.w.stephenson@xxxxxxxxxxxx>]

We often get comments about the documentation being substandard.  In
future, it would help me a great deal if people concerned enough to want
the manual changed could do as much work themselves as possible.

Please could you edit the appropriate Yodl file from the zsh
distribution and send zsh-workers@xxxxxxx a 'diff -u' ('diff -c' will
do) of any changed files.  If you don't have the latest CVS/git source
the last distributed versions is usually fine, the documentation doesn't
change that fast and even just looking at the diff helps me find what
you're talking about.

The files are in the subdirectory Doc/Zsh.  They're basically plain text
and I don't expect you to know anything about Yodl.

- You don't need to do any formatting at all, just add some clearly
marked text.

- You don't need to make any attempt at definitive text and I don't care
how bad your English is.  I'm perfectly happy with comments pointing out
the problem, e.g.

!!!Shouldn't the manual point out this doesn't work with blah blah blah?!!!

!!!For option -X it says blah blah, shouldn't it say the same here?!!!

!!!I was expecting something about feature blah here, it was hard to
find in its current location [please also mark that location with
some text, anything will do, so I can compare]!!!

!!!It doesn't really do 'blah', it actually does 'blech', so the wording
needs improving!!!

etc. etc.  (Of course, if you *do* think you know what it should say
please send that instead.  To emphasise: actual diffs really do save a
lot of time over descriptions of what needs changing.)

It would help even more if you do this in all the relevant locations
that you're aware of (e.g. for multiple features with similar effects)
so I don't have to spend time hunting for things you already know
about.

This will save me considerable time since I won't have to go through the
documentation trying to second guess where and what you're complaining
about and in what way you think it could be improved.  If you go through
the exercise yourself, I think you'll see how much quicker it is if all
I need to do is make an edit to something you've submitted rather than
start hunting through files from scratch.  I really do need all the help
I can get.

(I may repost this occasionally since I don't think there's another
really good way of drawing list users' attention to it.)

Thanks for your help.

-- 
Peter Stephenson <p.w.stephenson@xxxxxxxxxxxx>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/