timeout.1: Document non-POSIX options

[aly_aaronly.me]

Looks good to me. Thank you.

[ziaee]

Thanks for the patch! The mdoc(7) manual explains that it's important to use standardized sections wherever possible to reinforce the idea that people can jump directly to the relevant section. The COMPATIBILITY section is a GNU-ism. Please put this in the STANDARDS section. Other than that, looks good to me!

[temcbun_gmail.com]

In D56090#1282965, @ziaee wrote:

The COMPATIBILITY section is a GNU-ism.

Thanks, I didn't know that. I took that section from mv(1).

[temcbun_gmail.com]

Move non-POSIX options block in the STANDARDS section.

[ziaee]

Sorry to backtrack here (and to let this slip for a while), but I did a deeper dive in preparation for merging this. Looking at our utilities that are specified in POSIX.1-2024:

xargs:
options are non-standard FreeBSD extensions which may not be available on other operating systems.

ls:
are non-standard extensions.

what:
The -q option is a non-standard FreeBSD extension which may not be available on other operating systems.

cut:
The -w flag is an extension to the specification.

pax:
operations are extensions to the POSIX standard.

date:
With the exception of the -u option, all options are extensions to the standard.

patch:
The flags [-BCEFfstVvxz] and [--posix] are extensions to that specification.

env:
options are non-standard extensions supported by FreeBSD, but which may not be available on other operating systems.

find:
are extensions to IEEE Std 1003.1-2001 (“POSIX.1”).

Looking at GNU coreutils (which doesn't provide STANDARDS or COMPATIBILITY sections), they also have both long-options and -v.

The extended documentation for the mdoc language suggests we use are extensions to that specification..

https://mandoc.bsd.lv/mdoc/style/standards.html

[temcbun_gmail.com]

In D56090#1289449, @ziaee wrote:

Sorry to backtrack here (and to let this slip for a while), but I did a deeper dive in preparation for merging this. Looking at our utilities that are specified in POSIX.1-2024:

xargs:
options are non-standard FreeBSD extensions which may not be available on other operating systems.

ls:
are non-standard extensions.

what:
The -q option is a non-standard FreeBSD extension which may not be available on other operating systems.

cut:
The -w flag is an extension to the specification.

pax:
operations are extensions to the POSIX standard.

date:
With the exception of the -u option, all options are extensions to the standard.

patch:
The flags [-BCEFfstVvxz] and [--posix] are extensions to that specification.

env:
options are non-standard extensions supported by FreeBSD, but which may not be available on other operating systems.

find:
are extensions to IEEE Std 1003.1-2001 (“POSIX.1”).

Looking at GNU coreutils (which doesn't provide STANDARDS or COMPATIBILITY sections), they also have both long-options and -v.

The extended documentation for the mdoc language suggests we use are extensions to that specification..

https://mandoc.bsd.lv/mdoc/style/standards.html

Thank you! I would then adopt this wording here.

Looking at GNU coreutils (which doesn't provide STANDARDS or COMPATIBILITY sections)

By the way, I'm planning to move COMPATIBILITY section to STANDARDS in all the man pages that still have that.

[temcbun_gmail.com]

Use recommended wording for non-standard options.

[ziaee]

Thanks for doing this, and sorry again for the backtracking.

By the way, I'm planning to move COMPATIBILITY section to STANDARDS in all the man pages that still have that.

Greater standardization would be great, but the situation is not bad right now. It would also be hard, because what they're describing doesn't map 1:1. If you want to work on this I will happily review it, but I think you've been adding a lot of amazing new things and doing higher value cleanups. For example, many posix utilities we have are missing any mention of standard conformance at all. That would be much higher value, I think. I haven't dug into them because it's quite nuanced and I have lots of other stuff I'm doing.