Signed-off-by: Stephen Finucane <step...@that.guru>
---
utilities/automake.mk | 4 +-
utilities/ovs-command-bashcomp.INSTALL.md | 88 -----------------------
utilities/ovs-command-bashcomp.INSTALL.rst | 111 +++++++++++++++++++++++++++++
3 files changed, 113 insertions(+), 90 deletions(-)
delete mode 100644 utilities/ovs-command-bashcomp.INSTALL.md
create mode 100644 utilities/ovs-command-bashcomp.INSTALL.rst
diff --git a/utilities/automake.mk b/utilities/automake.mk
index 380418a..014e477 100644
--- a/utilities/automake.mk
+++ b/utilities/automake.mk
@@ -37,11 +37,11 @@ noinst_SCRIPTS += utilities/ovs-sim
utilities/ovs-lib: $(top_builddir)/config.status
-docs += utilities/ovs-command-bashcomp.INSTALL.md
+docs += utilities/ovs-command-bashcomp.INSTALL.rst
EXTRA_DIST += \
utilities/ovs-appctl-bashcomp.bash \
utilities/ovs-check-dead-ifs.in \
- utilities/ovs-command-bashcomp.INSTALL.md \
+ utilities/ovs-command-bashcomp.INSTALL.rst \
utilities/ovs-ctl.in \
utilities/ovs-dev.py \
utilities/ovs-docker \
diff --git a/utilities/ovs-command-bashcomp.INSTALL.md
b/utilities/ovs-command-bashcomp.INSTALL.md
deleted file mode 100644
index 9bdef40..0000000
--- a/utilities/ovs-command-bashcomp.INSTALL.md
+++ /dev/null
@@ -1,88 +0,0 @@
-Using bash command-line completion scripts
-------------------------------------------
-
-There are two completion scripts available, ovs-appctl-bashcomp.bash
-and ovs-vsctl-bashcomp.bash respectively.
-
-ovs-appctl-bashcomp
--------------------
-
- ovs-appctl-bashcomp.bash adds bash command-line completion support
- for ovs-appctl, ovs-dpctl, ovs-ofctl and ovsdb-tool commands.
-
- Features:
- ---------
-
- display available completion or complete on unfinished user input
- (long option, subcommand, and argument).
-
- once the subcommand (e.g. ofproto/trace) has been given, the
- script will print the subcommand format.
-
- the script can convert between keywords like 'bridge/port/interface/dp'
- and the available record in ovsdb.
-
- Limitations:
- ------------
-
- only support small set of important keywords
- (dp, datapath, bridge, switch, port, interface, iface).
-
- does not support parsing of nested options
- (e.g. ovsdb-tool create [db [schema]]).
-
- does not support expansion on repeatitive argument
- (e.g. ovs-dpctl show [dp...]).
-
- only support matching on long options, and only in the format
- (--option [arg], i.e. should not use --option=[arg]).
-
-ovs-vsctl-bashcomp
--------------------
-
- ovs-vsctl-bashcomp.bash adds bash command-line completion support
- for ovs-vsctl command.
-
- Features:
- ---------
-
- display available completion and complete on user input for
- global/local options, command, and argument.
-
- query database and expand keywords like 'table/record/column/key'
- to available completions.
-
- deal with argument relations like 'one and more', 'zero or one'.
-
- complete multiple ovs-vsctl commands cascaded via '--'.
-
- Limitations:
- ------------
-
- completion of very long ovs-vsctl command can take up to several
- seconds.
-
-How to use:
------------
-
- The bashcomp scripts should be placed at /etc/bash_completion.d/
- to be available for all bash sessions. Running 'make install'
- will place the scripts to $(sysconfdir)/bash_completion.d/. So user
- should specify --sysconfdir=/etc at configuration. Meanwhile, if OVS is
- installed from packages, the scripts will automatically be placed inside
- /etc/bash_completion.d/.
-
- If you just want to run the scripts in one bash, you can remove them from
- /etc/bash_completion.d/ and run the scripts via '. ovs-appctl-bashcomp.bash'
- or '. ovs-vsctl-bashcomp.bash'.
-
-Test:
------
-
- Unit tests are added in tests/completion.at and integrated into autotest
- framework. To run the tests, just do make check.
-
-Bug Reporting:
---------------
-
-Please report problems to b...@openvswitch.org.
\ No newline at end of file
diff --git a/utilities/ovs-command-bashcomp.INSTALL.rst
b/utilities/ovs-command-bashcomp.INSTALL.rst
new file mode 100644
index 0000000..6df60c6
--- /dev/null
+++ b/utilities/ovs-command-bashcomp.INSTALL.rst
@@ -0,0 +1,111 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ ======= Heading 0 (reserved for the title in a document)
+ ------- Heading 1
+ ~~~~~~~ Heading 2
+ +++++++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+====================================
+Bash command-line completion scripts
+====================================
+
+There are two completion scripts available, ovs-appctl-bashcomp.bash and
+ovs-vsctl-bashcomp.bash respectively.
+
+ovs-appctl-bashcomp
+-------------------
+
+ovs-appctl-bashcomp.bash adds bash command-line completion support for
+ovs-appctl, ovs-dpctl, ovs-ofctl and ovsdb-tool commands.
+
+Features
+~~~~~~~~
+
+- Display available completion or complete on unfinished user input (long
+ option, subcommand, and argument).
+
+- Subcommand hints
+
+- Convert between keywords like ``bridge``, ``port``, ``interface``, or ``dp``
+ and the available record in ovsdb.
+
+Limitations
+~~~~~~~~~~~
+
+- Only supports a small set of important keywords (``dp``, ``datapath``,
``bridge``, ``switch``,
+ ``port``, ``interface``, ``iface``).
+
+- Does not support parsing of nested options. For example:
+
+
+ ::
+
+ $ ovsdb-tool create [db [schema]]
+
+- Does not support expansion on repeated argument. For example:
+
+ ::
+
+ $ ovs-dpctl show [dp...]).
+
+- Only supports matching on long options, and only in the format ``--option
+ [arg]``. Do not use ``--option=[arg]``.
+
+ovs-vsctl-bashcomp
+-------------------
+
+ovs-vsctl-bashcomp.bash adds bash command-line completion support for ovs-vsctl
+command.
+
+Features
+~~~~~~~~
+
+- Display available completion and complete on user input for global/local
+ options, command, and argument.
+
+- Query database and expand keywords like ``table``, ``record``, ``column``, or
+ ``key``, to available completions.
+
+- Deal with argument relations like 'one and more', 'zero or one'.
+
+- Complete multiple ovs-vsctl commands cascaded via ``--``.
+
+Limitations
+~~~~~~~~~~~
+
+Completion of very long ``ovs-vsctl`` commands can take up to several seconds.
+
+Usage
+-----
+
+The bashcomp scripts should be placed at ``/etc/bash_completion.d/`` to be
+available for all bash sessions. Running ``make install`` will place the
+scripts to ``$(sysconfdir)/bash_completion.d/``, thus, the user should specify
+``--sysconfdir=/etc`` at configuration. If OVS is installed from packages, the
+scripts will automatically be placed inside ``/etc/bash_completion.d/``.
+
+If you just want to run the scripts in one bash, you can remove them from
+``/etc/bash_completion.d/`` and run the scripts via ``.
+ovs-appctl-bashcomp.bash`` or ``. ovs-vsctl-bashcomp.bash``.
+
+Tests
+-----
+
+Unit tests are added in ``tests/completion.at`` and integrated into autotest
+framework. To run the tests, just run ``make check``.
--
2.7.4
_______________________________________________
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
