More documentation and man page fixes

- Include numbers in man page references
- Use “:manpage:” where appropriate
- Don't escape underscore in verbatim text (e.g. “``always_failover``)
  as it would show up in the generated man page
- Quote whole paths, not just build-time part

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Guido Trotter <ultrotter@google.com>

diff --git a/NEWS b/NEWS
index f2a940e..d75ed85 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -703,7 +703,7 @@ New features
 - Instance migration can fall back to failover if instance is not
   running.
 - Filters can be used when listing nodes, instances, groups and locks;
-  see *ganeti(7)* manpage.
+  see :manpage:`ganeti(7)` manpage.
 - Added post-execution status as variables to :doc:`hooks <hooks>`
   environment.
 - Instance tags are exported/imported together with the instance.

diff --git a/doc/admin.rst b/doc/admin.rst
index d3e09be..a458a0f 100644 (file)
--- a/doc/admin.rst
+++ b/doc/admin.rst
@@ -322,7 +322,7 @@ after shutting down an instance, execute the following::
 .. warning:: Do not use the Xen or KVM commands directly to stop
    instances. If you run for example ``xm shutdown`` or ``xm destroy``
    on an instance Ganeti will automatically restart it (via
-   the :command:`ganeti-watcher` command which is launched via cron).
+   the :command:`ganeti-watcher(8)` command which is launched via cron).
 
 Querying instances
 ~~~~~~~~~~~~~~~~~~
@@ -1217,7 +1217,7 @@ upgrade the Ganeti software, or simply restart the software on any node:
 Watcher control
 +++++++++++++++
 
-The :manpage:`ganeti-watcher` is a program, usually scheduled via
+The :manpage:`ganeti-watcher(8)` is a program, usually scheduled via
 ``cron``, that takes care of cluster maintenance operations (restarting
 downed instances, activating down DRBD disks, etc.). However, during
 maintenance and troubleshooting, this can get in your way; disabling it

diff --git a/doc/design-2.0.rst b/doc/design-2.0.rst
index 26cd8c6..6bff30a 100644 (file)
--- a/doc/design-2.0.rst
+++ b/doc/design-2.0.rst
@@ -1621,7 +1621,7 @@ DEBUG_LEVEL
 
 These are only the basic variables we are thinking of now, but more
 may come during the implementation and they will be documented in the
-:manpage:`ganeti-os-api` man page. All these variables will be
+:manpage:`ganeti-os-interface(7)` man page. All these variables will be
 available to all scripts.
 
 Some scripts will need a few more information to work. These will have

diff --git a/doc/install.rst b/doc/install.rst
index c6a62d9..ec1c6ab 100644 (file)
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -655,7 +655,7 @@ installed.
    can be added, of course, if needed.
 
 Alternatively, you can create your own OS definitions. See the manpage
-:manpage:`ganeti-os-interface`.
+:manpage:`ganeti-os-interface(7)`.
 
 Initializing the cluster
 ++++++++++++++++++++++++

diff --git a/man/gnt-backup.rst b/man/gnt-backup.rst
index 51b6e2d..d4d86e5 100644 (file)
--- a/man/gnt-backup.rst
+++ b/man/gnt-backup.rst
@@ -30,7 +30,7 @@ EXPORT
 
 Exports an instance to the target node. All the instance data and
 its configuration will be exported under the
-``@CUSTOM_EXPORT_DIR@/``*instance* directory on the target node.
+``@CUSTOM_EXPORT_DIR@/$instance`` directory on the target node.
 
 The ``--shutdown-timeout`` is used to specify how much time to wait
 before forcing the shutdown (xm destroy in xen, killing the kvm

diff --git a/man/gnt-cluster.rst b/man/gnt-cluster.rst
index f5d13be..55d4bed 100644 (file)
--- a/man/gnt-cluster.rst
+++ b/man/gnt-cluster.rst
@@ -340,7 +340,7 @@ auto\_balance
     will be set to true if not specified.
 
 always\_failover
-    Default value for the ``always\_failover`` flag for instances; if
+    Default value for the ``always_failover`` flag for instances; if
     not set, ``False`` is used.
 
 

diff --git a/man/gnt-instance.rst b/man/gnt-instance.rst
index be91e36..92153bb 100644 (file)
--- a/man/gnt-instance.rst
+++ b/man/gnt-instance.rst
@@ -672,7 +672,7 @@ useful for having different subdirectories for different
 instances. The full path of the directory where the disk files are
 stored will consist of cluster-wide file storage directory + optional
 subdirectory + instance name. Example:
-``@RPL_FILE_STORAGE_DIR@``*/mysubdir/instance1.example.com*. This
+``@RPL_FILE_STORAGE_DIR@/mysubdir/instance1.example.com``. This
 option is only relevant for instances using the file storage backend.
 
 The ``--file-driver`` specifies the driver to use for file-based
@@ -1600,7 +1600,7 @@ The ``--no-runtime-changes`` option forbids migrate to alter an
 instance's runtime before migrating it (eg. ballooning an instance
 down because the target node doesn't have enough available memory).
 
-If an instance has the backend parameter ``always\_failover`` set to
+If an instance has the backend parameter ``always_failover`` set to
 true, then the migration is automatically converted into a failover.
 
 See **ganeti(7)** for a description of ``--submit`` and other common

diff --git a/man/hspace.rst b/man/hspace.rst
index 1a3c064..e0169f4 100644 (file)
--- a/man/hspace.rst
+++ b/man/hspace.rst
@@ -191,8 +191,9 @@ OK
   that the computation failed and any values present should not be
   relied upon.
 
-Many of the INI_/FIN_ metrics will be also displayed with a TRL_ prefix,
-and denote the cluster status at the end of the tiered allocation run.
+Many of the ``INI_``/``FIN_`` metrics will be also displayed with a
+``TRL_`` prefix, and denote the cluster status at the end of the tiered
+allocation run.
 
 The human output format should be self-explanatory, so it is not
 described further.