test/[: remove effectively inaccessible self-doc

Did you know that you could get a manual page for the 'test'/'['
builtin command using one of these strange command lines?

	test --man --

	[ --man -- ]

Neither did I. It's not documented or mentioned anywhere (and this
syntax violates POSIX). So nobody knows about it, which makes that
documentation useless. (The regular --man option doesn't work
because that would break 'test'.) I only found out how to invoke it
when I understood what the uncommented C code handling this does.

The test/[ command's self-documentation is unmaintained since 2003
and somewhat incomplete. It's also mostly redundant with the
documentation on Conditional Expressions in the main (k)sh.1 manual
page. But unlike the latter, this is resident in RAM, wasting
working memory in every shell process.

src/cmd/ksh93/sh.1:
- Add documentation for 'test'/'[' commands (yes, they were not
  mentioned in the main manual page until now), describing them
  in terms of differences from '[[' and recommending the latter.

src/cmd/ksh93/include/test.h,
src/cmd/ksh93/bltins/test.c,
src/cmd/ksh93/data/testops.c:
- Remove RAM-resident --man doc for test/[ command.
- Remove the bizarre option parsing that allowed invoking it.

Author: McDutchie

src/cmd/ksh93/bltins/test.c

@@ -202,21 +202,8 @@ int b_test(int argc, char *argv[],Shbltin_t *context)
 				exitval = (*argv[2]!=0);
 				goto done;
 			}
-			if(cp[0] != '-' || cp[2] || cp[1]=='?')
-			{
-				if(cp[0]=='-' && (cp[1]=='-' || cp[1]=='?') &&
-					strcmp(argv[2],"--")==0)
-				{
-					char *av[3];
-					av[0] = argv[0];
-					av[1] = argv[1];
-					av[2] = 0;
-					optget(av,sh_opttest);
-					errormsg(SH_DICT,ERROR_usage(2), "%s",opt_info.arg);
-					return(2);
-				}
+			if(cp[0] != '-' || cp[2])
 				break;
-			}
 			exitval = (!test_unop(tdata.sh,cp[1],argv[2]));
 			goto done;
 		case 2:

src/cmd/ksh93/data/testops.c

@@ -55,109 +55,6 @@ const Shtable_t shtab_testops[] =
 		"",		0
 };
 
-const char sh_opttest[] =
-"[-1c?\n@(#)$Id: test (AT&T Research) 2003-03-18 $\n]"
-USAGE_LICENSE
-"[+NAME?test - evaluate expression]"
-"[+DESCRIPTION?\btest\b evaluates expressions and indicates its "
-	"results based on the exit status.  Option parsing is not "
-	"performed so that all arguments, including \b--\b are processed "
-	" as operands.  The evaluation of the "
-	"expression depends on the number of operands as follows:]{"
-	"[+0?Evaluates to false.]"
-	"[+1?True if argument is not an empty string.]"
-	"[+2?If first operand is \b!\b, the result is True if the second "
-		"operand an empty string.  Otherwise, it is evaluated "
-		"as one of the unary expressions defined below.  If the "
-		"unary operator is invalid and the second argument is \b--\b,"
-		"then the first argument is processed as an option argument.]"
-	"[+3?If first operand is \b!\b, the result is True if the second "
-		"and third operand evaluated as a unary expression is False.  "
-		"Otherwise, the three operands are evaluaged as one of the  "
-		"binary expressions listed below.]"
-	"[+4?If first operand is \b!\b, the result is True if the next "
-		"three operands are a valid binary expression that is False.]"
-"}"
-"[If any \afile\a is of the form \b/dev/fd/\b\an\a, then file descriptor "
-	"\an\a is checked.]"
-"[+?Unary expressions can be one of the following:]{"
-	"[+-a \afile\a?True if \afile\a exists, obsolete.]"
-	"[+-b \afile\a?True if \afile\a exists and is a block special file.]"
-	"[+-c \afile\a?True if \afile\a exists and is a character special "
-		"file.]"
-	"[+-d \afile\a?True if \afile\a exists and is a directory.]"
-	"[+-e \afile\a?True if \afile\a exists.]"
-	"[+-f \afile\a?True if \afile\a exists and is a regular file.]"
-	"[+-g \afile\a?True if \afile\a exists and has its set-group-id bit "
-		"set.]"
-	"[+-h \afile\a?True if \afile\a exists and is a symbolic link.]"
-	"[+-k \afile\a?True if \afile\a exists and has its sticky bit on.]"
-#if SHOPT_TEST_L
-	"[+-l \afile\a?True if \afile\a exists and is a symbolic link.]"
-#endif
-	"[+-n \astring\a?True if length of \astring\a is non-zero.]"
-	"[+-o \aoption\a?True if the shell option \aoption\a is enabled.]"
-	"[+-p \afile\a?True if \afile\a exists and is a pipe or fifo.]"
-	"[+-r \afile\a?True if \afile\a exists and is readable.]"
-	"[+-s \afile\a?True if \afile\a exists and has size > 0.]"
-	"[+-t \afildes\a?True if file descriptor number \afildes\a is "
-		"open and is associated with a terminal device.]"
-	"[+-u \afile\a?True if \afile\a exists and has its set-user-id bit "
-		"set.]"
-	"[+-v \avarname\a?True if \avarname\a is a valid variable name that is set.]"
-	"[+-w \afile\a?True if \afile\a exists and is writable.]"
-	"[+-x \afile\a?True if \afile\a exists and is executable.  For a "
-		"directory it means that it can be searched.]"
-	"[+-z \astring\a?True if \astring\a is a zero length string.]"
-	"[+-G \afile\a?True if \afile\a exists and group is the effective "
-		"group id of the current process.]"
-	"[+-L \afile\a?True if \afile\a exists and is a symbolic link.]"
-	"[+-N \afile\a?True if \afile\a exists and has been modified since "
-		"it was last read.]"
-	"[+-O \afile\a?True if \afile\a exists and owner is the effective "
-		"user id of the current process.]"
-	"[+-R \avarname\a?True if \avarname\a is a name reference.]"
-	"[+-S \afile\a?True if \afile\a exists and is a socket.]"
-"}"
-"[+?Binary expressions can be one of the following:]{"
-	"[+\astring1\a = \astring2\a?True if \astring1\a is equal to "
-		"\astring2\a.]"
-	"[+\astring1\a == \astring2\a?True if \astring1\a is equal to "
-		"\astring2\a.]"
-	"[+\astring1\a != \astring2\a?True if \astring1\a is not equal to "
-		"\astring2\a.]"
-	"[+\anum1\a -eq \anum2\a?True if numerical value of \anum1\a is "
-		"equal to \anum2\a.]"
-	"[+\anum1\a -ne \anum2\a?True if numerical value of \anum1\a is not "
-		"equal to \anum2\a.]"
-	"[+\anum1\a -lt \anum2\a?True if numerical value of \anum1\a is less "
-		"than \anum2\a.]"
-	"[+\anum1\a -le \anum2\a?True if numerical value of \anum1\a is less "
-		"than or equal to \anum2\a.]"
-	"[+\anum1\a -gt \anum2\a?True if numerical value of \anum1\a is "
-		"greater than \anum2\a.]"
-	"[+\anum1\a -ge \anum2\a?True if numerical value of \anum1\a is "
-		"greater than or equal to \anum2\a.]"
-	"[+\afile1\a -nt \afile2\a?True if \afile1\a is newer than \afile2\a "
-		"or \afile2\a does not exist.]"
-	"[+\afile1\a -ot \afile2\a?True if \afile1\a is older than \afile2\a "
-		"or \afile2\a does not exist.]"
-	"[+\afile1\a -ef \afile2\a?True if \afile1\a is another name for "
-		"\afile2\a.  This will be true if \afile1\a is a hard link "
-		"or a symbolic link to \afile2\a.]"
-"}"
-"\n"
-"\n[expression]\n"
-"\n"
-"[+EXIT STATUS?]{"
-	"[+0?Indicates that the specified expression is True.]"
-	"[+1?Indicates that the specified expression is False.]"
-	"[+>1?An error occurred.]"
-"}"
-
-"[+SEE ALSO?\blet\b(1), \bexpr\b(1)]"
-;
-
 const char test_opchars[]	= "HLNRSVOGCaeohrwxdcbfugkv"
 #if SHOPT_TEST_L
 	"l"

