Re: chgrp(1) & chown(8): mark -h and -R as mutually exclusive

[Frederic Nowak]

Hi Ingo,

> On 05 November 2015 at 19:02 Ingo Schwarze  wrote:
> 
> 
> Hi Frederic,
> 
> Theo de Raadt wrote on Thu, Nov 05, 2015 at 10:53:55AM -0700:
> > Frederic Nowak wrote:
> 
> >> the command line arguments -h and -R for chgrp and chown are
> >> mutually
> >> exclusive. The patch below changes the markup and the usage strings
> >> to
> >> make this clearer.
> 
> Thank you for working on OpenBSD manual pages!
> 
> > I don't think it makes it clearer; it makes it more confusing.
> > 
> > The usage messages of programs are not a sufficent grammer to
> > exactly
> > describe what conflicts with what.  Taken too far, it would bewilder
> > newcomers.
> 
> For a more comprehensive explanation of why this particular patch is
> rejected, look at this style guide entry:
> 
>   http://mdocml.bsd.lv/mdoc/style/synopsis.html
> 
> Other parts of the extended mdoc(7) documentation may sometimes
> come in handy for your work as well:
> 
>   http://mdocml.bsd.lv/mdoc/
> 
> Yours,
>   Ingo

Thanks, I hadn't seen that resource before. Looks very interesting!
Would it make sense to include a link, e.g. in the description section
of mdoc(7)?

By the way, is there a place where I could send patches for the
extended documentation etc? I only found a spelling mistake so far
(http://manpages.bsd.lv/toc.html "1. Chapter: Commnds"), but just in
case I find something else while reading it.

Cheers,
Frederic

> 
> 
> > > Index: bin/chmod/chgrp.1
> > > ===
> > > RCS file: /cvs/src/bin/chmod/chgrp.1,v
> > > retrieving revision 1.16
> > > diff -u -p -r1.16 chgrp.1
> > > --- bin/chmod/chgrp.1 21 Jan 2014 22:35:44 -  1.16
> > > +++ bin/chmod/chgrp.1 5 Nov 2015 17:09:11 -
> > > @@ -40,9 +40,7 @@
> > >  .Nd change group
> > >  .Sh SYNOPSIS
> > >  .Nm chgrp
> > > -.Op Fl h
> > > -.Oo
> > > -.Fl R
> > > +.Oo Fl h | R
> > >  .Op Fl H | L | P
> > >  .Oc
> > >  .Ar group
> > > Index: bin/chmod/chmod.c
> > > ===
> > > RCS file: /cvs/src/bin/chmod/chmod.c,v
> > > retrieving revision 1.38
> > > diff -u -p -r1.38 chmod.c
> > > --- bin/chmod/chmod.c 9 Oct 2015 01:37:06 -   1.38
> > > +++ bin/chmod/chmod.c 5 Nov 2015 17:09:11 -
> > > @@ -350,11 +350,11 @@ usage(void)
> > >   __progname, ischmod ? "mode" : "flags");
> > >   else
> > >   fprintf(stderr,
> > > - "usage: %s [-h] [-R [-H | -L | -P]] %s file ...\n",
> > > + "usage: %s [-h | -R [-H | -L | -P]] %s file ...\n",
> > >   __progname, ischown ? "owner[:group]" : "group");
> > >   if (ischown)
> > >   fprintf(stderr,
> > > - "   %s [-h] [-R [-H | -L | -P]] :group file ...\n",
> > > + "   %s [-h | -R [-H | -L | -P]] :group file ...\n",
> > >   __progname);
> > >   exit(1);
> > >  }
> > > Index: bin/chmod/chown.8
> > > ===
> > > RCS file: /cvs/src/bin/chmod/chown.8,v
> > > retrieving revision 1.19
> > > diff -u -p -r1.19 chown.8
> > > --- bin/chmod/chown.8 14 Sep 2015 20:06:58 -  1.19
> > > +++ bin/chmod/chown.8 5 Nov 2015 17:09:11 -
> > > @@ -37,17 +37,13 @@
> > >  .Nd change file owner and group
> > >  .Sh SYNOPSIS
> > >  .Nm chown
> > > -.Op Fl h
> > > -.Oo
> > > -.Fl R
> > > +.Oo Fl h | R
> > >  .Op Fl H | L | P
> > >  .Oc
> > >  .Ar owner Ns Op : Ns Ar group
> > >  .Ar
> > >  .Nm chown
> > > -.Op Fl h
> > > -.Oo
> > > -.Fl R
> > > +.Oo Fl h | R
> > >  .Op Fl H | L | P
> > >  .Oc
> > >  .Pf : Ar group
>

Re: chgrp(1) & chown(8): mark -h and -R as mutually exclusive

[Ingo Schwarze]

Hi Frederic,

Frederic Nowak wrote on Fri, Nov 06, 2015 at 08:58:14AM +0100:
> On 05 November 2015 at 19:02 Ingo Schwarze  wrote:

>>   http://mdocml.bsd.lv/mdoc/

