patchThe GNU Bourne-Again SHell - Patches: patch #10162, Minor changes to help until, while...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

patch #10162: Minor changes to help until, while message.

Submitter:  Paxsali <paxsali>
Submitted:  Sun 19 Dec 2021 05:44:54 PM UTC
   
 
Category:  None Priority:  5 - Normal
Status:  Done Privacy:  Public
Assigned to:  None Open/Closed:  Open

Sun 19 Dec 2021 05:44:54 PM UTC, original submission:  

Hi all,

I noticed a minor inconsistency in the help messages of until and while.

Comparing both of them directly with the help message for if one notices quickly that the if help message clearly distinguished between three different occurrences of COMMANDS.

  • `if COMMANDS'
  • `elif COMMANDS' (optional)
  • `else COMMANDS'


The full syntax for if being:


if COMMANDS; then COMMANDS; [ elif COMMANDS; then COMMANDS; ]... [ else COMMANDS; ] fi


In contrast to if, here are the syntaxes of until and while:

until:

until: until COMMANDS; do COMMANDS; done


while:

while: while COMMANDS; do COMMANDS; done


Both have two occurrences of COMMANDS, however their help messages aren't 100% clear which one's are meant and can potentially be mixed up or misunderstood.

You and I know how it's meant, ofc. But I'm not sure this is the best way to explain what it does to other people.

I think the following wording might be better and I'd like to put it up for discussion:

until:

$ help until
until: until COMMANDS; do COMMANDS; done
    Execute commands as long as a test does not succeed.

    Expand and execute `do COMMANDS' as long as the final command in the
    `until COMMANDS' has an exit status which is not zero.

    Exit Status:
    Returns the status of the last command executed.


while:

$ help while
while: while COMMANDS; do COMMANDS; done
    Execute commands as long as a test succeeds.

    Expand and execute `do COMMANDS' as long as the final command in the
    `while COMMANDS' has an exit status of zero.

    Exit Status:
    Returns the status of the last command executed.


patch:

diff --git a/builtins/reserved.def b/builtins/reserved.def
index 33184b02..128e62e7 100644
--- a/builtins/reserved.def
+++ b/builtins/reserved.def
@@ -117,8 +117,8 @@ $BUILTIN while
 $SHORT_DOC while COMMANDS; do COMMANDS; done
 Execute commands as long as a test succeeds.

-Expand and execute COMMANDS as long as the final command in the
-`while' COMMANDS has an exit status of zero.
+Expand and execute `do COMMANDS' as long as the final command in the
+`while COMMANDS' has an exit status of zero.

 Exit Status:
 Returns the status of the last command executed.
@@ -128,8 +128,8 @@ $BUILTIN until
 $SHORT_DOC until COMMANDS; do COMMANDS; done
 Execute commands as long as a test does not succeed.

-Expand and execute COMMANDS as long as the final command in the
-`until' COMMANDS has an exit status which is not zero.
+Expand and execute `do COMMANDS' as long as the final command in the
+`until COMMANDS' has an exit status which is not zero.

 Exit Status:
 Returns the status of the last command executed.


I believe above wording will be more accessible for beginners while still being correct.

This is a very minor change.

Thanks for discussing in advance.

PS:
the patch above deliberately only consideres the file builtins/reserved.def, not all the other occurences under po/<language>.{po,pot}.
Since I don't understand how they're all related or generated, I thought it's enough to just mention this for anyone who does understand it.

Paxsali <paxsali>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by chet (Updated the item)
  • -email is unavailable- added by paxsali (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

     

    Follows 1 latest change.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-12-21 chet StatusNone Done

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code