getopt_long(3): Document behavior of leading characters in optstring

[kevans]

Summary

Leading '+', '-', and ':' in optstring have special meaning. We briefly mention that the first two have special meaning in that we say POSIXLY_CORRECT turns them off, but we don't actually document their meaning. Add a paragraph to RETURN VALUES explaining how they control the treatment of non-option arguments.

A leading ':' has no mention; add a note that it suppresses warnings about missing arguments.

As an aside for the review: I debated adding a further note that a leading '+' is required for maintaining compatibility with getopt(3) as far as treatment of non-option arguments goes, but I was not sure if this was a good idea or not.

[kevans]

getopt_long.3

241 ↗

(On Diff #38705)

I guess this line is already wrong before we even get off the ground?

[jilles]

Even though it is from January, this is still a useful patch.

getopt_long.3

210–212 ↗

(On Diff #38739)

The functions only return ':' if error messages are suppressed. In the default mode, missing option arguments cause an error message to be written and '?' to be returned.

221–229 ↗

(On Diff #38739)

This should mention somewhere that + or - should go before : if both are given.

230–233 ↗

(On Diff #38739)

This is actually almost the other way around: if + is specified, it means processing should halt at the first non-option argument.

[kevans]

• Broke the return value commentary out into a separate paragraph since it's getting kind of wordy
• Add a note about the default return behavior, and how exactly this is changed with ':'
• Mention that +/- must appear before :
• Fix the description of '+' -- it explicitly turns off the permutation and stops at the first non-option argument. I've also added a note that a leading '+' matches the default behavior of getopt(3).

[kevans]

Any other comments on this?