netdev - ip manpage comments

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20161127024932.GA9954@cyber.jgcomp.com>
Date:   Sat, 26 Nov 2016 21:49:32 -0500
From:   Jon LaBadie <jonfu@...omp.com>
To:     netdev@...r.kernel.org
Subject: ip manpage comments

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.

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.

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.

Thank you for consideration of my opinion and for the development
of an awesome tool.

Jon
-- 
Jon H. LaBadie                  jonfu@...omp.com