From 48a5589b761771257ad01252b0ce1abf9945fbb1 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Daniel=20P=2E=20Berrang=C3=A9?= <berrange@redhat.com>
Date: Fri, 18 Oct 2019 15:29:47 +0100
Subject: [PATCH] docs: convert virt-xml-validate man page from pod to rst
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.

Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/Makefile.am                              |   1 +
 docs/manpages/index.rst                       |   1 +
 .../manpages/virt-xml-validate.rst            | 107 +++++++++++-------
 tools/Makefile.am                             |   3 -
 4 files changed, 68 insertions(+), 44 deletions(-)
 rename tools/virt-xml-validate.pod => docs/manpages/virt-xml-validate.rst (53%)

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 5829bbccc6..378855ab71 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -202,6 +202,7 @@ manpages_rst = \
   $(NULL)
 manpages1_rst = \
   manpages/virt-pki-validate.rst \
+  manpages/virt-xml-validate.rst \
   $(NULL)
 manpages7_rst = \
   $(NULL)
diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst
index 0d166c1923..5042071c7d 100644
--- a/docs/manpages/index.rst
+++ b/docs/manpages/index.rst
@@ -14,3 +14,4 @@ Tools
 
 * `virt-host-validate(1) <virt-host-validate.html>`__ - validate host virtualization setup
 * `virt-pki-validate(1) <virt-pki-validate.html>`__ - validate libvirt PKI files are configured correctly
+* `virt-xml-validate(1) <virt-xml-validate.html>`__ - validate libvirt XML files against a schema
diff --git a/tools/virt-xml-validate.pod b/docs/manpages/virt-xml-validate.rst
similarity index 53%
rename from tools/virt-xml-validate.pod
rename to docs/manpages/virt-xml-validate.rst
index a51a57002a..940eada3a8 100644
--- a/tools/virt-xml-validate.pod
+++ b/docs/manpages/virt-xml-validate.rst
@@ -1,14 +1,27 @@
-=head1 NAME
+=================
+virt-xml-validate
+=================
 
-virt-xml-validate - validate libvirt XML files against a schema
+-------------------------------------------
+validate libvirt XML files against a schema
+-------------------------------------------
 
-=head1 SYNOPSIS
+:Manual section: 1
+:Manual group: Virtualization Support
 
-B<virt-xml-validate> I<XML-FILE> [I<SCHEMA-NAME>]
+.. contents::
 
-B<virt-xml-validate> I<OPTION>
+SYNOPSIS
+========
 
-=head1 DESCRIPTION
+
+``virt-xml-validate`` *XML-FILE* [*SCHEMA-NAME*]
+
+``virt-xml-validate`` *OPTION*
+
+
+DESCRIPTION
+===========
 
 Validates a libvirt XML for compliance with the published schema.
 The first compulsory argument is the path to the XML file to be
@@ -18,98 +31,110 @@ from the name of the root element in the XML document.
 
 Valid schema names currently include
 
-=over 4
-
-=item C<domainsnapshot>
+- ``domainsnapshot``
 
 The schema for the XML format used by domain snapshot configuration
 
-=item C<domain>
+- ``domain``
 
 The schema for the XML format used by guest domains configuration
 
-=item C<network>
+- ``network``
 
 The schema for the XML format used by virtual network configuration
 
-=item C<storagepool>
+- ``storagepool``
 
 The schema for the XML format used by storage pool configuration
 
-=item C<storagevol>
+- ``storagevol``
 
 The schema for the XML format used by storage volume descriptions
 
-=item C<nodedev>
+- ``nodedev``
 
 The schema for the XML format used by node device descriptions
 
-=item C<capability>
+- ``capability``
 
 The schema for the XML format used to declare driver capabilities
 
-=item C<nwfilter>
+- ``nwfilter``
 
 The schema for the XML format used by network traffic filters
 
-=item C<nwfilterbinding>
+- ``nwfilterbinding``
 
 The schema for XML format used by network filter bindings.
 
-=item C<secret>
+- ``secret``
 
 The schema for the XML format used by secrets descriptions
 
-=item C<interface>
+- ``interface``
 
 The schema for the XML format used by physical host interfaces
 
-=back
-
-=head1 OPTIONS
 
-=over
+OPTIONS
+=======
 
-=item B<-h, --help>
+``-h``, ``--help``
 
 Display command line help usage then exit.
 
-=item B<-V, --version>
+``-V``, ``--version``
 
 Display version information then exit.
 
-=back
 
-=head1 EXIT STATUS
+EXIT STATUS
+===========
 
 Upon successful validation, an exit status of 0 will be set. Upon
 failure a non-zero status will be set.
 
-=head1 AUTHOR
 
-Daniel P.Berrange
+AUTHOR
+======
+
+Daniel P. Berrangé
+
 
-=head1 BUGS
+BUGS
+====
 
-Report any bugs discovered to the libvirt community via the
-mailing list L<https://libvirt.org/contact.html> or bug tracker
-L<https://libvirt.org/bugs.html>.
-Alternatively report bugs to your software distributor / vendor.
+Please report all bugs you discover.  This should be done via either:
 
-=head1 COPYRIGHT
+#. the mailing list
+
+   `https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_
+
+#. the bug tracker
+
+   `https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_
+
+Alternatively, you may report bugs to your software distributor / vendor.
+
+
+COPYRIGHT
+=========
 
 Copyright (C) 2009-2013 by Red Hat, Inc.
-Copyright (C) 2009 by Daniel P. Berrange
+Copyright (C) 2009 by Daniel P. Berrangé
+
 
-=head1 LICENSE
+LICENSE
+=======
 
-virt-xml-validate is distributed under the terms of the GNU GPL v2+.
+``virt-xml-validate`` is distributed under the terms of the GNU GPL v2+.
 This is free software; see the source for copying conditions. There
 is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE
 
-=head1 SEE ALSO
 
-L<virsh(1)>, online XML format descriptions L<https://libvirt.org/format.html>
+SEE ALSO
+========
 
-=cut
+virsh(1), `online XML format descriptions <https://libvirt.org/format.html>`_,
+`https://libvirt.org/ <https://libvirt.org/>`_
diff --git a/tools/Makefile.am b/tools/Makefile.am
index f1ebbffed5..52b5fdaba1 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -56,7 +56,6 @@ PODFILES = \
 	virt-admin.pod \
 	virt-login-shell.pod \
 	virt-sanlock-cleanup.pod \
-	virt-xml-validate.pod \
 	virsh.pod \
 	$(NULL)
 
@@ -64,7 +63,6 @@ MANINFILES = \
 	virt-admin.1.in \
 	virt-login-shell.1.in \
 	virt-sanlock-cleanup.8.in \
-	virt-xml-validate.1.in \
 	virsh.1.in \
 	$(NULL)
 
@@ -94,7 +92,6 @@ bin_SCRIPTS = virt-xml-validate virt-pki-validate
 bin_PROGRAMS = virsh virt-admin
 libexec_SCRIPTS = libvirt-guests.sh
 man1_MANS = \
-		virt-xml-validate.1 \
 		virsh.1 \
 		virt-admin.1
 
-- 
2.47.2