[libvirt] [PATCH 00/17] docs: remove all use of POD for man pages in favour of RST

Daniel P. Berrangé berrange at redhat.com
Fri Dec 6 14:50:25 UTC 2019


As part of the goal to eliminate Perl from libvirt, this gets rid of the
use of POD format for man pages. There's nothing especially bad about
POD as a markup language compared to other lightweight markup languages
like RST or Markdown. It hasn't found widespread usage outside of the
Perl world though, and so switching from POD to RST brings a language
which likely has more familiarity to contributors.

This also nicely aligns with our use of RST of web pages, and indeed
in this series things are setup so that all the man pages get published
on the main libvirt.org website. Over time this will hopefuly draw
search engines traffic to libvirt.org instead of random 3rd party
websites hosting various out of date copies of the man pages.

Reviewing the individual RST files is likely a very unpleasant task,
especially the enourmous virsh man page. Most of the conversion work
was automated with pod2rst, followed by lots of editting to cleanup
its output. virsh had some further automated processing done to create
headers for each command.

It is probably more useful to review the rendered man page output
and/or websites to see that it looks sane when read.

Daniel P. Berrangé (17):
  src: update keycodemapdb submodule
  rpm: move pod2man & rst2html deps outside the autotools conditional
  rpm: use python3-docutils as the direct dep
  docs: introduce rst2man as a mandatory tool for building docs
  docs: describe the basic RST structure for a man page
  docs: convert libvirtd man page from pod to rst
  docs: convert virtlockd man page from pod to rst
  docs: convert virtlogd man page from pod to rst
  docs: convert virt-host-validate man page from pod to rst
  docs: convert virt-pki-validate man page from pod to rst
  docs: convert virt-xml-validate man page from pod to rst
  docs: convert virt-sanlock-cleanup man page from pod to rst
  docs: convert virt-login-shell man page from pod to rst
  docs: convert virt-admin man page from pod to rst
  docs: convert virsh man page from pod to rst
  docs: convert virkeycode*/virkeyname* man pages from pod to rst
  docs: remove build recipes related to pod2man usage

 docs/Makefile.am                              |  118 +
 docs/docs.html.in                             |    3 +
 docs/manpages/index.rst                       |   37 +
 docs/manpages/libvirtd.rst                    |  259 +
 docs/manpages/virsh.rst                       | 7096 +++++++++++++++++
 docs/manpages/virt-admin.rst                  |  610 ++
 docs/manpages/virt-host-validate.rst          |   95 +
 docs/manpages/virt-login-shell.rst            |  144 +
 docs/manpages/virt-pki-validate.rst           |   89 +
 docs/manpages/virt-sanlock-cleanup.rst        |   79 +
 .../manpages/virt-xml-validate.rst            |  107 +-
 docs/manpages/virtlockd.rst                   |  177 +
 docs/manpages/virtlogd.rst                    |  179 +
 docs/styleguide.rst                           |   86 +
 libvirt.spec.in                               |    7 +-
 m4/virt-external-programs.m4                  |    5 +
 src/Makefile.am                               |   18 -
 src/keycodemapdb                              |    2 +-
 src/locking/Makefile.inc.am                   |   18 -
 src/locking/virtlockd.pod                     |  165 -
 src/logging/Makefile.inc.am                   |   13 -
 src/logging/virtlogd.pod                      |  165 -
 src/remote/Makefile.inc.am                    |   15 -
 src/remote/libvirtd.pod                       |  235 -
 src/util/Makefile.inc.am                      |   47 +-
 tools/Makefile.am                             |   68 -
 tools/virsh.pod                               | 5526 -------------
 tools/virt-admin.pod                          |  497 --
 tools/virt-host-validate.pod                  |   68 -
 tools/virt-login-shell.pod                    |  112 -
 tools/virt-pki-validate.pod                   |   61 -
 tools/virt-sanlock-cleanup.pod                |   49 -
 32 files changed, 9052 insertions(+), 7098 deletions(-)
 create mode 100644 docs/manpages/index.rst
 create mode 100644 docs/manpages/libvirtd.rst
 create mode 100644 docs/manpages/virsh.rst
 create mode 100644 docs/manpages/virt-admin.rst
 create mode 100644 docs/manpages/virt-host-validate.rst
 create mode 100644 docs/manpages/virt-login-shell.rst
 create mode 100644 docs/manpages/virt-pki-validate.rst
 create mode 100644 docs/manpages/virt-sanlock-cleanup.rst
 rename tools/virt-xml-validate.pod => docs/manpages/virt-xml-validate.rst (53%)
 create mode 100644 docs/manpages/virtlockd.rst
 create mode 100644 docs/manpages/virtlogd.rst
 delete mode 100644 src/locking/virtlockd.pod
 delete mode 100644 src/logging/virtlogd.pod
 delete mode 100644 src/remote/libvirtd.pod
 delete mode 100644 tools/virsh.pod
 delete mode 100644 tools/virt-admin.pod
 delete mode 100644 tools/virt-host-validate.pod
 delete mode 100644 tools/virt-login-shell.pod
 delete mode 100644 tools/virt-pki-validate.pod
 delete mode 100644 tools/virt-sanlock-cleanup.pod

-- 
2.23.0




More information about the libvir-list mailing list