On Tue, Dec 21, 2021 at 09:43:27AM +0100, Ingo Schwarze wrote:
> 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.
>
hi.
my concern was that we would change a piece of text that talked
generally about patch files (without overly describing the format) into
a specific reference to an exact file (.Ar patchfile). the former does
not generally exclude stdin, but the latter seemed to do so. or at least
leave some ambiguity.
so i hoped to avoid the issue with a simpler fix. still, as noted, i
didn;t feel it to be overly important since, as you say, the document
does then go on to explain things. and we do usually talk about how
things work in general, then flesh out differences.
> > 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".
>
heh, so the opposite of what i'm describing.
> So to first get the issue reported by chrisz@ out of the way, i
> committed the patch as-is.
>
sure, makes sense
> 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?
>
yes, because it seems to address all our points. on the other hand, i
can;t help but feel that the original wording was better, even if it has
the issue about not being clear that it should be a text file. it was
simpler and easier to understand.
would it work to reinstate that original wording ("patch will take a
patch file"), but somehow strongarm the second sentence ("If
patchfile is omitted") into one describing both that it shold be a text
file, and what happens if it is omitted?
i.e. leave the original wording of sentence 1, but adjust that of
sentence 2.
what do you think?
jmc
> 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
>
