[ovs-dev] [PATCH] Refer to database manpages in *ctl manpages

[Ben Pfaff]

On Mon, Feb 12, 2018 at 02:17:53PM -0600, Mark Michelson wrote:
> The ovn-nbctl, ovn-sbctl, and ovs-vsctl manpages are inconsistent in
> their "Database Commands" section when it comes to referring to what
> database tables exist. This commit amends this by making each *ctl
> manpage reference the corresponding database manpage instead.
> 
> Signed-off-by: Mark Michelson <mmichels at redhat.com>
> ---
> While having a look through the manpages for ovn-nbctl, ovn-sbctl, and
> ovs-vsctl, I noticed that each of them were different with regards to
> referring to tables:
> 
> * ovn-nbctl listed tables but the list was incomplete.
> * ovn-sbctl listed no tables at all.
> * ovs-vsctl listed all tables.
> 
> To me, there were two ways to go here: list all tables in each of the
> three manpages, or list no tables in the three manpages. In the end, I
> decided to make a reference to the database manpages. This way we're not
> repeating table listings and there's no risk of omitting tables. The
> database manpages are better references anyway for tables and their
> columns.

Thanks for working on the documentation!

The main point of having the list of tables in ovs-vsctl(8) is not
actually to list the tables but to let people know what names they can
use for rows in those tables.  This patch loses that information for
ovs-vsctl.

However, this stuff is encoded into the ctl_table_class structs in each
ctl program, such as the one starting around line 2363 in ovs-vsctl.c:
    static const struct ctl_table_class tables[OVSREC_N_TABLES] = {
    ...
    };
so it probably wouldn't be too hard to write a function that prints this
info in a human-readable form and then call that function for --help
output.  And then every one of these programs would have correct and
up-to-date helpful output all the time, and we could delete it from the
manpages while still keeping my conscience clear that it was available.

Any chance you'd be willing to work on that?

Thanks,

Ben.