src/cmd/ksh93/include/test.h

@@ -61,7 +61,6 @@ extern int test_unop(Shell_t*,int, const char*);
 extern int test_inode(const char*, const char*);
 extern int test_binop(Shell_t*,int, const char*, const char*);
 
-extern const char	sh_opttest[];
 extern const char	test_opchars[];
 extern const char	e_argument[];
 extern const char	e_missing[];

src/cmd/ksh93/sh.1

@@ -5494,7 +5494,7 @@ The command only expands parameters.
 .br
 .ne 2
 .TP
-\(dg \f3\|. \f2name\^\fP \*(OK \f2arg\^\fP .\|.\|. \*(CK
+\(dg \f3\|.\fP \f2name\^\fP \*(OK \f2arg\^\fP .\|.\|. \*(CK
 If
 .I name\^
 is a function defined with the
@@ -5525,6 +5525,10 @@ command and the original positional parameters are restored upon completion.
 Otherwise the positional parameters are unchanged.
 The exit status is the exit status of the last command executed.
 .TP
+\f3[\fP \f2expression\fP \f3]\fP
+The \f3[\fP command is the same as \f3test\fP, with the exception that an
+additional closing \f3]\fP argument is required. See \f3test\fP below.
+.TP
 \f3alias\fP \*(OK \f3\-ptx\fP \*(CK  \*(OK \f2name\fP\*(OK \f3=\fP\f2value\^\fP  \*(CK \*(CK .\|.\|.
 .B alias\^
 with no arguments prints the list of aliases
@@ -7198,6 +7202,24 @@ in the parent shell). Equivalent to
 .BR kill\ -s\ STOP\ "$$" ,
 except that it accepts no operands and refuses to suspend a login shell.
 .TP
+\f3test\fP \f2expression\fP
+The \f3test\fP and \f3[\fP commands execute conditional expressions similar
+to those specified for the \f3[[\fP compound command under
+.I Conditional Expressions
+above, but with several important differences. The \f3=\fP, \f3==\fP and
+\f3!=\fP operators test for string (in)equality without pattern matching;
+the \f3==\fP variant is nonstandard and should not be used. The \f3=\(ap\fP,
+\f3<\fP, \f3>\fP, \f3&&\fP and \f3||\fP operators are not available. Most
+importantly, as \f3test\fP and \f3[\fP are simple regular commands, field
+splitting and file name generation \f2are\fP performed on all their
+arguments and all aspects of regular shell grammar (such as redirection)
+remain active. This is usually harmful, so care must be taken to quote
+arguments and expansions to avoid this. There are also certain inherent
+grammatical ambiguities in the expressions. To avoid the many pitfalls
+arising from these issues, the \f3[[\fP compound command should be used
+instead. The primary purpose of the \f3test\fP and \f3[\fP commands is
+compatibility with other shells that lack \f3[[\fP.
+.TP
 \f3times\fP
 Displays the accumulated user and system CPU times, one line with the times
 used by the shell and another with those used by all of the shell's child