> On Mon, Jun 19, 2017 at 12:15:49PM +0200, Klemens Nanni wrote: > > 'arp -[d]a' do not require hostname as told in the manual page. > > > > A single fprintf() is both shorter and cleaner. > > > > this diff suggest that running arp without arguments should work, but it > does not. > > there are a few approaches i guess. you could try and have SYNOPSIS show > every usage trickery, or assume the reader can work out that > this format of arp requires a hostname but, for example, the flag which > displays all current arp entries does not. > > i prefer the latter (that is, how it is now). if i thought it was not > obvious how that worked, i'd say the fault lies in DESCRIPTION. but i > think it's clear here.
absolutely right. SYNOPSIS are not a grammar, it is not proscriptive. The text is simply declarative, to help readers understand the scope of operation; allowing them to determine valid use cases. Everyone might as well get used to that. I fear any solution to this -- if taken the full extreme -- would lead to a number of manual pages having 50 pages of SYNOPSIS at the start. That would be very unhelpful, so let's not go there. Or, we could outlaw behaviours in commands which don't rigorously abide to what SYNOPSIS describes. Also an unachievable goal which can create great harm once the fanatics get involved. https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good > > Index: arp.8 > > =================================================================== > > RCS file: /cvs/src/usr.sbin/arp/arp.8,v > > retrieving revision 1.39 > > diff -u -p -r1.39 arp.8 > > --- arp.8 5 Apr 2016 18:18:42 -0000 1.39 > > +++ arp.8 19 Jun 2017 10:15:10 -0000 > > @@ -40,7 +40,7 @@ > > .Nm arp > > .Op Fl adn > > .Op Fl V Ar rdomain > > -.Ar hostname > > +.Op Ar hostname > > .Nm arp > > .Op Fl F > > .Op Fl f Ar file > > Index: arp.c > > =================================================================== > > RCS file: /cvs/src/usr.sbin/arp/arp.c,v > > retrieving revision 1.79 > > diff -u -p -r1.79 arp.c > > --- arp.c 19 Apr 2017 05:36:12 -0000 1.79 > > +++ arp.c 19 Jun 2017 10:15:10 -0000 > > @@ -601,11 +601,10 @@ ether_str(struct sockaddr_dl *sdl) > > void > > usage(void) > > { > > - fprintf(stderr, "usage: arp [-adn] [-V rdomain] hostname\n"); > > - fprintf(stderr, " arp [-F] [-f file] [-V rdomain] " > > - "-s hostname ether_addr\n" > > - " [temp | permanent] [pub]\n"); > > - fprintf(stderr, " arp -W ether_addr [iface]\n"); > > + fprintf(stderr, "usage: arp [-adn] [-V rdomain] [hostname]\n" > > + " arp [-F] [-f file] [-V rdomain] -s hostname ether_addr\n" > > + " [temp | permanent] [pub]\n" > > + " arp -W ether_addr [iface]\n"); > > exit(1); > > } > > > > >
