Re: Worth mentioning in documentation

[Greg Wooledge]

On Thu, Aug 06, 2015 at 04:13:30PM +0200, Juanma wrote:
> In section ???3.2.4.2 Conditional Constructs??? of Bash docs (both in 
> ???man??? and in the web), at the end, there is an explanation on combining 
> expressions, starting with the use of brackets.
> 
> There it would be worth to mention that:
> 1. you must escape the brackets, also inside script files
> 2. you have to leave blank/s between the brackets and the expression itself

Section 3.2.4.2 of http://www.gnu.org/software/bash/manual/bash.html
is inside 3.2.4 Compound Commands, which is inside 3.2 Shell Commands.
I believe you are talking about the section that discusses the [[ ... ]]
command.

Point 1: I truly have no idea what you mean.  What brackets are you
escaping, and how, and why?

Point 2: Spaces.

Chet chose to omit the phrase "The syntax of ___ is:" from the last few
commands in this section, but you should certainly treat:

[[ ... ]]

     [[ expression ]]

as if it were written:

[[ ... ]]

  The syntax of the [[ ... ]] command is:

     [[ expression ]]

If you treat [[ expression ]] as a formal syntax specifier like those of
"if" and "case", just a few paragraphs up, then the spaces already in
it should be considered as documented.

The manual doesn't explicitly point out that you need spaces after "if"
or "case".  (It fails to mention that you can *omit* the spaces in the
((...)) command, but that's a special exception.)