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

Message ID 20180212201753.16254-1-mmichels@redhat.com
State Changes Requested
Headers show
Series
  • [ovs-dev] Refer to database manpages in *ctl manpages
Related show

Commit Message

Mark Michelson Feb. 12, 2018, 8:17 p.m.
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@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.
---
 ovn/utilities/ovn-nbctl.8.xml | 60 +++----------------------------------------
 ovn/utilities/ovn-sbctl.8.in  |  4 +--
 utilities/ovs-vsctl.8.in      | 50 +-----------------------------------
 3 files changed, 6 insertions(+), 108 deletions(-)

Comments

Ben Pfaff Feb. 15, 2018, 12:22 a.m. | #1
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@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.

Patch

diff --git a/ovn/utilities/ovn-nbctl.8.xml b/ovn/utilities/ovn-nbctl.8.xml
index 4d0aea963..5a8f5dacf 100644
--- a/ovn/utilities/ovn-nbctl.8.xml
+++ b/ovn/utilities/ovn-nbctl.8.xml
@@ -820,64 +820,10 @@ 
     additional ways to identify records.  Some commands also take
     <var>column</var> parameters that identify a particular field within the
     records in a table.</p>
-    <p>The following tables are currently defined:</p>
-    <dl>
-      <dt><code>Logical_Switch</code></dt>
-      <dd>
-        An L2 logical switch.  Records may be identified by name.
-      </dd>
-
-      <dt><code>Logical_Switch_Port</code></dt>
-      <dd>
-        A port within an L2 logical switch.  Records may be identified by name.
-      </dd>
-
-      <dt><code>ACL</code></dt>
-      <dd>
-        An ACL rule for a logical switch that points to it through its <var>acls</var> column.
-      </dd>
-
-      <dt><code>Logical_Router</code></dt>
-      <dd>
-        An L3 logical router.  Records may be identified by name.
-      </dd>
-
-      <dt><code>Logical_Router_Port</code></dt>
-      <dd>
-        A port within an L3 logical router.  Records may be identified by name.
-      </dd>
-
-      <dt><code>Logical_Router_Static_Route</code></dt>
-      <dd>
-        A static route belonging to an L3 logical router.
-      </dd>
 
-      <dt><code>Address_Set</code></dt>
-      <dd>
-        An address set that can be used in ACLs.
-      </dd>
-
-      <dt><code>Load_Balancer</code></dt>
-      <dd>
-        A load balancer for a logical switch that points to it through its <var>load_balancer</var> column.
-      </dd>
-
-      <dt><code>NAT</code></dt>
-      <dd>
-        A NAT rule for a Gateway router.
-      </dd>
-
-      <dt><code>DHCP_Options</code></dt>
-      <dd>
-        DHCP options.
-      </dd>
-
-      <dt><code>NB_Global</code></dt>
-      <dd>
-        North bound global configurations.
-      </dd>
-
-    </dl>
+    <p>
+      For a list of tables and their columns, see <code>ovn-nb</code>(5).
+    </p>
 
     <p>
       Record names must be specified in full and with correct capitalization,
diff --git a/ovn/utilities/ovn-sbctl.8.in b/ovn/utilities/ovn-sbctl.8.in
index cd43cf3be..40807c1dc 100644
--- a/ovn/utilities/ovn-sbctl.8.in
+++ b/ovn/utilities/ovn-sbctl.8.in
@@ -278,8 +278,8 @@  parameter may be the UUID for a record, and many tables offer
 additional ways to identify records.  Some commands also take
 \fIcolumn\fR parameters that identify a particular field within the
 records in a table.
-.\" It would be kind to list all the tables and their supported identifiers
-.\" here.
+.PP
+For a list of tables and their columns, see \fBovn\-sb\fR(5).
 .PP
 Record names must be specified in full and with correct
 capitalization, except that UUIDs may be abbreviated to their first 4
diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
index 34f41e4e8..374dd5368 100644
--- a/utilities/ovs-vsctl.8.in
+++ b/utilities/ovs-vsctl.8.in
@@ -530,55 +530,7 @@  additional ways to identify records.  Some commands also take
 \fIcolumn\fR parameters that identify a particular field within the
 records in a table.
 .PP
-The following tables are currently defined:
-.IP "\fBOpen_vSwitch\fR"
-Global configuration for an \fBovs\-vswitchd\fR.  This table contains
-exactly one record, identified by specifying \fB.\fR as the record
-name.
-.IP "\fBBridge\fR"
-Configuration for a bridge within an Open vSwitch.  Records may be
-identified by bridge name.
-.IP "\fBPort\fR"
-A bridge port.  Records may be identified by port name.
-.IP "\fBInterface\fR"
-A network device attached to a port.  Records may be identified by
-name.
-.IP "\fBFlow_Table\fR"
-Configuration for a particular OpenFlow flow table.  Records may be
-identified by name.
-.IP "\fBQoS\fR"
-Quality-of-service configuration for a \fBPort\fR.  Records may be
-identified by port name.
-.IP "\fBQueue\fR"
-Configuration for one queue within a \fBQoS\fR configuration.  Records
-may only be identified by UUID.
-.IP "\fBMirror\fR"
-A port mirroring configuration attached to a bridge.  Records may be
-identified by mirror name.
-.IP "\fBController\fR"
-Configuration for an OpenFlow controller.  A controller attached to a
-particular bridge may be identified by the bridge's name.
-.IP "\fBManager\fR"
-Configuration for an OVSDB connection.  Records may be identified
-by target (e.g. \fBtcp:1.2.3.4\fR).
-.IP "\fBNetFlow\fR"
-A NetFlow configuration attached to a bridge.  Records may be
-identified by bridge name.
-.IP "\fBSSL\fR"
-The global SSL configuration for \fBovs\-vswitchd\fR.  The record
-attached to the \fBOpen_vSwitch\fR table may be identified by
-specifying \fB.\fR as the record name.
-.IP "\fBsFlow\fR"
-An sFlow exporter configuration attached to a bridge.  Records may be
-identified by bridge name.
-.IP "\fBIPFIX\fR"
-An IPFIX exporter configuration attached to a bridge.  Records may be
-identified by bridge name.
-.IP "\fBFlow_Sample_Collector_Set\fR"
-An IPFIX exporter configuration attached to a bridge for sampling
-packets on a per-flow basis using OpenFlow \fBsample\fR actions.
-.IP "\fBAutoAttach\fR"
-Configuration for Auto Attach within a bridge.
+For a list of tables and their columns, see \fBovs-vswitchd.conf.db\fR(5).
 .PP
 Record names must be specified in full and with correct
 capitalization, except that UUIDs may be abbreviated to their first 4