Re: zsh.texi

[Clive Messer <clive@xxxxxxxxxxxxxxxx>]

On Wed, 12 Jun 1996, Bart Schaefer wrote:

> On Jun 12, 11:25pm, Mark Borges wrote:

> } Subject: Re: zsh.texi
> }
> }    http://www.mal.com/zsh/Doc/test/zsh.texi.gz
> 
> "403 Forbidden
> 
> Your client does not have permission to get URL /zsh/Doc/test/zsh.texi.gz
> from this server."

I dare say Mark will fix this.
 
> }    http://www.mal.com/zsh/Doc/test/zsh_toc.html
> } 
> } Please take a look if you're interested. We would appreciate any
> } suggestions or comments (or better, patches) anyone may have.
> 
> Spell-check it.

Unfortunately, Mark does not have the latest working copy (with spelling
corrections) and will not have until I return home and upload it this
evening. 

> I'm just glancing at the programmable completion section at the moment.
> Some of it is still pretty hard to decipher.  Here's an example:
>
>
> -d This can be combined with -F, -B, -w, -a, -R and -G to get names of
>        disabled functions, builtins, reserved words or aliases. 
> -e Without -d this option has no effect. Otherwise this can be combined
>        with -F, -B, -w, -a, -R and -G to get names of functions, builtins,
>        reserved words or aliases even if they are disabled. 
>
>
> That stuff under -e doesn't make sense to me -- Without -d, has no
> effect?
> You mean I have to use `compctl -d -e ...'?  Why? -- and it conflicts
> with the zshcompctl.man description:
>
> -e Names of executable (and enabled) commands.

Yes, the above is wrong.  I will correct it when I return home this
evening before I upload the latest version to Mark.

> Here's another example:
>
>
> -C controls completion when there is no current command, in other words
> when the command word itself is being completed. Without this command,
> the names of any executable command (whether in the path or specific to
> the shell, such as aliases or functions) are completed.
>
>
> "Without this command, ..." ??  Without what command?  I think it means
> "If no `compctl -C' command has been issued in the current shell, ...".

This is a direct copy of zshcompctl.man.
Perhaps it needs to be clarified in the man page.

> Then there's this:
>
>
> If the + flag is alone and followed immediately by the command list, the
> completion behavior for all the commands in the list is reset to its
> default by deleting the command from the list of those handled
> specially.
>
> I think this means:
>
> If the + flag is alone and followed immediately by a list of command
> names, any previous programmable completion for each of those commands
> is disabled. This restores the default completions for the listed
> commands.

Again, this is a direct copy of the man page.

> As a general remark, this sort of documentation should avoid talking
> about how a given operation is accomplished (e.g., above, dump the "by
> deleting the command from the list ... handled specially") and just
> state what the end result is.  Only discuss how something works if
> that's important for using the feature correctly; and even then, *first*
> concisely describe the end result, and *then* elaborate how it comes to
> pass.

I did not set out to re-write the man pages, just port them to texinfo.
zsh.texi (at present) is a copy of the man pages in texinfo format with 
an expanded "Introduction" that includes the META-FAQ.

> I don't know if it's broken in the base document or if it's the fault
> of texi2html, but double-quoted strings in some examples are really
> messed up:
>
>
> -H num pattern 
>        [...snip...]
>        A typical use is `compctl -D -f + -H 0 " -X '(No file found;
>        using history)''
>
> -l cmd
>        [...snip...] 
>        example, `compctl -x 'r[-exec,;]' -l " -- find'

This is a problem with doubled single-quote characters ie. ''
They are correctly handled (@iftex / @ifinfo) in the source so I would
assume that the problem is with texi2html.

Clive.
-- 
C Messer. Epos Systems. UK.  |
<clive@xxxxxxxxxxxxxxxx>     |   "I pressed her thigh and death smiled."
<clive@xxxxxxxxxxxxxxxxxx>   |    Jim Morrison.