Page MenuHomeFreeBSD

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

Authored by thebugfixers_pm.me on Fri, Jun 26, 7:50 PM.

Details

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.

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

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 requested changes to this revision.Fri, Jun 26, 9:35 PM
ziaee added a reviewer: manpages.

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.

This revision now requires changes to proceed.Fri, Jun 26, 9:35 PM

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 ?

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.

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. :)

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.

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

des requested changes to this revision.Sat, Jun 27, 8:48 PM
des added a subscriber: 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.

This revision now requires changes to proceed.Sat, Jun 27, 8:48 PM