[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug-patch] [PATCH] patch.man: Some fixes in the manual
From: |
Bjarni Ingi Gislason |
Subject: |
[bug-patch] [PATCH] patch.man: Some fixes in the manual |
Date: |
Tue, 5 Mar 2019 20:26:20 +0000 |
User-agent: |
Mutt/1.5.20 (2009-12-10) |
Enable and fix warnings from 'test-groff'.
<patch.man>:699 (macro BR): only 1 argument, but more are expected
<patch.man>:1060 (macro BR): only 1 argument, but more are expected
Output is from: test-groff -b -e -mandoc -T utf8 -rF0 -t -w w -z
[ "test-groff" is a developmental version of "groff" ]
#####
Correct the indentation of a .RS/.RE block inside a .TP block.
####
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\- (here to the string '\*=').
440:\fB--fuzz\fR=\fInum\fP option into account.
#####
Use the correct macro for the font change of a single argument.
699:.BR \*=suffix
#####
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7) [package "manpages"]).
587:and if the first command is an append (i.e. it should have been a delete)
790:(e.g. with
978:(e.g. the file
991:(e.g. with
1025:(e.g. a shell script) to accomplish them should accompany the patch.
#####
Wrong distance between sentences or protect the indicator.
a) Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) [package "manpages"] and "info groff".
Or
b) Adjust space between sentences (two spaces),
c) or protect the indicator by adding "\&" after it.
The "indicator" is an "end-of-sentence character" (.!?).
The amount of space in the output can then be controlled with the
".ss" request.
310:endings. On Windows, reads and writes do transform line endings by default,
587:and if the first command is an append (i.e. it should have been a delete)
762:given in context diff headers. Unless specified in the time stamps,
852:Marshall T. Rose and Einar A. Stefferud,
1193:\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.
patch.man: line 63 length 83
If the entire diff is indented by a consistent amount, if lines end in
\s-1CRLF\s0,
patch.man: line 307 length 82
line endings. This option is needed on \s-1POSIX\s0 systems when applying
patches
patch.man: line 370 length 83
to ignore up to that many lines of context in looking for places to install a
hunk.
#####
Remove superfluous quotation marks (") from the argument of a
single-font macro.
331:.B "\*=dry\-run"
396:.B "\*=help"
893:.B "\-Np1"
#####
Split a punctuation mark from a single argument for a two-fonts marco
1060:.BR \-p0.
Signed-off-by: Bjarni Ingi Gislason <address@hidden>
#####
---
patch.man | 44 ++++++++++++++++++++++++++------------------
1 file changed, 26 insertions(+), 18 deletions(-)
diff --git a/patch.man b/patch.man
index e919eae..03b7703 100644
--- a/patch.man
+++ b/patch.man
@@ -60,7 +60,8 @@ Thus you could feed an article or message containing a
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.
@@ -304,10 +305,11 @@ 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.)
@@ -323,12 +325,12 @@ anything else.
.TP
\fB\-D\fP \fIdefine\fP or \fB\*=ifdef=\fP\fIdefine\fP
Use the
-.BR #ifdef " .\|.\|. " #endif
+.BR #ifdef " .\|.\|.\& " #endif
construct to mark changes, with
.I define
as the differentiating symbol.
.TP
-.B "\*=dry\-run"
+.B \*=dry\-run
Print the results of applying the patches without actually changing any files.
.TP
\fB\-e\fP or \fB\*=ed\fP
@@ -393,7 +395,7 @@ The default value of this option is given by the value of
the
.B PATCH_GET
environment variable if it is set; if not, the default value is zero.
.TP
-.B "\*=help"
+.B \*=help
Print a summary of options and exit.
.TP
\fB\-i\fP \fIpatchfile\fP or \fB\*=input=\fP\fIpatchfile\fP
@@ -437,7 +439,7 @@ lines from the patch; in the merge format, this section is
missing. The merge
format is the default.
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.
@@ -468,28 +470,34 @@ you keep your files in a different directory than the
person who sent
out the patch.
For example, supposing the file name in the patch file was
.Sp
+.LP
.RS
\fB/u/howard/src/blurfl/blurfl.c\fP
.RE
.Sp
+.IP "" 3
setting
.B \-p0
gives the entire file name unmodified,
.B \-p1
gives
.Sp
+.LP
.RS
\fBu/howard/src/blurfl/blurfl.c\fP
.RE
.Sp
+.IP "" 3
without the leading slash,
.B \-p4
gives
.Sp
+.LP
.RS
\fBblurfl/blurfl.c\fP
.RE
.Sp
+.IP "" 3
and not specifying
.B \-p
at all just gives you \fBblurfl.c\fP.
@@ -584,7 +592,7 @@ If it can, you are asked if you want to have the
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
@@ -696,7 +704,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
@@ -759,7 +767,7 @@ is
.TP
\fB\-Z\fP or \fB\*=set\-utc\fP
Set the modification and access times of patched files from time stamps
-given in context diff headers. Unless specified in the time stamps,
+given in context diff headers. Unless specified in the time stamps,
assume that the context diff headers use Coordinated Universal Time
(\s-1UTC\s0, often known as \s-1GMT\s0). Also see the
.B \-T
@@ -787,7 +795,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
@@ -849,7 +857,7 @@ controlling terminal; used to get answers to questions
asked of the user
.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 <URL:ftp://ftp.isi.edu/in-notes/rfc934.txt> (1985-01).
.SH "NOTES FOR PATCH SENDERS"
@@ -890,7 +898,7 @@ by telling them which directory to
to, and which
.B patch
options to use. The option string
-.B "\-Np1"
+.B \-Np1
is recommended.
Test your procedure by pretending to be a recipient and applying
your patch to a copy of the original files.
@@ -975,7 +983,7 @@ Take care not to send out reversed patches, since it makes
people wonder
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.in"
@@ -988,7 +996,7 @@ have the recipients apply the patch with the
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
@@ -1022,7 +1030,7 @@ empty files, empty directories, or special files such as
symbolic links.
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
@@ -1057,7 +1065,7 @@ the
option's operand was optional, and a bare
.B \-p
was equivalent to
-.BR \-p0.
+.BR \-p0 .
The
.B \-p
option now requires an operand, and
@@ -1190,7 +1198,7 @@ Please report bugs via email to
.BR <address@hidden> .
.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.
--
2.20.1
--
Bjarni I. Gislason
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [bug-patch] [PATCH] patch.man: Some fixes in the manual,
Bjarni Ingi Gislason <=