prefix_command documentation is confusing and should be reworded

[mwestphal]

We read the prefix_command documentation:

App *     prefix_command (bool allow=true)
     Do not parse anything after the first unrecognized option and return. 

bool     prefix_command_ {false}
     If true, return immediately on an unrecognized option (implies allow_extras) INHERITABLE. 

There is an incoherence. The method param name is "allow" implying that setting to true would "allow" unrecognized option but the param doc is they other way around.

On testing, it looks like the param doc is incorrect, setting prefix_command to true indeed "allow" to have unrecognized option.

[henryiii]

That is what it does, though; it causes parsing to stop as soon as it hits an unrecognized option, which puts them in the "unparsed" options. This "allows" unrecognized options; otherwise if it didn't stop, it would try to recognize them and fail.

[mwestphal]

I just tested, setting it to true does not cause the parsing to stop, setting it to false cause the parsing to stop.

[henryiii]

What do you mean by "parsing to stop"? Just checking to make sure we are referring to the same thing.

[mwestphal]

What I mean by "parsing to stop" is that, when setting allow to false, when encountering an unrecognized option, the parsing stop and the parsing method returns immediatly.

[henryiii]

Okay, that's what allow=true does, it causes parsing to stop and returns, giving access to all unrecognized options. allow=false cases parsing to continue, which breaks on an option not registered with CLI11. If you call .prefix_command() (which is allow=true), then prefix_command_ is true which returns immediately on unrecognized options.

[mwestphal]

I'm getting confused a bit now but I think its a vocabulary issue.

in any case, we got confused by the documentation when using this in our app (ParaView).

Indeed, when I hear "it causes parsing to stop", I definitely do not understand "it does not cause an error and give access to unrecognized option".

Nothing critical, but I think this doc could be improved to explain a bit more how to use CLI11 to do a partial parsing of the CLI options (which is the usecase I had).

[henryiii]

Okay, I think this should be reworded to avid "parsing to stop". Internally, that's what's happening, but that's not a good description for readers. I think we can use the same text for both, since they are the same thing.

[phlptp]

@mwestphal this was clarified in #1059, I will leave it open for a day or so if you have any further comment

[mwestphal]

Lgtm