[PATCH 1/3] doc: usage: Add general rule for `$?`

[Quentin Schulz]

On 10/22/25 3:54 PM, Tom Rini wrote:
> On Wed, Oct 22, 2025 at 11:19:21AM +0200, Quentin Schulz wrote:
>> Hi Tom,
>>
>> On 10/21/25 10:25 PM, Tom Rini wrote:
>>> diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst
[...]
>>> +   values are 0 on success, -1 on a usage related errors, i. e. invalid syntax
[...]
>> I would also add a comma after "syntax".
> 
> Is that oxford comma or no?
> 

I don't believe so?

"Values are 0 on success, -1 on usage related errors and 1 on any other 
error."

With Oxford comma:
"Values are 0 on success, -1 on usage related errors, and 1 on any other 
error."

Here it's simply to "close" an example/clarification/extension:

"I found an apple, an orange, next to a kiwi and a potato."
"I found an apple, an orange, next to a kiwi, and a potato."

In the second sentence *I* (so to take with a grain of salt as I'm not a 
native speaker :) ), I know the potato is not necessarily next to the 
kiwi, it's just that I found one. In the first sentence, it's implied 
because otherwise the sentence would be "odd" (removing "useless" info 
would mean the sentence is now "I found an apple, an orange.").

I could even see

"I found an apple, an orange (next to a kiwi) and a potato."

so

values are 0 on success, -1 on a usage related errors (i.e. invalid 
syntax) and 1 on any other error.

Anyway, nothing important (nor necessarily proper English).

>>
>> Should i.e. be e.g.? c.f. https://en.wiktionary.org/wiki/i.e.
>>

This one "it depends", if the only possible usage related error is a 
syntax error, "i.e." is fine, otherwise not.

>>> +   and 1 on any other error. Any exceptions to this are documented by the
>>> +   specific command, i. e. :doc:`cmd/for` sets this based on the last command
>>
>> s/i. e./e.g./
> 
> Maybe? In both cases I'm following the example in the previous rule here
> that's quoted for context.
> 

That's for sure not an "i.e." that should be here. Replace "i.e." with 
"that is" or "in other words" and if it doesn't work, it's likely "e.g." 
(to be replaced with "for example").

Cheers,
Quentin