Re: rm.1: remove extraneous word
Hi Jason, Jason McIntyre wrote on Fri, Sep 03, 2021 at 07:47:19AM +0100: > On Thu, Sep 02, 2021 at 11:10:54PM +0100, Jason McIntyre wrote: >> i wonder if it was originally an attempt to not quote posix >> (or posix attempting to not quote bsd). posix refers to removing >> "directory entries", which seems more natural. Quite to the contrary. A wording "removes the entries" first appeared in AT System III UNIX (1980). I first see the specific wording "remove directory entries" in Version 10 AT UNIX in December 1989 and it was then also used by Cynthia Livingston on June 11, 1990 when she converted the page from man(7) to mdoc(7). So this predates POSIX.2 (1992). Not sure what XPG 3 said in 1989. The current wording of the .Nd and the first sentence of the DESCRIPTION was committed by Keith Bostic on August 12, 1990 with this commit message: new version of rm from scratch and the POSIX.2 description I'm surprised that Keith referred to POSIX.2 in 1990 even though the original POSIX.2 is usually quoted as "IEEE Std 1003.2-1992". I know that POSIX.2 drafts were being worked on in 1991, but apparently some were already in circulation in the summer of 1990. > on the other hand, the phrase "non-directory type files" is pretty > awful. posix is clearer i think, sticking to "directory entries > specified by each file argument".we could also use this: "directory > entries specified on the command line". but that would feel like > deliberately avoiding the term "file", which is clear and simple. > > just using "non-directory files" is also weird. i mean, you can very > much remove directory files. It is standard practice that the first paragraph of the DESCRIPTION describes default behaviour, then the option list describes modifications of this behaviour, in this case that -d and -r also remove directories. So regarding the content, there is nothing to fix. If you think the wording is awful, you could say The rm utility attempts to remove the files specified on the command line. By default, specifying a directory is an error. If the permissions ... or something similar. Since this is about wording, i would say it is your call. In any case, i agree with Theo that the .Nd should not be changed. Yours, Ingo
Re: rm.1: remove extraneous word
Unix has these things called hard links. As such, rm deletes a directory entry pointing to an inode which stores a file, but other directory entries could point at the same file. Introducing people to this vaguely is nice, so I thikn this should keep saying 'directory entries'. >On Thu, Sep 02, 2021 at 11:10:54PM +0100, Jason McIntyre wrote: >> On Thu, Sep 02, 2021 at 02:28:54PM -0700, Evan Silberman wrote: >> > Speaking of the first sentence of rm(1): >> > >> > Remove extraneous word from command description >> > >> > "non-directory files" reads more naturally and means the same thing as >> > "non-directory type files". >> > >> >> true. >> >> i wonder if it was originally an attempt to not quote posix >> (or posix attempting to not quote bsd). posix refers to removing >> "directory entries", which seems more natural. >> >> regardless, rm can remove both directory entries/non-directory type >> files as well as directories. although by default it does not remove >> directories, i wonder if we could just say: >> >> The >> .Nm >> utility >> attempts to remove any files specified on the command line. >> >> and NAME could be: >> >> - rm - remove directory entries >> + rm - remove files >> >> but maybe that is unixical heresy? >> >> jmc >> > >i cannot really make up my mind here. posix and other bsds all use >"remove directory entries" for NAME. i worry that my proposal would be >needless change, and a lessening of valid terminology. so i probably >reject my own proposal. > >on the other hand, the phrase "non-directory type files" is pretty >awful. posix is clearer i think, sticking to "directory entries >specified by each file argument".we could also use this: "directory >entries specified on the command line". but that would feel like >deliberately avoiding the term "file", which is clear and simple. > >just using "non-directory files" is also weird. i mean, you can very >much remove directory files. > >jmc > >> > diff --git a/bin/rm/rm.1 b/bin/rm/rm.1 >> > index a2526a36392..1be2bf31913 100644 >> > --- a/bin/rm/rm.1 >> > +++ b/bin/rm/rm.1 >> > @@ -46,7 +46,7 @@ >> > .Sh DESCRIPTION >> > The >> > .Nm >> > -utility attempts to remove the non-directory type files specified on the >> > +utility attempts to remove the non-directory files specified on the >> > command line. >> > If the permissions of the file do not permit writing, and the standard >> > input device is a terminal, the user is prompted (on the standard error >> > > >
Re: rm.1: remove extraneous word
On Thu, Sep 02, 2021 at 11:10:54PM +0100, Jason McIntyre wrote: > On Thu, Sep 02, 2021 at 02:28:54PM -0700, Evan Silberman wrote: > > Speaking of the first sentence of rm(1): > > > > Remove extraneous word from command description > > > > "non-directory files" reads more naturally and means the same thing as > > "non-directory type files". > > > > true. > > i wonder if it was originally an attempt to not quote posix > (or posix attempting to not quote bsd). posix refers to removing > "directory entries", which seems more natural. > > regardless, rm can remove both directory entries/non-directory type > files as well as directories. although by default it does not remove > directories, i wonder if we could just say: > > The > .Nm > utility > attempts to remove any files specified on the command line. > > and NAME could be: > > - rm - remove directory entries > + rm - remove files > > but maybe that is unixical heresy? > > jmc > i cannot really make up my mind here. posix and other bsds all use "remove directory entries" for NAME. i worry that my proposal would be needless change, and a lessening of valid terminology. so i probably reject my own proposal. on the other hand, the phrase "non-directory type files" is pretty awful. posix is clearer i think, sticking to "directory entries specified by each file argument".we could also use this: "directory entries specified on the command line". but that would feel like deliberately avoiding the term "file", which is clear and simple. just using "non-directory files" is also weird. i mean, you can very much remove directory files. jmc > > diff --git a/bin/rm/rm.1 b/bin/rm/rm.1 > > index a2526a36392..1be2bf31913 100644 > > --- a/bin/rm/rm.1 > > +++ b/bin/rm/rm.1 > > @@ -46,7 +46,7 @@ > > .Sh DESCRIPTION > > The > > .Nm > > -utility attempts to remove the non-directory type files specified on the > > +utility attempts to remove the non-directory files specified on the > > command line. > > If the permissions of the file do not permit writing, and the standard > > input device is a terminal, the user is prompted (on the standard error > >
Re: rm.1: remove extraneous word
> On Sep 2, 2021, at 4:05 PM, li...@wrant.com wrote: > > Do all manual pages need to be free form texts to suit non-technical > audiences? Yes? Who do you think the documentation is for?
Re: rm.1: remove extraneous word
Thu, 02 Sep 2021 14:28:54 -0700 Evan Silberman > Speaking of the first sentence of rm(1): Where is that discussion happening, how is it concerning the rm(1) manual page? > Remove extraneous word from command description What is the rationale for this, is it entirely missing or undisclosed publicly? > "non-directory files" reads more naturally and means the same thing as > "non-directory type files". > > diff --git a/bin/rm/rm.1 b/bin/rm/rm.1 > index a2526a36392..1be2bf31913 100644 > --- a/bin/rm/rm.1 > +++ b/bin/rm/rm.1 > @@ -46,7 +46,7 @@ > .Sh DESCRIPTION > The > .Nm > -utility attempts to remove the non-directory type files specified on the > +utility attempts to remove the non-directory files specified on the > command line. > If the permissions of the file do not permit writing, and the standard > input device is a terminal, the user is prompted (on the standard error > Hi Evan, Read carefully these pages, they include file types sections that explain well: https://man.openbsd.org/find.1#type https://man.openbsd.org/stat.2 why directories are file types too, and the wording for that particular matter: https://man.openbsd.org/rm.1 https://man.netbsd.org/rm.1 https://www.freebsd.org/cgi/man.cgi?rm https://www.gnu.org/software/coreutils/manual/html_node/rm-invocation.html https://pubs.opengroup.org/onlinepubs/9699919799/utilities/rm.html https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/utilities/rm.html https://pubs.opengroup.org/onlinepubs/9699919799.2016edition/utilities/rm.html https://pubs.opengroup.org/onlinepubs/9699919799.2013edition/utilities/rm.html https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/utilities/rm.html Do all manual pages need to be free form texts to suit non-technical audiences? -- Kind regards, Anton Lazarov MScEng EECSIT
Re: rm.1: remove extraneous word
On Thu, Sep 02, 2021 at 02:28:54PM -0700, Evan Silberman wrote: > Speaking of the first sentence of rm(1): > > Remove extraneous word from command description > > "non-directory files" reads more naturally and means the same thing as > "non-directory type files". > true. i wonder if it was originally an attempt to not quote posix (or posix attempting to not quote bsd). posix refers to removing "directory entries", which seems more natural. regardless, rm can remove both directory entries/non-directory type files as well as directories. although by default it does not remove directories, i wonder if we could just say: The .Nm utility attempts to remove any files specified on the command line. and NAME could be: - rm - remove directory entries + rm - remove files but maybe that is unixical heresy? jmc > diff --git a/bin/rm/rm.1 b/bin/rm/rm.1 > index a2526a36392..1be2bf31913 100644 > --- a/bin/rm/rm.1 > +++ b/bin/rm/rm.1 > @@ -46,7 +46,7 @@ > .Sh DESCRIPTION > The > .Nm > -utility attempts to remove the non-directory type files specified on the > +utility attempts to remove the non-directory files specified on the > command line. > If the permissions of the file do not permit writing, and the standard > input device is a terminal, the user is prompted (on the standard error >
rm.1: remove extraneous word
Speaking of the first sentence of rm(1): Remove extraneous word from command description "non-directory files" reads more naturally and means the same thing as "non-directory type files". diff --git a/bin/rm/rm.1 b/bin/rm/rm.1 index a2526a36392..1be2bf31913 100644 --- a/bin/rm/rm.1 +++ b/bin/rm/rm.1 @@ -46,7 +46,7 @@ .Sh DESCRIPTION The .Nm -utility attempts to remove the non-directory type files specified on the +utility attempts to remove the non-directory files specified on the command line. If the permissions of the file do not permit writing, and the standard input device is a terminal, the user is prompted (on the standard error
