help-bash
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Chet Ramey
Subject: Re: [Help-bash] How to keep only files match the prefix when do command completion?
Date: Thu, 15 Dec 2011 09:28:23 -0500
User-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:8.0) Gecko/20111105 Thunderbird/8.0

On 12/14/11 3:38 PM, Peng Yu wrote:

> But my previous comment still applies.
> 
> "... this is written in some obscure place, but it also means that the
> manual should be rewritten"
> 
> Do you expect a new users to understand section 8.6? These are all
> abstract descriptions without concrete examples. Since you are the
> author of bash, you will have no problem understanding it. But please
> think as if you were a new user who has no zero knowledge of bash
> completion.

That's an interesting question.  What is the level of sophistication
we can expect for someone who is looking at bash completion?  And when
I mean bash completion, I mean something beyond the existing options to
`complete' -- the use of shell functions to customize completion for a
particular command.  Can we expect someone like that to be writing his
first shell function?  I would argue that that's not the common case.

A person who is writing a shell function to customize completion should
already posess a good understanding of how shell functions work.  The
existing text explaining the arguments and the paragraph explaining how
to return values to the completion system should supplement that.

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.

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.

> My suggestion is to give some working examples and introduce the
> options in 8.7 and then introduce 8.6. Or merge descriptions in 8.6
> with the options described in 8.7 and adding examples to illustrate
> the points. Or at least, refer back to section 8.6 in 8.7 for each
> option discussed in section 8.7 (but this is a less optimal solution
> as it introduce cyclic dependencies)?

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


> "the first argument is the name of the command whose arguments are being
> completed, the second argument is the word being completed, and the
> third argument is
> the word preceding the word being completed on the current command line."
> 
> The above is very hard to catch for user who basically gets lost in
> that section. Why don't you put it in the description of -F? And
> explicitly spell $1, $2 and $3 so that they become more searchable?

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.

Chet

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
                 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, ITS, CWRU    address@hidden    http://cnswww.cns.cwru.edu/~chet/



reply via email to

[Prev in Thread] Current Thread [Next in Thread]