test.1: Add note regarding -a,-o and () obsolecence

[thebugfixers_pm.me]

Summary

Main change:

• Add BINARY PRIMARIES section to highlight move to && and ||.

Also:

• Minor tidy to NAME and SYNOPSIS section

Background regarding binary primaries:

See Shellcheck SC2166 and its reference to upstream POSIX which marked -a, -o and ( or ) as obsolescent in 2008 and removed from the standard in 2024.

[bcr]

Small issue found. Maybe mandoc -Tlint finds others?

bin/test/test.1

316

You need to make a line break after a sentence stop.

[ziaee]

Hi! Thank you so much for working on this!

bin/test/test.1

38–45

The change to NAME is a nice catch, thanks! The existing style of SYNOPSIS appears correct, please revert proposed changes to SYNOPSIS or explain them further.

295

Please add a .Pp after line 295

296

The prevailing style for shell operators in our manual pages is Li, as seen in sh(1).

314

Please add a .Pp after line 314.

317

Information about standards conformance belongs in STANDARDS.

325

Caveats belong in CAVEATS.

335

In fact, this entire section should be in CAVEATS.

[thebugfixers_pm.me]

Thank you both for your comments. I will modify in-line with your suggestions.

@ziaee, regarding your CAVEATS comment, the main reason I didn't do it was the original version also had a number of items interspersed that should have been in CAVEATS, such perhaps all or part of GRAMMAR AMBIGUITY or the comment The -a operator has higher precedence than the -o operator. or the comment Some shells may provide a builtin test command which is similar or identical to this utility. Consult the builtin(1) manual page. or If file is a symbolic link, test will fully dereference it and then evaluate the expression against the file referenced, except for the -h and -L primaries.. So my edit was intended to try to remain roughly "in-keeping" with the original version.

But your comment is fair that the entire section should be re-headed CAVEATS. Do you want me to pull in the existing outliers into CAVEATS too ?

[ziaee]

But your comment is fair that the entire section should be re-headed CAVEATS. Do you want me to pull in the existing outliers into CAVEATS too ?

Yes, I would say that that's a good idea. Aligning with the standards outlined in mdoc(7) increases predictability, which improves accessibility to the manual subsystem as a whole.

[thebugfixers_pm.me]

In D57892#1327334, @ziaee wrote:

Aligning with the standards outlined in mdoc(7)

Well, this is my first ever man page edit (only doing it because I was tidying up some shell scripts elsewhere in src/ and shellcheck suddenly started telling me about SC2166.

So I can't promise 100% alignment, perhaps more of a generous contribution in the right direction. :)

[thebugfixers_pm.me]

Change in line with reviewer comments.

Removed BUGS entirely as it as effectively as discussion about -a and -o which are in effect obsolete and removed from the standards as per the main gist of this diff. People should be using && and || by default at this stage.

The EXAMPLES as it was a discussion telling people to use POSIX functionality instead of a non-standard primary -nt, so it was moved into CAVEATS. I did consider replacing it, but looking at e.g. OpenBSD, they omit EXAMPLES altogether and I am minded to agree because test is a straightforward primitive and does not really need examples.

[thebugfixers_pm.me]

Missed an extra move of an -a and -o item into CAVEATS

[des]

I don't think you understand the purpose of a manual page.

bin/test/test.1

274

No.

280

No.

286–291

This belongs here, not in CAVEATS.

287

This is test(1), not sh(1).

303

There is nothing historical about -a and -o; they are still supported and widely used.

404

That's not your call to make. We have no plans to remove them.