bin/47726: The patch(1) man page could use improvements, especially regarding its backup methods [patch included]

[Bug Hunting <bughunting%xs4all.nl@localhost>]

>Number:         47726
>Category:       bin
>Synopsis:       The patch(1) man page could use improvements, especially 
>regarding its backup methods [patch included]
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Apr 07 23:45:00 +0000 2013
>Originator:     Bug Hunting
>Release:        NetBSD 6.99.19
>Description:

The patch(1) man page could be made more informative about its
backup methods and suffixes (especially with numbered backups) and
prefixes, including its options influencing all this.

Also, the exit status information should be put in its own section
(even though the `DIAGNOSTICS' section is valid on itself, and
should indeed be kept), as mandoc_mdoc(7) explains as follows:

       EXIT STATUS
       This section documents the command exit status for section 1, 6, and 8
       utilities.  Historically, this information was described in
       DIAGNOSTICS, a practise that is now discouraged.

and

       DIAGNOSTICS
       Documents error conditions.  This is most useful in section 4 manuals.
       Historically, this section was used in place of EXIT STATUS for manuals
       in sections 1, 6, and 8; however, this practise is discouraged.

.


>How-To-Repeat:

"man -s 1 patch".

Experiment with patch(1) creating backups, as well as its prefix
and suffix options.


>Fix:

Apply the proposed patch attached.  Its top lines provide a proposed
commit message, to which a reference to this PR should be added.

When done, optionally pull-up changes to NetBSD release branches.

Also, optionally report back committed changes to OpenBSD and / or
DragonFly BSD, where the current patch(1) code originates from (as
mentioned in its CVS log, e.g., the commit message of patch.1, r1.13).

Final note: I don't know if there is / was any relation (codewisely
spoken) between src/usr.bin/patch and pkgsrc/devel/nbpatch(/files),
e.g., which would be the case if the latter was essentially a pkgsrc
version of the former; it at least seems that both lead there own
lives, creating redundant code by the way (perhaps merge the code
of the two into one, so they are consistent with one another?); in
either way, which is the reason for bringing this up, the patch
attached does _not_ (fully) cleanly apply to
pkgsrc/devel/nbpatch/files/nbpatch.1, but probably shouldn't be
applied there anyway, in the first place.

--bp/iNruPH9dso1Pn
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="patch.1_1.16.patch"

- Clarify relation between `-B', `-V' (and `-b'), and `-z' options;
- mention `-z' and `SIMPLE_BACKUP_SUFFIX' are only used for simple backups;
- augment the `Backup Files' section in multiple ways, including
  explaining the (non changeable) suffix used with numbered backups;
- put exit status information (from the `DIAGNOSTICS' section) in
  its own `EXIT STATUS' section (and put it in the correctly ordered
  location);
- bump date.

The `EXIT STATUS' change, most notably the macro improvements
included with it, is inspired by OpenBSD's src/usr.bin/patch/patch.1
revision 1.26 commit.

From Bug Hunting.

---

Index: src/usr.bin/patch/patch.1
===================================================================
RCS file: /cvsroot/src/usr.bin/patch/patch.1,v
retrieving revision 1.16
diff -u -r1.16 patch.1
--- src/usr.bin/patch/patch.1   29 Jan 2013 09:30:11 -0000      1.16
+++ src/usr.bin/patch/patch.1   7 Apr 2013 21:17:05 -0000
@@ -21,7 +21,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 18, 2008
+.Dd April 7, 2013
 .Dt PATCH 1
 .Os
 .Sh NAME
@@ -88,13 +88,17 @@
 .It Fl B Ar backup-prefix , Fl Fl prefix Ar backup-prefix
 Causes the next argument to be interpreted as a prefix to the backup file
 name.
-If this argument is specified, any argument to
+This option overrides the
+.Fl V
+and
 .Fl z
-will be ignored.
+options.
 .It Fl b , Fl Fl backup
 Save a backup copy of the file before it is modified.
 By default the original file is saved with a backup extension of
 .Qq .orig
+(or an alternative suffix given with
+.Fl z )
 unless the file already has a numbered backup, in which case a numbered
 backup is made.
 This is equivalent to specifying
@@ -306,9 +310,12 @@
 .Nm
 patchers.
 .It Fl z Ar backup-ext , Fl Fl suffix Ar backup-ext
-Causes the next argument to be interpreted as the backup extension, to be
-used in place of
+Causes the next argument to be interpreted as the simple backup extension,
+to be used in place of
 .Qq .orig .
+The
+.Fl B
+option overrides this option.
 .It Fl Fl posix
 Enables strict
 .St -p1003.1-2004
@@ -479,18 +486,27 @@
 and patch a file in the blurfl directory directly from the article containing
 the patch.
 .Ss Backup Files
-By default, the patched version is put in place of the original, with
-the original file backed up to the same name with the extension
-.Qq .orig ,
-or as specified by the
+By default a
+.Dq simple
+backup is made, in which the patched version is put in place of the original,
+with the original file backed up to the same name with the extension
+.Qq .orig .
+The type of backup to be made, as well as the prefix or suffix, can be changed
+as specified by the
 .Fl B ,
 .Fl V ,
-or
+and
 .Fl z
 options.
-The extension used for making backup files may also be specified in the
+The extension used for making simple backup files may also be specified in the
 .Ev SIMPLE_BACKUP_SUFFIX
 environment variable, which is overridden by the options above.
+For numbered backups, a suffix of
+.Qq \&.~ Ns Em n Ns ~
+is used, with
+.Em n
+starting at 1, and raised by one with each additional
+numbered backup file.
 .Pp
 If the backup file is a symbolic or hard link to the original file,
 .Nm
@@ -546,7 +562,7 @@
 .Fl Fl posix
 option has been specified.
 .It Ev SIMPLE_BACKUP_SUFFIX
-Extension to use for backup file names instead of
+Extension to use for simple backup file names instead of
 .Qq .orig .
 .It Ev TMPDIR
 Directory to put temporary files in; default is
@@ -567,33 +583,33 @@
 .Nm
 prompts the user
 .El
-.Sh DIAGNOSTICS
-Too many to list here, but generally indicative that
-.Nm
-couldn't parse your patch file.
-.Pp
-The message
-.Qq Hmm...
-indicates that there is unprocessed text in the patch file and that
-.Nm
-is attempting to intuit whether there is a patch in that text and, if so,
-what kind of patch it is.
-.Pp
+.Sh EXIT STATUS
 The
 .Nm
 utility exits with one of the following values:
 .Pp
-.Bl -tag -width Ds -compact -offset indent
-.It \&0
+.Bl -tag -width Ds -offset indent -compact
+.It 0
 Successful completion.
-.It \&1
+.It 1
 One or more lines were written to a reject file.
-.It \*[Gt]\&1
+.It \*(Gt1
 An error occurred.
 .El
 .Pp
 When applying a set of patches in a loop it behooves you to check this
 exit status so you don't apply a later patch to a partially patched file.
+.Sh DIAGNOSTICS
+Too many to list here, but generally indicative that
+.Nm
+couldn't parse your patch file.
+.Pp
+The message
+.Qq Hmm...
+indicates that there is unprocessed text in the patch file and that
+.Nm
+is attempting to intuit whether there is a patch in that text and, if so,
+what kind of patch it is.
 .Sh SEE ALSO
 .Xr diff 1
 .Sh STANDARDS

--bp/iNruPH9dso1Pn--

>Unformatted:
 --bp/iNruPH9dso1Pn
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline