Subject: Re: bug#33097: test has filetest -a but man page doesn't list it

From: Bernhard Voelker <[email-masked]>
Date: Sat, 20 Oct 2018 00:56:01 +0200

On 10/19/18 10:48 PM, Martin Schulte wrote:
> Hello coreutils maintainers,
> 
> test in coreutils 8.30 supports the unary -a test (is the same as -e) but
> this is not listed on the manpage (in bash 4.4.12 "help test" does list
> it).
> 
> I can imagine good reasons to kick out the unary -a but I think it
> then should be kicked out of program and man page (or it should be listed
> in the man page, maybe as deprecated).

Good spot, thanks for the report.

The '-a FILE' primary is supported since "the beginning", and even the
POSIX spec mentions this unlucky thing:

  http://pubs.opengroup.org/onlinepubs/9699919799/utilities/test.html

  An early proposal used the KornShell -a primary (with the same meaning),
  but this was changed to -e because there were concerns about the high
  probability of humans confusing the -a primary with the -a binary operator.

I don't think we can remove that primary without breaking some scripts,
so it's probably best to document it.
The attached, proposed patch add documentation both in the man and
texinfo format.

Comments?

Have a nice day,
Berny
From 0a7d57e7fc9fdfdf3e7f6f4e5c3a5a9a7891c099 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <[email-masked]>
Date: Sat, 20 Oct 2018 00:49:30 +0200
Subject: [PATCH] doc: document (highly discouraged) 'test -a FILE' primary

* doc/coreutils.texi (node File type tests): Add a sentence about the
supported-yet-discouraged primary '-a FILE'.
* src/test.c (usage): Likewise.

The documentation of that primary was missing since "the beginning".
Fixes https://bugs.gnu.org/33097
---
 doc/coreutils.texi | 4 ++++
 src/test.c         | 3 +++
 2 files changed, 7 insertions(+)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 512443aa6..0a7aab133 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -13007,6 +13007,10 @@ terminal.
 
 @end table
 
+This implementation of @command{test} also supports the primary @samp{-a FILE}
+as an alias of @samp{-e FILE} for compatibility with some shell implementations,
+e.g. @command{bash}, but its use is highly discouraged both to avoid ambiguity
+and for portability reasons.
 
 @node Access permission tests
 @subsection Access permission tests
diff --git a/src/test.c b/src/test.c
index aae45012a..f255d06b1 100644
--- a/src/test.c
+++ b/src/test.c
@@ -792,6 +792,9 @@ INTEGER may also be -l STRING, which evaluates to the length of STRING.\n\
 \n\
 NOTE: Binary -a and -o are inherently ambiguous.  Use 'test EXPR1 && test\n\
 EXPR2' or 'test EXPR1 || test EXPR2' instead.\n\
+This implementation of 'test' also supports the primary '-a FILE' as an\n\
+alias of '-e FILE' for compatibility reasons, but its use is highly\n\
+discouraged for obvious reasons.\n\
 "), stdout);
       fputs (_("\
 \n\
-- 
2.19.1