adds a detailed synopsis to the man page; sorts options in

the description list and adds missing arguments; syncs usage()

written with a lot of useful advice by jmc@

ok by jmc@

1 files changed, 90 insertions, 52 deletions

diff --git a/usr.bin/patch/patch.1 b/usr.bin/patch/patch.1
index 9d12b8b12bd..feba068130c 100644
--- a/usr.bin/patch/patch.1
+++ b/usr.bin/patch/patch.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: patch.1,v 1.17 2003/10/31 20:20:45 millert Exp $
+.\"	$OpenBSD: patch.1,v 1.18 2007/04/18 21:52:24 sobrado Exp $
 .\" Copyright 1986, Larry Wall
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -27,8 +27,22 @@
 .Nd apply a diff file to an original
 .Sh SYNOPSIS
 .Nm patch
-.Op Cm options
+.Bk -words
+.Op Fl bCcEeflNnRstuv
+.Op Fl B Ar backup-prefix
+.Op Fl D Ar symbol
+.Op Fl d Ar directory
+.Op Fl F Ar max-fuzz
+.Op Fl i Ar patchfile
+.Op Fl o Ar out-file
+.Op Fl p Ar strip-count
+.Op Fl r Ar rej-name
+.Op Fl V Cm t | nil | never
+.Op Fl x Ar number
+.Op Fl z Ar backup-ext
+.Op Fl Fl posix
 .Op Ar origfile Op Ar patchfile
+.Ek
 .Nm patch
 .Pf \*(Lt Ar patchfile
 .Sh DESCRIPTION
@@ -71,6 +85,15 @@ below).
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
+.It Xo
+.Fl B Ar backup-prefix ,
+.Fl Fl prefix Ar backup-prefix
+.Xc
+Causes the next argument to be interpreted as a prefix to the backup file
+name.
+If this argument is specified, any argument to
+.Fl z
+will be ignored.
 .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
@@ -78,27 +101,18 @@ By default the original file is saved with a backup extension of
 unless the file already has a numbered backup, in which case a numbered
 backup is made.
 This is equivalent to specifying
-.Qo Fl V Ar existing Qc .
+.Qo Fl V Cm existing Qc .
 This option is currently the default but that will change in a future release.
-.It Fl B , Fl Fl prefix
-Causes the next argument to be interpreted as a prefix to the backup file
-name.
-If this argument is specified, any argument to
-.Fl z
-will be ignored.
+.It Fl C , Fl Fl check
+Checks that the patch would apply cleanly, but does not modify anything.
 .It Fl c , Fl Fl context
 Forces
 .Nm
 to interpret the patch file as a context diff.
-.It Fl C , Fl Fl check
-Checks that the patch would apply cleanly, but does not modify anything.
-.It Fl d , Fl Fl directory
-Causes
-.Nm
-to interpret the next argument as a directory, and
-.Xr cd 1
-to it before doing anything else.
-.It Fl D , Fl Fl ifdef
+.It Xo
+.Fl D Ar symbol ,
+.Fl Fl ifdef Ar symbol
+.Xc
 Causes
 .Nm
 to use the
@@ -108,17 +122,37 @@ The argument following will be used as the differentiating symbol.
 Note that, unlike the C compiler, there must be a space between the
 .Fl D
 and the argument.
+.It Xo
+.Fl d Ar directory ,
+.Fl Fl directory Ar directory
+.Xc
+Causes
+.Nm
+to interpret the next argument as a directory, and
+.Xr cd 1
+to it before doing anything else.
+.It Fl E , Fl Fl remove-empty-files
+Causes
+.Nm
+to remove output files that are empty after the patches have been applied.
+This option is useful when applying patches that create or remove files.
 .It Fl e , Fl Fl ed
 Forces
 .Nm
 to interpret the patch file as an
 .Xr ed 1
 script.
-.It Fl E , Fl Fl remove-empty-files
-Causes
+.It Xo
+.Fl F Ar max-fuzz ,
+.Fl Fl fuzz Ar max-fuzz
+.Xc
+Sets the maximum fuzz factor.
+This option only applies to context diffs, and causes
 .Nm
-to remove output files that are empty after the patches have been applied.
-This option is useful when applying patches that create or remove files.
+to ignore up to that many lines 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, and it may not be set to more than
+the number of lines of context in the context diff, ordinarily 3.
 .It Fl f , Fl Fl force
 Forces
 .Nm
