inconsistent synopses in help output

[Benno Schulenberg]

In the output of the 'help' command in any bash upto and including
4.4-beta, the possible arguments in most of the commands listed are
shown in lowercase, but for some they are in uppercase.  Examples:

  alias [-p] [name[=value] ... ]
  break [n]
  case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... esac
  dirs [-clpv] [+N] [-N]
  enable [-a] [-dnps] [-f filename] [name ...]
  for NAME [in WORDS ... ] ; do COMMANDS; done
  help [-dms] [pattern ...]
  local [option] name[=value] ...
  while COMMANDS; do COMMANDS; done

This is inconsistent.  What's more, in the descriptions that follow
when you do 'help SOMECOMMAND', the arguments are always referred
to in uppercase.  For example in the output of 'help break' it says:
"If N is specified, break N enclosing loops."  But its synopsis line
says: "break: break [n]".  It would be much clearer if the synopsis
and the description would both use uppercase for this argument,
just like the 'dirs' command already does.

Also, using uppercase for arguments makes it much easier to see
what is a word that needs to be replaced and what is a keyword
that must be typed as is, like in the 'case' and 'for' commands.

For example:

  command [-pVv] command [arg ...]

would be clearer when written as:

  command [-pVv] COMMAND [ARG ...]

So...  I propose to write all replaceable argument words in the
help sysnopses in uppercase, just like they are in the reference
manual (the Info document).  I can make the patch, if you wish.

Benno

-- 
http://www.fastmail.com - IMAP accessible web-mail