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@xxxxxxxxxx> > > 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 :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
