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