Package: make
Version: 4.4.1-3
Severity: minor
Tags: patch
Dear maintainer,
* 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=0 -ww -z < "man page"
[Use
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) 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?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
an.tmac:<stdin>:151: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
an.tmac:<stdin>:204: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
* 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: forky/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.16.12+deb14+1-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 make depends on:
ii libc6 2.41-12
make recommends no packages.
Versions of packages make suggests:
pn make-doc <none>
-- no debconf information
Input file is make.1
Output from "mandoc -T lint make.1": (shortened list)
1 WARNING: skipping paragraph macro: PP after SH
1 WARNING: skipping paragraph macro: sp after SH
-.-.
Output from
test-nroff -mandoc -t -ww -z make.1: (shortened list)
2 Use macro '.B' for one argument or split the argument.
2 .BR is for at least 2 arguments, got 1
-.-.
Change '-' (\-) to '\(en' (en-dash) for a (numeric) range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
make.1:398:Copyright \(co 1992-1993, 1996-2023 Free Software Foundation, Inc.
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-"
(begin of an option or end of options)
then use "\-\-".
make.1:120:considered and which are applied---everything interesting about how
make.1:207:\fB\--jobserver-style=\fR\fIstyle\fR
-.-.
Reduce space between words.
make.1:75:.IR README .)
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
207:\fB\--jobserver-style=\fR\fIstyle\fR
246:When running multiple jobs in parallel with \fB-j\fR, ensure the output of
-.-.
Split lines longer than 80 characters (fill completly
an A4 sized page line on a terminal)
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 237, length 86
\fB\-o\fR \fIfile\fR, \fB\-\-old\-file\fR=\fIfile\fR,
\fB\-\-assume\-old\fR=\fIfile\fR
Line 351, length 117
\fB\-W\fR \fIfile\fR, \fB\-\-what\-if\fR=\fIfile\fR,
\fB\-\-new\-file\fR=\fIfile\fR, \fB\-\-assume\-new\fR=\fIfile\fR
Longest line is number 351 with 117 characters
-.-.
Remove unnecessary double font change (e.g., \fR\fI) in a row or (better)
use a two-fonts macro.
207:\fB\--jobserver-style=\fR\fIstyle\fR
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
make.1:268:Print the data base (rules and variable values) that results from
make.1:273:switch (see below).
make.1:302:Touch files (mark them up to date without really changing them)
make.1:404:Foundation; either version 3 of the License, or (at your option) any
later
-.-.
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).
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
207:\fB\--jobserver-style=\fR\fIstyle\fR
-.-.
Change "---" to an em dash
120:considered and which are applied---everything interesting about how
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
make.1:1:.TH MAKE 1 "26 May 2023" "GNU" "User Commands"
make.1:124:.BI \-\-debug "[=FLAGS]"
make.1:331:.BI \-\-shuffle "[=MODE]"
make.1:397:.SH "COPYRIGHT"
-.-.
Add "\&" after an ellipsis, when it does not end a sentence.
6:[\fIOPTION\fR]... [\fITARGET\fR]...
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
an.tmac:<stdin>:151: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
an.tmac:<stdin>:204: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- make.1 2025-11-14 00:32:34.611558606 +0000
+++ make.1.new 2025-11-14 02:39:40.007221402 +0000
@@ -1,11 +1,10 @@
-.TH MAKE 1 "26 May 2023" "GNU" "User Commands"
+.TH MAKE 1 "26 May 2023" GNU "User Commands"
.SH NAME
make \- GNU Make utility to maintain groups of programs
.SH SYNOPSIS
.B make
-[\fIOPTION\fR]... [\fITARGET\fR]...
+[\fIOPTION\fR]...\& [\fITARGET\fR]...
.SH DESCRIPTION
-.LP
The
.I make
utility will determine automatically which pieces of a large program need to
@@ -72,7 +71,7 @@ or
.I Makefile
because it appears prominently near the beginning of a directory
listing, right near other important files such as
-.IR README .)
+.IR README .)
The first name checked,
.IR GNUmakefile ,
is not recommended for most makefiles. You should use this name if you have a
@@ -88,7 +87,6 @@ updates a target if it depends on prereq
that have been modified since the target was last modified,
or if the target does not exist.
.SH OPTIONS
-.sp 1
.TP 0.5i
\fB\-b\fR, \fB\-m\fR
These options are ignored for compatibility with other versions of
@@ -117,11 +115,11 @@ Print debugging information in addition
The debugging information says which files are being considered for
remaking, which file-times are being compared and with what results,
which files actually need to be remade, which implicit rules are
-considered and which are applied---everything interesting about how
+considered and which are applied\(emeverything interesting about how
.B make
decides what to do.
.TP 0.5i
-.BI \-\-debug "[=FLAGS]"
+.BI \-\-debug [=FLAGS]
Print debugging information in addition to normal processing.
If the
.I FLAGS
@@ -148,7 +146,7 @@ for debugging while remaking makefiles,
shows all recipes that are run even if they are silent, and
.I why
shows the reason
-.BR make
+.B make
decided to rebuild each target. Use
.I none
to disable all previous debugging flags.
@@ -201,10 +199,10 @@ option, the last one is effective.
If the
.B \-j
option is given without an argument,
-.BR make
+.B make
will not limit the number of jobs that can run simultaneously.
.TP 0.5i
-\fB\--jobserver-style=\fR\fIstyle\fR
+\fB\-\-jobserver-style=\fIstyle\fR
The style of jobserver to use. The
.I style
may be one of
@@ -243,7 +241,7 @@ on account of changes in
Essentially the file is treated as very old and its rules are ignored.
.TP 0.5i
\fB\-O\fR[\fItype\fR], \fB\-\-output\-sync\fR[=\fItype\fR]
-When running multiple jobs in parallel with \fB-j\fR, ensure the output of
+When running multiple jobs in parallel with \fB\-j\fR, ensure the output of
each job is collected together rather than interspersed with output from
other jobs. If
.I type
@@ -328,7 +326,7 @@ Turn off
.BR \-w ,
even if it was turned on implicitly.
.TP 0.5i
-.BI \-\-shuffle "[=MODE]"
+.BI \-\-shuffle [=MODE]
Enable shuffling of goal and prerequisite ordering.
.I MODE
is one of
@@ -394,8 +392,8 @@ See the chapter ``Problems and Bugs'' in
This manual page contributed by Dennis Morse of Stanford University.
Further updates contributed by Mike Frysinger. It has been reworked by Roland
McGrath. Maintained by Paul Smith.
-.SH "COPYRIGHT"
-Copyright \(co 1992-1993, 1996-2023 Free Software Foundation, Inc.
+.SH COPYRIGHT
+Copyright \(co 1992\(en1993, 1996\(en2023 Free Software Foundation, Inc.
This file is part of
.IR "GNU Make" .
.LP
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>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
-.-
For a style guide use
mandoc -T lint
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
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)
-.-