> Thanks, I hadn't seen that resource before. Looks very interesting!
> Would it make sense to include a link, e.g. in the description section
> of mdoc(7)?

Maybe at some point, probably not yet, it is still very incomplete.
I only recently started mentioning it in public at all.

> By the way, is there a place where I could send patches for the
> extended documentation etc?

For

  http://mdocml.bsd.lv/mdoc/

for now, just to me, certainly not to .

> I only found a spelling mistake so far
> (http://manpages.bsd.lv/toc.html "1. Chapter: Commnds"), but just in
> case I find something else while reading it.

Wait, that's not the same thing, that's Kristaps' tutorial,
which is barely maintained at this point.

For

  http://manpages.bsd.lv/

probably  is the best address.

Yours,
  Ingo

Re: chgrp(1) & chown(8): mark -h and -R as mutually exclusive

[Theo de Raadt]

I don't think it makes it clearer; it makes it more confusing.

The usage messages of programs are not a sufficent grammer to exactly
describe what conflicts with what.  Taken too far, it would bewilder
newcomers.

> the command line arguments -h and -R for chgrp and chown are mutually
> exclusive. The patch below changes the markup and the usage strings to
> make this clearer.
> 
> Cheers,
> Frederic
> 
> Index: bin/chmod/chgrp.1
> ===
> RCS file: /cvs/src/bin/chmod/chgrp.1,v
> retrieving revision 1.16
> diff -u -p -r1.16 chgrp.1
> --- bin/chmod/chgrp.1 21 Jan 2014 22:35:44 -  1.16
> +++ bin/chmod/chgrp.1 5 Nov 2015 17:09:11 -
> @@ -40,9 +40,7 @@
>  .Nd change group
>  .Sh SYNOPSIS
>  .Nm chgrp
> -.Op Fl h
> -.Oo
> -.Fl R
> +.Oo Fl h | R
>  .Op Fl H | L | P
>  .Oc
>  .Ar group
> Index: bin/chmod/chmod.c
> ===
> RCS file: /cvs/src/bin/chmod/chmod.c,v
> retrieving revision 1.38
> diff -u -p -r1.38 chmod.c
> --- bin/chmod/chmod.c 9 Oct 2015 01:37:06 -   1.38
> +++ bin/chmod/chmod.c 5 Nov 2015 17:09:11 -
> @@ -350,11 +350,11 @@ usage(void)
>   __progname, ischmod ? "mode" : "flags");
>   else
>   fprintf(stderr,
> - "usage: %s [-h] [-R [-H | -L | -P]] %s file ...\n",
> + "usage: %s [-h | -R [-H | -L | -P]] %s file ...\n",
>   __progname, ischown ? "owner[:group]" : "group");
>   if (ischown)
>   fprintf(stderr,
> - "   %s [-h] [-R [-H | -L | -P]] :group file ...\n",
> + "   %s [-h | -R [-H | -L | -P]] :group file ...\n",
>   __progname);
>   exit(1);
>  }
> Index: bin/chmod/chown.8
> ===
> RCS file: /cvs/src/bin/chmod/chown.8,v
> retrieving revision 1.19
> diff -u -p -r1.19 chown.8
> --- bin/chmod/chown.8 14 Sep 2015 20:06:58 -  1.19
> +++ bin/chmod/chown.8 5 Nov 2015 17:09:11 -
> @@ -37,17 +37,13 @@
>  .Nd change file owner and group
>  .Sh SYNOPSIS
>  .Nm chown
> -.Op Fl h
> -.Oo
> -.Fl R
> +.Oo Fl h | R
>  .Op Fl H | L | P
>  .Oc
>  .Ar owner Ns Op : Ns Ar group
>  .Ar
>  .Nm chown
> -.Op Fl h
> -.Oo
> -.Fl R
> +.Oo Fl h | R
>  .Op Fl H | L | P
>  .Oc
>  .Pf : Ar group
> 

chgrp(1) & chown(8): mark -h and -R as mutually exclusive

[Frederic Nowak]

Hi there,

the command line arguments -h and -R for chgrp and chown are mutually
exclusive. The patch below changes the markup and the usage strings to
make this clearer.

Cheers,
Frederic

Index: bin/chmod/chgrp.1
===
RCS file: /cvs/src/bin/chmod/chgrp.1,v
retrieving revision 1.16
diff -u -p -r1.16 chgrp.1
--- bin/chmod/chgrp.1   21 Jan 2014 22:35:44 -  1.16
+++ bin/chmod/chgrp.1   5 Nov 2015 17:09:11 -
@@ -40,9 +40,7 @@
 .Nd change group
 .Sh SYNOPSIS
 .Nm chgrp
-.Op Fl h
-.Oo
-.Fl R
+.Oo Fl h | R
 .Op Fl H | L | P
 .Oc
 .Ar group
