Re: [Help-bash] How to keep only files match the prefix when do command completion?

[Peng Yu]

> And once you assume a certain level of sophistication, you can assume a
> certain level of experience with writing and debugging shell code: using
> `set -x' temporarily to see what the completion system passes to a shell
> function and so on.

Although it is good for users to know these, as an author of the
manual, you can not expect all users know these things. And even if
they do, the manual should serve the purpose of make thing clear by
itself. Expecting the users to try out how a command work is not a
reasonable expectation from the author of the manual, although the
users themselves may elect to do so.

> I agree with the value of having explicit examples to refer to.  Maybe
> a short example that can be used to illustrate the use of the passed
> arguments and returning values using COMPREPLY would be productive.

Although I can not enumerate all the cases, I do believe there are
more examples need in the manual (I'll report more when I see them).
You probably want to look through the manual and add more examples
whenever necessary.

> It's generally clearer to introduce the concepts and process before
> describing the builtin commands that can `activate' it.

What about introducing the concepts and process along with examples?
The concepts and process in section 8.6 are too abstract, they deserve
some more examples for illustration purposes. Otherwise, the users
have to jump to all the sections that are referred in section 8.6,
which is a waste of users' time.


> Again, it's more useful to describe how things work using general terms
> before getting specific.  It's also good to avoid having information in
> multiple places.  A reference to the previous section might be useful,
> but that's hard to say -- it's the previous section, after all, not one
> halfway back in the document.

Probably it is a drawback of the man page format, so that you can not
add hyperlinks to refer the exact location. But what about describing
the arguments twice (the first time in the current location, the
second time when you describe -F).

-F function
The shell function function is executed in the current shell environment.
When it finishes, the possible completions are retrieved from
the value of the COMPREPLY array variable.

Instead of saying the above, what about saying the following.

-F function
The shell function function is executed in the current shell
environment. Argument $1 of `function` is the name of the command
whose arguments are being completed, argument $2 is the word being
completed, and argument $3 is the word preceding the word being
completed on the current command line. When it finishes, the possible
completions are retrieved from the value of the COMPREPLY array
variable.

Note that do not use things like "the first argument". It is not easy
to see. Use things like $1, as people can immediate see it is a bash
specific thing and is an argument.

Again, I feel that you still don't get the idea of how to make the
manual more readable (hence you may not able to see where examples
should be added as I suggested above). I think that a writer of an
document really need to think how to make the manual easy to read for
the readers rather than think how it is convenient for the auther to
write the manual.

-- 
Regards,
Peng