Hi, On Sat, Nov 26, 2016 at 09:49:32PM -0500, Jon LaBadie wrote: > Though not new to *nix, I am new to using the ip(8) command. > Thus some of my historical assumptions about ip may be wrong. > > It seems that an inclusive manpage for the ip command was > broken up into a shorter ip(8) manpage and 15 or more > ip-<subcommand>(8) manpages. I'm basing this assumption > on long, inclusive manpages on https://linux.die.net/man/8/ip > and CentOS 6 while CentOS 7 and Fedora 24 each have the > sub-divided style. > > I won't debate the wisdom of this subdivision, only comment > on how it was done. > > The ip(8) manpage make no mention of additional subordinate > documents. The listing of the additional documents in the > See Also section is insufficient. This section is typically > used to mention related commands and other sources of reference > materials such as info docs, wikis, blogs, or mailing lists.
In what aspect do you think it's insufficient? Only because you don't think it's the appropriate place to list them or are there any other reasons? Where do you think would be a better place for them? Looking at the description of 'SEE ALSO' section in man-pages.7, it is expected to find "A comma-separated list of related man pages" there. > When one does investigate one of the subordinate manpages, > they do not state that they document subcommands of the > ip command. In fact, on the ip-address(8) manpage it says > > The `ip address command' ... (quotes added) > > My first thought was "typo", this is the manpage about the > "ip-address" command. Of course there is no ip-address command. > But "ip address" is not a command either, it is the "ip" command > with an argument. Well, yes and no. While it is true that the command itself on most systems is 'ip' and 'address' is just the first parameter, by the internal design 'ip' is merely a dispatcher to the actual subcommand given. An interesting fact is that main() in ip.c checks argv[0] and in case it's longer than two characters assumes the remaining part is the subcommand (i.e. first parameter). So by symlinking 'ip' to 'ipaddress' I can use the latter as an alternative to calling 'ip address'. You might argue that the man page then should be named ipaddress.8, but there is a reason for it not to be like this: Given that most distributions don't make use of the symlink possibility, the dashed name allows for opening ip-address.8 using 'man ip address' which is in my opinion far more intuitive than having to use 'man ipaddress'. (Of course nothing prevents one from having an ipaddress.8 redirecting to ip-address.8.) > There are several commands that have broken their manpage into > several manpages. Two which come to mind are zsh(1) and perl(1). > The authors of those pages clearly state on the primary manpage > that this is an overview page and give clear pointers to the > additional manpages as well as additional documentation. I would > recommend reorganizing the ip(8) manpage in a similar fashion. Well, go ahead if you like. Patches are appreciated, and if you put me in Cc, I'll promise to help by reviewing them. > Thank you for consideration of my opinion and for the development > of an awesome tool. Please keep in mind that you are talking to a community here, not tech support of a product you bought. :) Cheers, Phil
