Re: Bug in user guide

[cheer_xiao <xiaqqaix@xxxxxxxxx>]

On Thu, Feb 10, 2011 at 11:04 PM, Bart Schaefer
<schaefer@xxxxxxxxxxxxxxxx> wrote:
> [snip]
> Just to be sure ... you're talking about
>    http://zsh.sourceforge.net/Guide/zshguide.html
> ??

Yes.

> We'd certainly welcome any help with the guide (or any other docs, for
> that matter) so do jump in and send us suggested improvements.  As for
> (1) in particular ... although the guide can be read linearly it's
> really more intended to to be navigated as hypertext, so adding more
> cross-references to places where terms are explained would probably be
> more useful than merely highlighting the "first" place they are used.
> Which ought to be possible if you're constructing an index anyway.

I think the user guide is intended for linear reading; it's quite hard
for me to start somewhere in the middle. After all, that's what most
"user guides" are; you should turn to the (more formal) documentation
when you need reference. User guides are more like books,
documentations dictionaries.

Given its linear nature, I suppose that adding cross-references can be
distracting and unnecessary (that's what the documentation needs),
while highlighting the first appearance of terms is quite helpful.

> Based on SourceForge's progress so far we might have our CVS back by
> sometime on Friday.

I'm looking forward to a heavily loaded "git pull"!

(I'm not a native speaker so please correct my English if it sounds
weird or impolite. Thanks!)