Package: patch
Version: git repository
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 ' $' <file>" to find 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>:8: warning: missing closing delimiter in output comparison
operator; expected character 'f', got a newline
an.tmac:<stdin>:10: style: .TH missing third argument; consider document
modification date in ISO 8601 format (YYYY-MM-DD)
troff:<stdin>:421: warning: font name 'CW' is deprecated
an.tmac:<stdin>:691: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:1096: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split 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: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.6-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 patch depends on:
ii libc6 2.40-4
patch recommends no packages.
Versions of packages patch suggests:
pn diffutils-doc <none>
pn ed <none>
-- no debconf information
Input file is patch.man
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
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
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 -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 of 'diff -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)
-.-.
Output from "mandoc -T lint patch.man": (shortened list)
3 input text line longer than 80 bytes
1 missing date, using ""
1 undefined string, using ""
-.-.
Output from "test-groff -mandoc -t -ww -z patch.man": (shortened list)
1 .BI is for at least 2 arguments, got 1
1 .BR is for at least 2 arguments, got 1
2 Use macro '.B' for one argument or split argument."
1 font name 'CW' is deprecated
1 missing closing delimiter in output comparison operator; expected
character 'f', got a newline
-.-.
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 "\-\-".
patch.man:437:\fB--fuzz\fR=\fInum\fP option into account.
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
691:.BR \*=suffix
1096:.BI \-u
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
579:and if the first command is an append (i.e. it should have been a delete)
782:(e.g. with
974:(e.g. the file
987:(e.g. with
1021:(e.g. a shell script) to accomplish them should accompany the patch.
-.-.
Wrong distance 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 "\&".
306:endings. On Windows, reads and writes do transform line endings by default,
579:and if the first command is an append (i.e. it should have been a delete)
754:given in context diff headers. Unless specified in the timestamps,
782:(e.g. with
844:Marshall T. Rose and Einar A. Stefferud,
974:(e.g. the file
987:(e.g. with
1021:(e.g. a shell script) to accomplish them should accompany the patch.
1105:\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP),
-.-.
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.
Line 66, length 83
If the entire diff is indented by a consistent amount, if lines end in
\s-1CRLF\s0,
Line 303, length 82
line endings. This option is needed on \s-1POSIX\s0 systems when applying
patches
Line 366, length 83
to ignore up to that many lines of context in looking for places to install a
hunk.
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
4:.if t .sp .3
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:8: warning: missing closing delimiter in output comparison
operator; expected character 'f', got a newline
an.tmac:<stdin>:10: style: .TH missing third argument; consider document
modification date in ISO 8601 format (YYYY-MM-DD)
troff:<stdin>:421: warning: font name 'CW' is deprecated
an.tmac:<stdin>:691: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument."
an.tmac:<stdin>:1096: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument."
-.-
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
Add a space after '<' (redirection operator).
--- patch.man 2024-12-30 08:12:25.983923614 +0000
+++ patch.man.new 2024-12-30 09:26:22.426949470 +0000
@@ -5,7 +5,7 @@
.if n .sp
..
.ds Cw CW
-.if \n(.g .if f CR .ds Cw CR
+.if \n(.g .if F CR .ds Cw CR
.ds fC \f(\*(Cw
.TH PATCH 1 "" GNU
.SH NAME
@@ -19,7 +19,7 @@ patch \- apply a diff file to an origina
but usually just
.Sp
.BI "patch \-p" "num"
-.BI < patchfile
+.BI "< " patchfile
.SH DESCRIPTION
.B patch
takes a patch file
@@ -63,7 +63,8 @@ Thus you could feed an email message con
diff listing to
.BR patch ,
and it should work.
-If the entire diff is indented by a consistent amount, if lines end in
\s-1CRLF\s0,
+If the entire diff is indented by a consistent amount,
+if lines end in \s-1CRLF\s0,
or if a diff is encapsulated one or more times by prepending
"\fB\- \fP" to lines starting with "\fB\-\fP" as specified by Internet RFC 934,
this is taken into account.
@@ -300,10 +301,12 @@ is
Write all files in binary mode, except for standard output and
.BR /dev/tty .
When reading, disable the heuristic for transforming CRLF line endings into LF
-line endings. This option is needed on \s-1POSIX\s0 systems when applying
patches
+line endings.
+This option is needed on \s-1POSIX\s0 systems when applying patches
generated on non-\s-1POSIX\s0 systems to non-\s-1POSIX\s0 files.
(On \s-1POSIX\s0 systems, file reads and writes never transform line
-endings. On Windows, reads and writes do transform line endings by default,
+endings.
+On Windows, reads and writes do transform line endings by default,
and patches should be generated by
.B "diff\ \*=binary"
when line endings are significant.)
@@ -363,7 +366,8 @@ for that.
Set the maximum fuzz factor.
This option only applies to diffs that have context, and causes
.B patch
-to ignore up to that many lines of context in looking for places to install a
hunk.
+to ignore up to that many lines of context in looking for places to install
+a hunk.
Note that a larger fuzz factor increases the odds of a faulty patch.
The default fuzz factor is 2. A fuzz factor greater than or equal to the
number of lines of context in the context diff, ordinarily 3, ignores all
@@ -434,7 +438,7 @@ lines from the patch; in the merge forma
format is the default.
.Sp
This option implies \fB\*=forward\fP and does not take the
-\fB--fuzz\fR=\fInum\fP option into account.
+\fB\-\-fuzz\fR=\fInum\fP option into account.
.TP
\fB\-n\fP or \fB\*=normal\fP
Interpret the patch file as a normal diff.
@@ -576,7 +580,7 @@ If it can, you are asked if you want to
option set.
If it can't, the patch continues to be applied normally.
(Note: this method cannot detect a reversed patch if it is a normal diff
-and if the first command is an append (i.e. it should have been a delete)
+and if the first command is an append (i.e., it should have been a delete)
since appends always succeed, due to the fact that a null context matches
anywhere.
Luckily, most patches add or change lines rather than delete them, so most
@@ -688,7 +692,7 @@ or
and
.B \-z
or
-.BR \*=suffix
+.B \*=suffix
options specify the simple backup file name.
If none of these options are given, then a simple backup suffix is used;
it is the value of the
@@ -751,7 +755,8 @@ is
.TP
\fB\-Z\fP or \fB\*=set\-utc\fP
Set the modification and access times of patched files from timestamps
-given in context diff headers. Unless specified in the timestamps,
+given in context diff headers.
+Unless specified in the timestamps,
assume that the context diff headers use Coordinated Universal Time
(\s-1UTC\s0, often known as \s-1GMT\s0). Also see the
.B \-T
@@ -779,7 +784,7 @@ Due to the limitations of
.B diff
output format, these options cannot update the times of files whose
contents have not changed. Also, if you use these options, you should remove
-(e.g. with
+(e.g., with
.BR "make\ clean" )
all files that depend on the patched files, so that later invocations of
.B make
@@ -841,7 +846,7 @@ controlling terminal; used to get answer
.BR ed (1),
.BR merge (1).
.Sp
-Marshall T. Rose and Einar A. Stefferud,
+Marshall T.\& Rose and Einar A.\& Stefferud,
Proposed Standard for Message Encapsulation,
Internet RFC 934 <https://datatracker.ietf.org/doc/html/rfc934> (1985-01).
.SH "NOTES FOR PATCH SENDERS"
@@ -971,7 +976,7 @@ Take care not to send out reversed patch
whether they already applied the patch.
.PP
Try not to have your patch modify derived files
-(e.g. the file
+(e.g., the file
.B configure
where there is a line
.B "configure: configure.ac"
@@ -984,7 +989,7 @@ have the recipients apply the patch with
or
.B \*=set\-utc
option, and have them remove any unpatched files that depend on patched files
-(e.g. with
+(e.g., with
.BR "make\ clean" ).
.PP
While you may be able to get away with putting 582 diff listings into
@@ -1018,7 +1023,7 @@ empty files, empty directories, or speci
Nor can they represent changes to file metadata like ownership, permissions,
or whether one file is a hard link to another.
If changes like these are also required, separate instructions
-(e.g. a shell script) to accomplish them should accompany the patch.
+(e.g., a shell script) to accomplish them should accompany the patch.
.PP
.B patch
cannot tell if the line numbers are off in an
@@ -1093,7 +1098,7 @@ Spaces are optional in the following lis
.BI \-p " num"
.B \-R
.BI \-r " rejectfile"
-.BI \-u
+.B \-u
.in
.fi
.RE
@@ -1102,7 +1107,7 @@ Please report bugs via email to
.BR <[email protected]> .
.PP
If code has been duplicated (for instance with
-\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP),
+\fB#ifdef OLDCODE\fP .\|.\|.\& \fB#else .\|.\|.\& #endif\fP),
.B patch
is incapable of patching both versions, and, if it works at all, will likely
patch the wrong one, and tell you that it succeeded to boot.