@@ -134,17 +168,9 @@ This option does not suppress commentary; use
 .Fl s
 for that.
 .It Xo
-.Fl F Ns Aq Ar number ,
-.Fl Fl fuzz Aq Ar number
+.Fl i Ar patchfile ,
+.Fl Fl input Ar patchfile
 .Xc
-Sets the maximum fuzz factor.
-This option only applies to context diffs, and causes
-.Nm
-to ignore up to that many lines 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, and it may not be set to more than
-the number of lines of context in the context diff, ordinarily 3.
-.It Fl i , Fl Fl input
 Causes the next argument to be interpreted as the input file name
 (i.e. a patchfile).
 This option may be specified multiple times.
@@ -155,21 +181,24 @@ Any sequence of whitespace in the pattern line will match any sequence
 in the input file.
 Normal characters must still match exactly.
 Each line of the context must still match a line in the input file.
-.It Fl n , Fl Fl normal
-Forces
-.Nm
-to interpret the patch file as a normal diff.
 .It Fl N , Fl Fl forward
 Causes
 .Nm
 to ignore patches that it thinks are reversed or already applied.
 See also
 .Fl R .
-.It Fl o , Fl Fl output
+.It Fl n , Fl Fl normal
+Forces
+.Nm
+to interpret the patch file as a normal diff.
+.It Xo
+.Fl o Ar out-file ,
+.Fl Fl output Ar out-file
+.Xc
 Causes the next argument to be interpreted as the output file name.
 .It Xo
-.Fl p Ns Aq Ar number ,
-.Fl Fl strip Aq Ar number
+.Fl p Ar strip-count ,
+.Fl Fl strip Ar strip-count
 .Xc
 Sets the pathname strip count,
 which controls how pathnames found in the patch file are treated,
@@ -209,8 +238,6 @@ Whatever you end up with is looked for either in the current directory,
 or the directory specified by the
 .Fl d
 option.
-.It Fl r , Fl Fl reject-file
-Causes the next argument to be interpreted as the reject file name.
 .It Fl R , Fl Fl reverse
 Tells
 .Nm
@@ -240,6 +267,11 @@ Luckily, most patches add or change lines rather than delete them, so most
 reversed normal diffs will begin with a delete, which will fail, triggering
 the heuristic.)
 .It Xo
+.Fl r Ar rej-name ,
+.Fl Fl reject-file Ar rej-name
+.Xc
+Causes the next argument to be interpreted as the reject file name.
+.It Xo
 .Fl s , Fl Fl quiet ,
 .Fl Fl silent
 .Xc
@@ -260,11 +292,10 @@ and assume that patches are reversed if they look like they are.
 Forces
 .Nm
 to interpret the patch file as a unified context diff (a unidiff).
-.It Fl v , Fl Fl version
-Causes
-.Nm
-to print out its revision header and patch level.
-.It Fl V , Fl Fl version-control
+.It Xo
+.Fl V Cm t | nil | never ,
+.Fl Fl version-control Cm t | nil | never
+.Xc
 Causes the next argument to be interpreted as a method for creating
 backup file names.
 The type of backups made can also be given in the
@@ -287,22 +318,29 @@ option are like the GNU Emacs
 variable; they also recognize synonyms that are more descriptive.
 The valid values are (unique abbreviations are accepted):
 .Bl -tag -width Ds -offset indent
-.It t , numbered
+.It Cm t , numbered
 Always make numbered backups.
-.It nil , existing
+.It Cm nil , existing
 Make numbered backups of files that already have them,
 simple backups of the others.
-.It never , simple
+.It Cm never , simple
 Always make simple backups.
 .El
+.It Fl v , Fl Fl version
+Causes
+.Nm
+to print out its revision header and patch level.
 .It Xo
-.Fl x Ns Aq Ar number ,
-.Fl Fl debug Aq Ar number
+.Fl x Ar number ,
+.Fl Fl debug Ar number
 .Xc
 Sets internal debugging flags, and is of interest only to
 .Nm
 patchers.
-.It Fl z , Fl Fl suffix
+.It Xo
+.Fl z Ar backup-ext ,
+.Fl Fl suffix Ar backup-ext
+.Xc
 Causes the next argument to be interpreted as the backup extension, to be
 used in place of
 .Qq .orig .