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

[Wei Liu <wei.liu2@xxxxxxxxxx>]

On Tue, Jul 25, 2017 at 02:17:59PM +0100, Ian Jackson wrote:
> 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 ?
> 

+1

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