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@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 :|