Jason McIntyre wrote on Mon, Dec 20, 2021 at 04:13:19PM +0000: > i'm ok with your diff
Thanks for checking. > but it is slightly misleading in context of > reading from stdin. i suppose that is no biggie. I think i see why you say so. Speaking *formally*, what we usually do is describing what the utility does by default in the first sentence, then explain how command line options modify that behaviour below "The options are as follows". We could do that here, somewhat like this: patch reads a text file called the "patch file" from standard input, containing any of the four forms ... yadayada ... and applies those differences to an original text file ... Besides, usually, we would *not* show a SYNOPSIS line patch <patchfile In this particular case, however, typing "patch <patchfile" or maybe "patch -i patchfile" is so dominant in practice that focussing on it seems to help users more than adhering to formal practices. I think calling this "misleading" is a bit strong because very often, the first sentence in our manual pages describes the default or most important mode of operation and subsequent sentences modify that by detailing other modes. In this case, not only does the next sentence say what happens if no patch file is specified, but we also have the "patch <patchfile" line right above. > it would be simpler to just s/patch file/text file/ maybe? True, that would be simpler and not outright wrong. But in normal operation, patch(1) deals with many text files, so i worry that people might get confused as to which text file we are talking about. It seems valuable for the first sentence to make it clear that one among all these files is special and to introduce the term "patch file" or ".Ar patchfile". So to first get the issue reported by chrisz@ out of the way, i committed the patch as-is. We could say .Nm takes a text file called the .Sq patch file containing any of the four forms ... Do you think that is better, like in the patch below? Yours, Ingo Index: patch.1 =================================================================== RCS file: /cvs/src/usr.bin/patch/patch.1,v retrieving revision 1.34 diff -u -r1.34 patch.1 --- patch.1 21 Dec 2021 08:07:20 -0000 1.34 +++ patch.1 21 Dec 2021 08:37:54 -0000 @@ -47,8 +47,8 @@ .Pf \*(Lt Ar patchfile .Sh DESCRIPTION .Nm -takes the text file -.Ar patchfile +takes a text file called the +.Dq patch file containing any of the four forms of difference listing produced by the .Xr diff 1 @@ -56,7 +56,7 @@ producing a patched version. If .Ar patchfile -is omitted, or is a hyphen, the patch will be read from the standard input. +is omitted or is a hyphen, the patch file is read from the standard input. .Pp .Nm will attempt to determine the type of the diff listing, unless overruled by a
