Re: Man page section for complete's -C option is inconsistent

[Mark Chandler]

Yep. It's definitely clear if you read the 'Programmable Completion' 
section.

A brief reference to the 'Programmable Completion' section to get that 
explanation would be useful. Or some hint that further reading is 
required to understand the functionality of this option.

As it stands the explanation of the -C option by itself is misleading. 
It doesn't mention the parameter passing at all. But it implies that all 
you need is a command that outputs possible completions. Particularly 
when you can see the following option -F explains how parameter passing 
is done, because that text is lacking for -C, it further implies that 
parameter passing is not done for -C. This is why I said that it's 
inconsistent.

If you like, I can try and go back through the source history to see if 
there's a comment around the commit for the -F text, to explain why it's 
more detailed there and not for -C. It is curious that they're so different.

Cheers,

Mark C.

On 07/07/2022 00:11, Chet Ramey wrote:
> On 7/4/22 12:03 AM, Mark Chandler via Bug reports for the GNU Bourne Again
> SHell wrote:
> > Configuration Information [Automatically generated, do not change]:
> > Machine: x86_64
> > OS: linux-gnu
> > Compiler: gcc
> > Compilation CFLAGS: -O2 -flto=auto -ffat-lto-objects -fexceptions -g
> > -grecord-gcc-switches -pipe -Wall -Werror=format-security
> > -Wp,-D_FORTIFY_SOURCE=2 -Wp,-D_GLIBCXX_ASSERTIONS
> > -specs=/usr/lib/rpm/redhat/redhat-hardened-cc1 -fstack-protector-strong
> > -specs=/usr/lib/rpm/redhat/redhat-annobin-cc1  -m64 -mtune=generic
> > -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection
> > uname output: Linux ice-mef 5.18.7-200.fc36.x86_64 #1 SMP PREEMPT_DYNAMIC
> > Sat Jun 25 20:06:14 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
> > Machine Type: x86_64-redhat-linux-gnu
> >
> > Bash Version: 5.1
> > Patch Level: 16
> > Release Status: release
> >
> > Description:
> >          Even though the -C option of "complete" is functionally very
> > similar to -F, the man page
> >          only provides detailed usage for -F. The -C description doesn't
> > mention parameter passing.
> Look at the `Programmable Completion' section:
>
> "When the function or command is invoked, the
> first argument ($1) is the name of the command whose arguments are  be-
> ing  completed,  the  second argument ($2) is the word being completed,
> and the third argument ($3) is the word preceding the word  being  com-
> pleted on the current command line."
>
> I can't recall why I duplicated that text in the description of `complete'.