Re: [Xen-devel] [PATCH v2 1/3] docs: add pod variant of xen-pv-channel.7

[Ian Jackson <ian.jackson@xxxxxxxxxxxxx>]

Olaf Hering writes ("[PATCH v2 1/3] docs: add pod variant of xen-pv-channel.7"):
> Convert source for xen-pv-channel.7 from markdown to pod.
> This removes the buildtime requirement for pandoc, and subsequently the
> need for ghc, in the chain for BuildRequires of xen.rpm.

Thanks.  Thanks also for the explanations.  I'm happy that this series
is fine in principle.  Now onto the details:

I applied your patches to see what they looked like and I noticed that
git-am complains about whitespace errors.

>  docs/man/xen-pv-channel.pod.7      | 189 
> +++++++++++++++++++++++++++++++++++++

These manpages are not quite in the conventional manpage structure,
and your work reveals that are documentation is disorganised.
Reorganising the pages to put things in more sensible places, add a
SYNOPSYS near the top, etc. is probably out of scope.  I just thought
I'd mention it.

But can you please change the headings to caps so they look like other
manpages ?

I wonder if I should ask you to add a NAME section, as that seems to
be very conventional in other projects' manpages.  See this for
example
  https://manpages.debian.org/stretch/dgit/dgit.7.en.html
What do others think ?

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel