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

[Daniel P. Berrangé]

On Tue, Dec 10, 2019 at 08:25:25PM -0500, Cole Robinson wrote:
> On 12/6/19 9:50 AM, Daniel P. Berrangé wrote:
> > 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.
> > 
> 
> Reviewed-by: Cole Robinson <crobinso at redhat.com>
> 
> With some tweaks:
> 
> * There's a leftover pod2man in the spec file.
> * This conflicts with the virsh --tls-destination changes so don't
> forget to re-merge those
> * virt-host-validate patch needs this diff
> 
> diff --git a/docs/Makefile.am b/docs/Makefile.am
> index e1f8f7646d..4027c2e26c 100644
> --- a/docs/Makefile.am
> +++ b/docs/Makefile.am
> @@ -236,7 +236,7 @@ manpages_rst += \
>    $(NULL)
>  endif ! WITH_LIBVIRTD
>  if WITH_HOST_VALIDATE
> -  manpages8_rst += manpages/virt-host-validate.rst
> +  manpages1_rst += manpages/virt-host-validate.rst
>  else ! WITH_HOST_VALIDATE
>    manpages_rst += manpages/virt-host-validate.rst
>  endif ! WITH_HOST_VALIDATE
> 
> 
> Non-blocking stuff:
> 
> The build process spits out noise like this now, but I didn't
> investigate, maybe it was there before and I missed it:
> 
> I/O error : Attempt to load network entity
> http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd
> manpages/virkeycode-osx.html.in:2: warning: failed to load external
> entity "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
>  1.0 Transitional//EN"
> "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"

That's fixed by this patch to use HTML5 instead of HTML4:

  https://www.redhat.com/archives/libvir-list/2019-December/msg00387.html

> 
> 
> As for the format, there's some improvements and some worse things, most
> are minor. The one place it's pretty ugly is virt-admin and virsh, with
> the command format immediately after the command header. Old style looks
> like:
> 
>     quit, exit
>         quit this interactive terminal
> 
> Now it is:
> 
>    quit, exit
>           quit
>           exit
> 
>        quit this interactive terminal
> 
> For larger commands it's better, so it's mostly noticeable at the start
> of the document with the short commands. Maybe drop the shell section
> entirely for short style commands, or maybe there's some other option, I
> didn't look into it much

It is a tradeoff between the man page formatting and the HTML. The
first is a heading, linked from the ToC, the second gives the actual
syntax & args. I don't think its worth changing just these few
cases without args, but maybe make it clearer 

    quit, exit
       syntax: quit
       syntax: exit
 
        quit this interactive terminal

or something similar.

> The other bit is nested Example: sections with ~ underline. It puts the
> Example: at the same indent as the top level command, which is ugly and
> tough to read. Just grep the rst for '~~~~' and see how it manifests in
> the output manpage. I think those few sections can be replaced by
> boldified text with *Example:* and it looks better, at least with the
> man page, but I didn't review the HTML.

It was done so that Example turns into a heading in the HTML, but I'l
see if there's a way to make both look nice.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|