Package: gawk
Version: 1:5.2.1-2+b1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:172: warning [page 2, line 21]: cannot break line
troff:<stdin>:250: warning [page 3, line 4]: cannot break line
troff:<stdin>:739: warning [page 6, line 48]: cannot break line
troff:<stdin>:918: warning [page 8, line 3]: cannot break line
troff:<stdin>:1406: warning [page 11, line 55]: cannot break line
an.tmac:<stdin>:1501: style: use of deprecated macro: .PD
an.tmac:<stdin>:1504: style: use of deprecated macro: .PD
an.tmac:<stdin>:1507: style: use of deprecated macro: .PD
an.tmac:<stdin>:1532: style: use of deprecated macro: .PD
an.tmac:<stdin>:1535: style: use of deprecated macro: .PD
an.tmac:<stdin>:1538: style: use of deprecated macro: .PD
troff:<stdin>:1644: warning [page 13, line 13]: cannot break line
troff:<stdin>:1738: warning [page 13, line 53]: cannot break line
troff:<stdin>:1786: warning [page 13, line 72]: cannot break line
troff:<stdin>:2244: warning [page 16, line 69]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages gawk depends on:
ii libc6 2.40-7
ii libgmp10 2:6.3.0+dfsg-3
ii libmpfr6 4.2.1-1+b2
ii libreadline8t64 8.2-6
ii libsigsegv2 2.14-1+b2
gawk recommends no packages.
Versions of packages gawk suggests:
pn gawk-doc <none>
-- no debconf information
Input file is gawk.1
Output from "mandoc -T lint gawk.1": (shortened list)
1 input text line longer than 80 bytes: patterns, the associ...
-.-.
Output from "test-nroff -mandoc -t -ww -z gawk.1": (shortened list)
9 cannot break line
-.-.
Find a repeated word
! 2367 --> the
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URL (web address)
172 .IR
https://www.gnu.org/software/gawk/manual/html_node/Debugger.html#Debugger .
250 .I https://www.gnu.org/software/gawk/manual/html_node/Options.html#Options
560 .I https://www.gnu.org/software/gawk/manual/html_node/Records.html
576 .IR https://www.gnu.org/software/gawk/manual/html_node/Fields.html .
632 .I
https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html
638 .IR
https://www.gnu.org/software/gawk/manual/html_node/Built_002din-Variables .
657 .I https://www.gnu.org/software/gawk/manual/html_node/PC-Using.html
721 .I https://www.gnu.org/software/gawk/manual/html_node/Field-Separators.html
739 .I
https://www.gnu.org/software/gawk/manual/html_node/Case_002dsensitivity.html
770 .I https://www.gnu.org/software/gawk/manual/html_node/Auto_002dset
777 .I
https://www.gnu.org/software/gawk/manual/html_node/Setting-the-rounding-mode
918 .IR
https://www.gnu.org/software/gawk/manual/html_node/Namespaces.html#Namespaces .
991 .I https://www.gnu.org/software/gawk/manual/html_node/Escape-Sequences
1131 .I https://www.gnu.org/software/gawk/manual/html_node/Regexp.html
1406 .I
https://www.gnu.org/software/gawk/manual/html_node/I_002fO-Functions.html#I_002fO-Functions
1463 .IR https://www.gnu.org/software/gawk/manual/html_node/Printf.html .
1608 .IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions .
1644 .IR
https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
.
1738 .I
https://www.gnu.org/software/gawk/manual/html_node/Gory-Details.html#Gory-Details
1786 .I
https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
1928 .IR https://www.gnu.org/software/gawk/manual/html_node/Time-Functions .
1948 .I
https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.html#Time-Functions
2050 .IR
https://www.gnu.org/software/gawk/manual/html_node/I18N-Functions.html#I18N-Functions
.
2201 .IR
https://www.gnu.org/software/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions
.
2244 .I
https://www.gnu.org/software/gawk/manual/html_node/Internationalization.html#Internationalization
2252 .IR https://www.gnu.org/software/gawk/manual/html_node/POSIX_002fGNU.html .
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
189:passing in options or source code (!) on the command line
223:the program. The trace is printed to standard error. Each ``op code''
255:Force arbitrary precision arithmetic on numbers. This option has
269:a member of the development team who is. If this situation
360:Signal the end of options. This is useful to allow further arguments to the
496:before processing the contents of the file. Similarly,
637:This list is purposely terse. For details, see
882:supports true multidimensional arrays. It does not require that
922:They may also be regular expressions. How the
1007:regular expression constants. These are written with a leading
1012:and passed to user-defined functions. Variables that have been so
1120:to skip it. If that is not done,
1443:returned to the calling function. If using a pipe, coprocess, or socket to
1462:are similar to those of C. For details, see
1566:to integers. Return the quotient of
1624:integers starting with 1. If the optional
1637:unchanged. The optional string
1927:formatting them. Details are provided in
2163:Functions may be called indirectly. To do this, assign
2221:natural language. Such strings are marked in the \*(AK program with
2308:The interval is in milliseconds. On systems that do not support
2436:Addison-Wesley, 2023. ISBN 9-780138-269722.
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 632, length 81
.I
https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html
Line 918, length 83
.IR
https://www.gnu.org/software/gawk/manual/html_node/Namespaces.html#Namespaces .
Line 1126, length 81
patterns, the associated statement is executed for each input record that
matches
Line 1406, length 94
.I
https://www.gnu.org/software/gawk/manual/html_node/I_002fO-Functions.html#I_002fO-Functions
Line 1644, length 95
.IR
https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
.
Line 1738, length 84
.I
https://www.gnu.org/software/gawk/manual/html_node/Gory-Details.html#Gory-Details
Line 1786, length 92
.I
https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
Line 1948, length 88
.I
https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.html#Time-Functions
Line 2050, length 91
.IR
https://www.gnu.org/software/gawk/manual/html_node/I18N-Functions.html#I18N-Functions
.
Line 2090, length 105
\fBdcngettext(\fIstring1\fB, \fIstring2\fB, \fInumber \fR[\fB, \fIdomain
\fR[\fB, \fIcategory\fR]]\fB)\fR
Line 2201, length 99
.IR
https://www.gnu.org/software/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions
.
Line 2244, length 100
.I
https://www.gnu.org/software/gawk/manual/html_node/Internationalization.html#Internationalization
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
160:.sp .5
2062:.sp .5
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
-.-
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of
a) an option in UTF-8 text
b) web addresses (URL).
632:.I
https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html
777:.I
https://www.gnu.org/software/gawk/manual/html_node/Setting-the-rounding-mode
-.-.
One space only after a possible end of sentence
(after a punctuation, that
can end a sentence).
gawk.1:223:the program. The trace is printed to standard error. Each ``op code''
gawk.1:255:Force arbitrary precision arithmetic on numbers. This option has
gawk.1:269:a member of the development team who is. If this situation
gawk.1:360:Signal the end of options. This is useful to allow further arguments
to the
gawk.1:496:before processing the contents of the file. Similarly,
gawk.1:637:This list is purposely terse. For details, see
gawk.1:882:supports true multidimensional arrays. It does not require that
gawk.1:922:They may also be regular expressions. How the
gawk.1:1007:regular expression constants. These are written with a leading
gawk.1:1012:and passed to user-defined functions. Variables that have been so
gawk.1:1073:.IB pattern " ? " pattern " : " pattern
gawk.1:1075:.BI ! " pattern"
gawk.1:1120:to skip it. If that is not done,
gawk.1:1224:.IB expr1 " ? " expr2 " : " expr3\/\fR.
gawk.1:1443:returned to the calling function. If using a pipe, coprocess, or
socket to
gawk.1:1462:are similar to those of C. For details, see
gawk.1:1566:to integers. Return the quotient of
gawk.1:1624:integers starting with 1. If the optional
gawk.1:1637:unchanged. The optional string
gawk.1:1927:formatting them. Details are provided in
gawk.1:2163:Functions may be called indirectly. To do this, assign
gawk.1:2221:natural language. Such strings are marked in the \*(AK program with
gawk.1:2308:The interval is in milliseconds. On systems that do not support
gawk.1:2436:Addison-Wesley, 2023. ISBN 9-780138-269722.
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-
Section headings (.SH and .SS) do not need quoting their arguments.
1265:.SS "I/O Statements"
-.-.
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:172: warning [page 2, line 21]: cannot break line
troff:<stdin>:250: warning [page 3, line 4]: cannot break line
troff:<stdin>:739: warning [page 6, line 48]: cannot break line
troff:<stdin>:918: warning [page 8, line 3]: cannot break line
troff:<stdin>:1406: warning [page 11, line 55]: cannot break line
an.tmac:<stdin>:1501: style: use of deprecated macro: .PD
an.tmac:<stdin>:1504: style: use of deprecated macro: .PD
an.tmac:<stdin>:1507: style: use of deprecated macro: .PD
an.tmac:<stdin>:1532: style: use of deprecated macro: .PD
an.tmac:<stdin>:1535: style: use of deprecated macro: .PD
an.tmac:<stdin>:1538: style: use of deprecated macro: .PD
troff:<stdin>:1644: warning [page 13, line 13]: cannot break line
troff:<stdin>:1738: warning [page 13, line 53]: cannot break line
troff:<stdin>:1786: warning [page 13, line 72]: cannot break line
troff:<stdin>:2244: warning [page 16, line 69]: cannot break line
-.-.
Additionally:
Put web addresses on a new line to avoid unnecessary line breaks.
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- gawk.1 2025-03-09 04:30:41.866159209 +0000
+++ gawk.1.new 2025-03-09 05:34:05.881667107 +0000
@@ -85,7 +85,7 @@ remains unique.
Additionally, every long option has a corresponding short
option, so that the option's functionality may be used from
within
-.B #!
+.B #!\&
executable scripts.
.SH OPTIONS
.I Gawk
@@ -157,7 +157,7 @@ The optional
.I file
argument specifies a file with a list
of commands for the debugger to execute non-interactively.
-.sp .5
+.sp 0.5
In this mode of execution,
.I gawk
loads the
@@ -169,7 +169,8 @@ and
.B \-\^\-include
options.
The debugger is documented in \*(EP; see
-.IR https://www.gnu.org/software/gawk/manual/html_node/Debugger.html#Debugger .
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Debugger.html#Debugger
.
.TP
.BI \-e " program-text\fR, \fP" \-\^\-source " program-text"
Use
@@ -184,9 +185,9 @@ Similar to
.BR \-f ,
however, this option is the last one processed.
This should be used with
-.B #!
+.B #!\&
scripts, particularly for CGI applications, to avoid
-passing in options or source code (!) on the command line
+passing in options or source code (!\&) on the command line
from a URL.
This option disables command-line variable assignments.
.TP
@@ -220,8 +221,9 @@ are treated as if they begin with an imp
.TP
.BR \-I ", " \-\^\-trace
Print the internal byte code names as they are executed when running
-the program. The trace is printed to standard error. Each ``op code''
-is preceded by a
+the program.
+The trace is printed to standard error.
+Each ``op code'' is preceded by a
.B +
sign in the output.
.TP
@@ -247,13 +249,14 @@ The library initialization routine is ex
Provide warnings about constructs that are
dubious or non-portable to other \*(AK implementations.
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Options.html#Options
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Options.html#Options
for the list of possible values for
.IR value .
.TP
.BR \-M ", " \-\^\-bignum
-Force arbitrary precision arithmetic on numbers. This option has
-no effect if
+Force arbitrary precision arithmetic on numbers.
+This option has no effect if
.I gawk
is not compiled to use the GNU MPFR and GMP libraries.
(In such a case,
@@ -266,9 +269,9 @@ This feature is
The primary
.I gawk
maintainer is no longer supporting it, although there is
-a member of the development team who is. If this situation
-changes, the feature
-will be removed from
+a member of the development team who is.
+If this situation changes,
+the feature will be removed from
.IR gawk .
.ig
Set
@@ -357,7 +360,8 @@ Per the
these options cause an immediate, successful exit.
.TP
.B \-\^\-
-Signal the end of options. This is useful to allow further arguments to the
+Signal the end of options.
+This is useful to allow further arguments to the
\*(AK program itself to start with a \*(lq\-\*(rq.
.PP
In compatibility mode,
@@ -429,13 +433,13 @@ the
and
.B \-\^\-include
options. If this variable does not exist, the default path is
-\fB".:/usr/local/share/awk"\fR.
+\fB".:/\:usr/\:local/\:share/\:awk"\fR.
(The actual directory may vary, depending upon how
.I gawk
was built and installed.)
If a file name given to the
.B \-f
-option contains a \*(lq/\*(rq character, no path search is performed.
+option contains a \*(lq/\:\*(rq character, no path search is performed.
.PP
The environment variable
.B AWKLIBPATH
@@ -443,7 +447,7 @@ specifies a search path to use when find
the
.B \-\^\-load
option. If this variable does not exist, the default path is
-\fB"/usr/local/lib/gawk"\fR.
+\fB"/\:usr/\:local/\:lib/\:gawk"\fR.
(The actual directory may vary, depending upon how
.I gawk
was built and installed.)
@@ -493,7 +497,8 @@ if a
rule exists,
.I gawk
executes the associated code
-before processing the contents of the file. Similarly,
+before processing the contents of the file.
+Similarly,
.I gawk
executes
the code associated with
@@ -557,7 +562,8 @@ Normally, records are separated by newli
records are separated by assigning values to the built-in variable
.BR RS .
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Records.html
+.br
+.I https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Records.html
for the details.
.SS Fields
As each input record is read,
@@ -573,7 +579,8 @@ and
.B FPAT
may be used to control input field splitting.
See the details, starting at
-.IR https://www.gnu.org/software/gawk/manual/html_node/Fields.html .
+.br
+.IR https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Fields.html .
.PP
Each field in the input record may be referenced by its position:
.BR $1 ,
@@ -629,13 +636,16 @@ fields are separated by commas.
Double-quotes may be used to enclose fields containing
commas, newlines, or doubled double-quotes.
See
-.I
https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Comma\-Separated\-Fields.html
for more details.
.SS Built-in Variables
.IR Gawk\^ "'s"
built-in variables are listed below.
-This list is purposely terse. For details, see
-.IR https://www.gnu.org/software/gawk/manual/html_node/Built_002din-Variables .
+This list is purposely terse.
+For details, see
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Built_002din\-Variables
.
.TP "\w'\fBFIELDWIDTHS\fR'u+1n"
.B ARGC
The number of command line arguments.
@@ -652,9 +662,10 @@ Array of command line arguments. The ar
\- 1.
.TP
.B BINMODE
-On non-POSIX systems, specifies use of \*(lqbinary\*(rq mode for all file I/O.
+On non-POSIX systems, specifies use of \*(lqbinary\*(rq mode for all file
I/\:O.
See
-.I https://www.gnu.org/software/gawk/manual/html_node/PC-Using.html
+.br
+.I https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:PC\-Using.html
for the details.
.TP
.B CONVFMT
@@ -718,7 +729,8 @@ as the field separator.
.B FS
The input field separator, a space by default.
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Field-Separators.html
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Field\-Separators.html
for the details.
.TP
.B FUNCTAB
@@ -736,7 +748,8 @@ array.
Controls the case-sensitivity of all regular expression
and string operations.
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Case_002dsensitivity.html
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Case_002dsensitivity.html
for details.
.TP
.B LINT
@@ -767,14 +780,16 @@ numbers, 53 by default.
The elements of this array provide access to information about the
running \*(AK program.
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Auto_002dset
+.br
+.I https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Auto_002dset
for the details.
.TP
.B ROUNDMODE
The rounding mode to use for arbitrary precision arithmetic on
numbers, by default \fB"N"\fR (IEEE-754 roundTiesToEven mode).
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Setting-the-rounding-mode
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Setting\-the\-rounding\-mode
for the details.
.TP
.B RS
@@ -879,10 +894,11 @@ statement may also be used to delete the
just by specifying the array name without a subscript.
.PP
.I gawk
-supports true multidimensional arrays. It does not require that
-such arrays be ``rectangular'' as in C or C++.
+supports true multidimensional arrays.
+It does not require that such arrays be ``rectangular'' as in C or C++.
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Arrays
+.br
+.I https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Arrays
for details.
.SS Namespaces
.I Gawk
@@ -915,14 +931,16 @@ namespace names. The names of additiona
may be used as namespace names or as simple identifiers in other
namespaces.
For more details, see
-.IR
https://www.gnu.org/software/gawk/manual/html_node/Namespaces.html#Namespaces .
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Namespaces.html#Namespaces
.
.SS Variable Typing And Conversion
Variables and fields
may be (floating point) numbers, or strings, or both.
-They may also be regular expressions. How the
-value of a variable is interpreted depends upon its context. If used in
-a numeric expression, it will be treated as a number; if used as a string
-it will be treated as a string.
+They may also be regular expressions.
+How the value of a variable is interpreted depends upon its context.
+If used in a numeric expression,
+it will be treated as a number;
+if used as a string it will be treated as a string.
.PP
To force a variable to be treated as a number, add zero to it; to force it
to be treated as a string, concatenate it with the null string.
@@ -988,29 +1006,31 @@ between double quotes (like \fB"value"\f
.I "escape sequences"
are recognized, as in C.
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Escape-Sequences
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Escape\-Sequences
for the details.
.SS Regexp Constants
A regular expression constant is a sequence of characters enclosed
between forward slashes (like
-.BR /value/ ).
+.BR /\:value/\: ).
.PP
The escape sequences described in the manual may also be used inside
constant regular expressions
(e.g.,
-.B "/[\ \et\ef\en\er\ev]/"
+.B "/\:[\ \et\ef\en\er\ev]/\:"
matches whitespace characters).
.PP
.I Gawk
provides
.I "strongly typed"
-regular expression constants. These are written with a leading
+regular expression constants.
+These are written with a leading
.B @
symbol (like so:
-.BR @/value/ ).
+.BR @/\:value/\: ).
Such constants may be assigned to scalars (variables, array elements)
-and passed to user-defined functions. Variables that have been so
-assigned have regular expression type.
+and passed to user-defined functions.
+Variables that have been so assigned have regular expression type.
.SH PATTERNS AND ACTIONS
\*(AK is a line-oriented language. The pattern comes first, and then the
action. Action statements are enclosed in
@@ -1066,13 +1086,13 @@ and to the pattern-action statements the
.B END
.B BEGINFILE
.B ENDFILE
-.BI / "regular expression" /
+.BI /\: "regular expression" /\:
.I "relational expression"
.IB pattern " && " pattern
.IB pattern " || " pattern
-.IB pattern " ? " pattern " : " pattern
+.IB pattern " ?\& " pattern " : " pattern
.BI ( pattern )
-.BI ! " pattern"
+.BI !\& " pattern"
.IB pattern1 ", " pattern2
.fi
.RE
@@ -1117,18 +1137,21 @@ is the empty string if the file was open
Otherwise, there is some problem with the file and the code should
use
.B nextfile
-to skip it. If that is not done,
+to skip it.
+If that is not done,
.I gawk
produces its usual fatal error for files that cannot be opened.
.PP
For
-.BI / "regular expression" /
-patterns, the associated statement is executed for each input record that
matches
-the regular expression.
+.BI /\: "regular expression" /\:
+patterns,
+the associated statement is executed for each input record
+that matches the regular expression.
Regular expressions are essentially the same as those in
.IR egrep (1).
See
-.I https://www.gnu.org/software/gawk/manual/html_node/Regexp.html
+.br
+.I https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Regexp.html
for the details on regular expressions.
.PP
A
@@ -1168,11 +1191,11 @@ and
.BR } .
Action statements consist of the usual assignment, conditional, and looping
statements found in most languages. The operators, control statements,
-and input/output statements
+and input/\:output statements
available are patterned after those in C.
.SS Operators
The operators in \*(AK, in order of decreasing precedence, are:
-.TP "\w'\fB*= /= %= ^=\fR'u+1n"
+.TP "\w'\fB*= /\:= %= ^=\fR'u+1n"
.BR ( \&.\|.\|. )
Grouping
.TP
@@ -1188,7 +1211,7 @@ Exponentiation.
.B "+ \- !"
Unary plus, unary minus, and logical negation.
.TP
-.B "* / %"
+.B "* /\: %"
Multiplication, division, and modulus.
.TP
.B "+ \-"
@@ -1198,7 +1221,7 @@ Addition and subtraction.
String concatenation.
.TP
.B "| |&"
-Piped I/O for
+Piped I/\:O for
.BR getline ,
.BR print ,
and
@@ -1221,7 +1244,7 @@ Logical OR.
.TP
.B ?:
The C conditional expression. This has the form
-.IB expr1 " ? " expr2 " : " expr3\/\fR.
+.IB expr1 " ? " expr2 " : " expr3\/\:\fR.
If
.I expr1
is true, the value of the expression is
@@ -1234,7 +1257,7 @@ and
.I expr3
is evaluated.
.TP
-.B "= += \-= *= /= %= ^="
+.B "= += \-= *= /\:= %= ^="
Assignment. Both absolute assignment
.BI ( var " = " value )
and operator-assignment (the other forms) are supported.
@@ -1262,8 +1285,8 @@ as follows:
\fB}\fR
.fi
.RE
-.SS "I/O Statements"
-The input/output statements are as follows:
+.SS I/\:O Statements
+The input/\:output statements are as follows:
.TP "\w'\fBprintf \fIfmt, expr-list\fR'u+1n"
\fBclose(\fIfile \fR[\fB, \fIhow\fR]\fB)\fR
Close an open file, pipe or coprocess.
@@ -1403,7 +1426,8 @@ Execute the command
and return the exit status.
(This may not be available on non-\*(PX systems.)
See
-.I
https://www.gnu.org/software/gawk/manual/html_node/I_002fO-Functions.html#I_002fO-Functions
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:I_002fO\-Functions.html#I_002fO\-Functions
for the full details on the exit status.
.PP
Additional output redirections are allowed for
@@ -1429,7 +1453,7 @@ The
function returns 1 on success, zero on end of file, and \-1 on an error.
If the
.IR errno (3)
-value indicates that the I/O operation may be retried,
+value indicates that the I/\:O operation may be retried,
and \fBPROCINFO["\fIinput\^\fP", "RETRY"]\fR
is set, then \-2 is returned instead of \-1, and further calls to
.B getline
@@ -1440,7 +1464,8 @@ is set to a string describing the proble
.PP
.BR NOTE :
Failure in opening a two-way socket results in a non-fatal error being
-returned to the calling function. If using a pipe, coprocess, or socket to
+returned to the calling function.
+If using a pipe, coprocess, or socket to
.BR getline ,
or from
.B print
@@ -1459,10 +1484,12 @@ The \*(AK versions of the
statement and
.B sprintf()
function
-are similar to those of C. For details, see
-.IR https://www.gnu.org/software/gawk/manual/html_node/Printf.html .
+are similar to those of C.
+For details, see
+.br
+.IR https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Printf.html .
.SS Special File Names
-When doing I/O redirection from either
+When doing I/\:O redirection from either
.B print
or
.B printf
@@ -1477,36 +1504,36 @@ allow access to open file descriptors in
parent process (usually the shell).
These file names may also be used on the command line to name data files.
The filenames are:
-.TP "\w'\fB/dev/stdout\fR'u+1n"
+.TP "\w'\fB/\:dev/\:stdout\fR'u+1n"
.B \-
The standard input.
.TP
-.B /dev/stdin
+.B /\:dev/\:stdin
The standard input.
.TP
-.B /dev/stdout
+.B /\:dev/\:stdout
The standard output.
.TP
-.B /dev/stderr
+.B /\:dev/\:stderr
The standard error output.
.TP
-.BI /dev/fd/\^ n
+.BI /\:dev/\:fd/\:\^ n
The file associated with the open file descriptor
.IR n .
.PP
The following special filenames may be used with the
.B |&
-coprocess operator for creating TCP/IP network connections:
+coprocess operator for creating TCP/\:IP network connections:
.TP
.PD 0
-.BI /inet/tcp/ lport / rhost / rport
+.BI /\:inet/\:tcp/\: lport /\: rhost /\: rport
.TP
.PD 0
-.BI /inet4/tcp/ lport / rhost / rport
+.BI /\:inet4/\:tcp/\: lport /\: rhost /\: rport
.TP
.PD
-.BI /inet6/tcp/ lport / rhost / rport
-Files for a TCP/IP connection on local port
+.BI /\:inet6/\:tcp/\: lport /\: rhost /\: rport
+Files for a TCP/\:IP connection on local port
.I lport
to
remote host
@@ -1517,33 +1544,33 @@ Use a port of
.B 0
to have the system pick a port.
Use
-.B /inet4
+.B /\:inet4
to force an IPv4 connection,
and
-.B /inet6
+.B /\:inet6
to force an IPv6 connection.
Plain
-.B /inet
+.B /\:inet
uses the system default (most likely IPv4).
Usable only with the
.B |&
-two-way I/O operator.
+two-way I/\:O operator.
.TP
.PD 0
-.BI /inet/udp/ lport / rhost / rport
+.BI /\:inet/\:udp/\: lport /\: rhost /\: rport
.TP
.PD 0
-.BI /inet4/udp/ lport / rhost / rport
+.BI /\:inet4/\:udp/\: lport /\: rhost /\: rport
.TP
.PD
-.BI /inet6/udp/ lport / rhost / rport
-Similar, but use UDP/IP instead of TCP/IP.
+.BI /\:inet6/\:udp/\: lport /\: rhost /\: rport
+Similar, but use UDP/\:IP instead of TCP/\:IP.
.SS Numeric Functions
\*(AK has the following built-in arithmetic functions:
.TP "\w'\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR'u+1n"
.BI atan2( y , " x" )
Return the arctangent of
-.I y/x
+.I y/\:x
in radians.
.TP
.BI cos( expr )
@@ -1563,7 +1590,8 @@ Truncate
.I num
and
.I denom
-to integers. Return the quotient of
+to integers.
+Return the quotient of
.I num
divided by
.I denom
@@ -1605,7 +1633,8 @@ number generator.
.SS String Functions
.I Gawk
has the following built-in string functions; details are provided in
-.IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions .
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:String\-Functions .
.TP "\w'\fBsprintf(\fIfmt\^\fB, \fIexpr-list\^\fB)\fR'u+1n"
\fBasort(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR
Return the number of elements in the source
@@ -1621,8 +1650,8 @@ comparing values, and replace the indice
sorted values
.I s
with sequential
-integers starting with 1. If the optional
-destination array
+integers starting with 1.
+If the optional destination array
.I d
is specified,
first duplicate
@@ -1634,14 +1663,16 @@ and then sort
leaving the indices of the
source array
.I s
-unchanged. The optional string
+unchanged.
+The optional string
.I how
controls the direction and the comparison mode.
Valid values for
.I how
are
described in
-.IR
https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
.
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:String\-Functions.html#String\-Functions
.
.IR s " and " d
are allowed to be the same array; this only makes sense when
supplying the third argument as well.
@@ -1735,7 +1766,8 @@ Use
to get a literal
.BR & .
(This must be typed as \fB"\e\e&"\fP; see
-.I
https://www.gnu.org/software/gawk/manual/html_node/Gory-Details.html#Gory-Details
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Gory\-Details.html#Gory\-Details
for a fuller discussion of the rules for ampersands
and backslashes in the replacement text of
.BR sub() ,
@@ -1783,7 +1815,8 @@ operator:
.IR re .
.ft R
See
-.I
https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:String\-Functions.html#String\-Functions
for a description of how the array
.I a
is filled if it is provided.
@@ -1924,8 +1957,10 @@ all work in terms of characters, not byt
.SS Time Functions
.I Gawk
provides the following functions for obtaining time stamps and
-formatting them. Details are provided in
-.IR https://www.gnu.org/software/gawk/manual/html_node/Time-Functions .
+formatting them.
+Details are provided in
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Time\-Functions .
.TP "\w'\fBsystime()\fR'u+1n"
\fBmktime(\fIdatespec\fR [\fB, \fIutc-flag\fR]\fB)\fR
Turn
@@ -1945,7 +1980,8 @@ is out of range,
.B mktime()
returns \-1.
See
-.I
https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.html#Time-Functions
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Time\-Functions.html#Time\-Functions
for the details of
.IR datespec .
.TP
@@ -2047,7 +2083,8 @@ or
The following functions may be used from within your AWK program for
translating strings at run-time.
For full details, see
-.IR
https://www.gnu.org/software/gawk/manual/html_node/I18N-Functions.html#I18N-Functions
.
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:I18N\-Functions.html#I18N\-Functions
.
.TP
\fBbindtextdomain(\fIdirectory \fR[\fB, \fIdomain\fR]\fB)\fR
Specify the directory where
@@ -2059,7 +2096,7 @@ will not or cannot be placed in the ``st
It returns the directory where
.I domain
is ``bound.''
-.sp .5
+.sp 0.5
The default
.I domain
is the value of
@@ -2140,7 +2177,7 @@ function f(p, q, a, b) # a and b ar
\&.\|.\|.
}
-/abc/ { .\|.\|.\& ; f(1, 2) ; .\|.\|.\& }
+/\:abc/\: { .\|.\|.\& ; f(1, 2) ; .\|.\|.\& }
.fi
.ft R
.RE
@@ -2160,7 +2197,8 @@ to return a value from a function. The
value is provided, or if the function returns by \*(lqfalling off\*(rq the
end.
.PP
-Functions may be called indirectly. To do this, assign
+Functions may be called indirectly.
+To do this, assign
the name of the function to be called, as a string, to a variable.
Then use the variable as if it were the name of a function, prefixed with an
.B @
@@ -2198,7 +2236,8 @@ interpreter with the
statement.
The full details are beyond the scope of this manual page;
see
-.IR
https://www.gnu.org/software/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions
.
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Dynamic\-Extensions.html#Dynamic\-Extensions
.
.SH SIGNALS
The
.I gawk
@@ -2217,8 +2256,9 @@ to dump the profile and function call st
.SH INTERNATIONALIZATION
String constants are sequences of characters enclosed in double
quotes. In non-English speaking environments, it is possible to mark
-strings in the \*(AK program as requiring translation to the local
-natural language. Such strings are marked in the \*(AK program with
+strings in the \*(AK program as
+requiring translation to the local natural language.
+Such strings are marked in the \*(AK program with
a leading underscore (\*(lq_\*(rq). For example,
.sp
.RS
@@ -2241,7 +2281,8 @@ might print
.B "bonjour, monde"
in France.
See
-.I
https://www.gnu.org/software/gawk/manual/html_node/Internationalization.html#Internationalization
+.br
+.I
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Internationalization.html#Internationalization
for the steps involved in producing and running a localizable
\*(AK program.
.SH GNU EXTENSIONS
@@ -2249,7 +2290,8 @@ for the steps involved in producing and
has a too-large number of extensions to \*(PX
.IR awk .
They are described in
-.IR https://www.gnu.org/software/gawk/manual/html_node/POSIX_002fGNU.html .
+.br
+.IR
https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:POSIX_002fGNU.html
.
All the extensions
can be disabled by
invoking
@@ -2305,7 +2347,8 @@ For connection to a remote host via sock
controls the number of retries, and
.B GAWK_MSEC_SLEEP
the interval between retries.
-The interval is in milliseconds. On systems that do not support
+The interval is in milliseconds.
+On systems that do not support
.IR usleep (3),
the value is rounded up to an integral number of seconds.
.PP
@@ -2364,7 +2407,7 @@ The original version of \*(UX
.I awk
was designed and implemented by Alfred Aho,
Peter Weinberger, and Brian Kernighan of Bell Laboratories.
-Ozan Yigit is the the current maintainer.
+Ozan Yigit is the current maintainer.
Brian Kernighan occasionally dabbles in its development.
.PP
Paul Rubin and Jay Fenlason,
@@ -2399,7 +2442,8 @@ please use the
program to report it.
.PP
Full instructions for reporting a bug are provided in
-.IR https://www.gnu.org/software/gawk/manual/html_node/Bugs.html .
+.br
+.IR https://www.gnu.org/\:software/\:gawk/\:manual/\:html_node/\:Bugs.html .
.I Please
carefully read and follow the instructions given there.
This will make bug reporting and resolution much easier for everyone involved.
@@ -2433,19 +2477,22 @@ and
.IR "The AWK Programming Language" ,
second edition,
Alfred V.\& Aho, Brian W.\& Kernighan, Peter J.\& Weinberger,
-Addison-Wesley, 2023. ISBN 9-780138-269722.
+Addison-Wesley, 2023.
+ISBN 9-780138-269722.
.PP
\*(EP,
Edition 5.3, shipped with the
.I gawk
source.
The current version of this document is available online at
-.IR https://www.gnu.org/software/gawk/manual .
+.br
+.IR https://www.gnu.org/\:software/\:gawk/\:manual .
.PP
The GNU
.B gettext
documentation, available online at
-.IR https://www.gnu.org/software/gettext .
+.br
+.IR https://www.gnu.org/\:software/\:gettext .
.SH EXAMPLES
.nf
Print and sort the login names of all users:
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
