FreeBSD 9.3: Awk manpage fails to cite the ampersand subsitution operation that occurs in sub/gsub functions, eg: $ echo damn! | awk '{ sub(/!/, "&&&"); print }'
The AWK manpage used to be fairly nice (10+ years ago), and it really appears that somebody trashed it intentionally. The formatting is botched (wrapping around to the 1st column) and there are stupid comments such as: BUGS There are no explicit conversions between numbers and strings. To force an expression to be treated as a number add 0 to it; to force it to be treated as a string concatenate "" to it. The scope rules for variables in functions are a botch; the syntax is worse. That is just bullshit. 100% bullshit. The implicit conversions between numbers and strings is intentional, and part of many more modern scripting languages. And what is wrong with the scope rules? Variables are local to the function; how is that a botch? And what is so bad about the syntax? It's just a stupid comment intended to insult - the obvious question is "for what purpose?" Did the author create something better than K&R, justifying such "authoritive insult?" AWK is part of the entire suite of Unix tools, and it is designed to do what AWK is designed to do, as M4 is designed to do what it is designed to do, and the same for SH, SED, YACC, LEX, PS ... and in that role, is nearly flawless. If anything is to be criticized, it would properly be the failure to process all 8-bit bytes equally (eg, without special consideration to 0x0), or the fact that nawk closes stdin if requested, or some other quirks that have been fixed in mawk/gawk. AWK is a very important and critical part of the Unix tool set, and honestly, this manpage is of highly inappropriate quality in comparison.
The awk man page was imported from OpenBSD, which fixes formatting and should cover all awk(1) options. Can you check whether that fixes your issue?
^Triage: this manual page is from upstream. Hopefully after all these years the problem has been fixed.