Index: bin/chmod/chmod.c
===
RCS file: /cvs/src/bin/chmod/chmod.c,v
retrieving revision 1.38
diff -u -p -r1.38 chmod.c
--- bin/chmod/chmod.c   9 Oct 2015 01:37:06 -   1.38
+++ bin/chmod/chmod.c   5 Nov 2015 17:09:11 -
@@ -350,11 +350,11 @@ usage(void)
__progname, ischmod ? "mode" : "flags");
else
fprintf(stderr,
-   "usage: %s [-h] [-R [-H | -L | -P]] %s file ...\n",
+   "usage: %s [-h | -R [-H | -L | -P]] %s file ...\n",
__progname, ischown ? "owner[:group]" : "group");
if (ischown)
fprintf(stderr,
-   "   %s [-h] [-R [-H | -L | -P]] :group file ...\n",
+   "   %s [-h | -R [-H | -L | -P]] :group file ...\n",
__progname);
exit(1);
 }
Index: bin/chmod/chown.8
===
RCS file: /cvs/src/bin/chmod/chown.8,v
retrieving revision 1.19
diff -u -p -r1.19 chown.8
--- bin/chmod/chown.8   14 Sep 2015 20:06:58 -  1.19
+++ bin/chmod/chown.8   5 Nov 2015 17:09:11 -
@@ -37,17 +37,13 @@
 .Nd change file owner and group
 .Sh SYNOPSIS
 .Nm chown
-.Op Fl h
-.Oo
-.Fl R
+.Oo Fl h | R
 .Op Fl H | L | P
 .Oc
 .Ar owner Ns Op : Ns Ar group
 .Ar
 .Nm chown
-.Op Fl h
-.Oo
-.Fl R
+.Oo Fl h | R
 .Op Fl H | L | P
 .Oc
 .Pf : Ar group

Re: chgrp(1) & chown(8): mark -h and -R as mutually exclusive

[Frederic Nowak]

> On 05 November 2015 at 18:53 Theo de Raadt 
> wrote:
> 
> 
> I don't think it makes it clearer; it makes it more confusing.
> 
> The usage messages of programs are not a sufficent grammer to exactly
> describe what conflicts with what.  Taken too far, it would bewilder
> newcomers.
> 

Understood. It's definitely more complex. I thought the synopsis
should show conflicts, but I get it now. Thanks!

> > the command line arguments -h and -R for chgrp and chown are
> > mutually
> > exclusive. The patch below changes the markup and the usage strings
> > to
> > make this clearer.
> > 
> > Cheers,
> > Frederic
> > 
> > Index: bin/chmod/chgrp.1
> > ===
> > RCS file: /cvs/src/bin/chmod/chgrp.1,v
> > retrieving revision 1.16
> > diff -u -p -r1.16 chgrp.1
> > --- bin/chmod/chgrp.1   21 Jan 2014 22:35:44 -  1.16
> > +++ bin/chmod/chgrp.1   5 Nov 2015 17:09:11 -
> > @@ -40,9 +40,7 @@
> >  .Nd change group
> >  .Sh SYNOPSIS
> >  .Nm chgrp
> > -.Op Fl h
> > -.Oo
> > -.Fl R
> > +.Oo Fl h | R
> >  .Op Fl H | L | P
> >  .Oc
> >  .Ar group
> > Index: bin/chmod/chmod.c
> > ===
> > RCS file: /cvs/src/bin/chmod/chmod.c,v
> > retrieving revision 1.38
> > diff -u -p -r1.38 chmod.c
> > --- bin/chmod/chmod.c   9 Oct 2015 01:37:06 -   1.38
> > +++ bin/chmod/chmod.c   5 Nov 2015 17:09:11 -
> > @@ -350,11 +350,11 @@ usage(void)
> > __progname, ischmod ? "mode" : "flags");
> > else
> > fprintf(stderr,
> > -   "usage: %s [-h] [-R [-H | -L | -P]] %s file ...\n",
> > +   "usage: %s [-h | -R [-H | -L | -P]] %s file ...\n",
> > __progname, ischown ? "owner[:group]" : "group");
> > if (ischown)
> > fprintf(stderr,
> > -   "   %s [-h] [-R [-H | -L | -P]] :group file ...\n",
> > +   "   %s [-h | -R [-H | -L | -P]] :group file ...\n",
> > __progname);
> > exit(1);
> >  }
> > Index: bin/chmod/chown.8
> > ===
> > RCS file: /cvs/src/bin/chmod/chown.8,v
> > retrieving revision 1.19
> > diff -u -p -r1.19 chown.8
> > --- bin/chmod/chown.8   14 Sep 2015 20:06:58 -  1.19
> > +++ bin/chmod/chown.8   5 Nov 2015 17:09:11 -
> > @@ -37,17 +37,13 @@
> >  .Nd change file owner and group
> >  .Sh SYNOPSIS
> >  .Nm chown
> > -.Op Fl h
> > -.Oo
> > -.Fl R
> > +.Oo Fl h | R
> >  .Op Fl H | L | P
> >  .Oc
> >  .Ar owner Ns Op : Ns Ar group
> >  .Ar
> >  .Nm chown
> > -.Op Fl h
> > -.Oo
> > -.Fl R
> > +.Oo Fl h | R
> >  .Op Fl H | L | P
> >  .Oc
> >  .Pf : Ar group
> > 
>