Re: [PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format

[Changbin Du]

On Fri, Mar 29, 2019 at 09:00:09PM -0700, Matthew Wilcox wrote:
> On Sat, Mar 30, 2019 at 12:04:06AM +0800, Changbin Du wrote:
> > @@ -1,13 +1,18 @@
> > -		The MSI Driver Guide HOWTO
> > -	Tom L Nguyen tom.l.nguyen@xxxxxxxxx
> > -			10/03/2003
> > -	Revised Feb 12, 2004 by Martine Silbermann
> > -		email: Martine.Silbermann@xxxxxx
> > -	Revised Jun 25, 2004 by Tom L Nguyen
> > -	Revised Jul  9, 2008 by Matthew Wilcox <willy@xxxxxxxxxxxxxxx>
> > -		Copyright 2003, 2008 Intel Corporation
> > +.. SPDX-License-Identifier: GPL-2.0
> > +.. include:: <isonum.txt>
> > +
> > +==========================
> > +The MSI Driver Guide HOWTO
> > +==========================
> > +
> > +:Authors: - Tom L Nguyen <tom.l.nguyen@xxxxxxxxx> 10/03/2003
> > +          - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@xxxxxx>
> > +	  - Revised Jun 25, 2004 by Tom L Nguyen
> > +	  - Revised Jul  9, 2008 by Matthew Wilcox <willy@xxxxxxxxxxxxxxx>
> > +	    Copyright 2003, 2008 Intel Corporation
> 
> The copyright line doesn't work quite the way it should in the rendered HTML.
> 
> It seems to me it should be:
> 
> :Copyright: 2003, 2008 Intel Corporation
> 
> Tom has used an ambiguous date format; given it appeared in the tree
> in December 2003, I suspect he's used middle-endian format.  It doesn't
> really seem relevant to have the dates here any more, so we could skip
> including them.  Also, none of these email addresses work, so perhaps
> just drop those too.
> 
> :Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
>
yeah, looks better. Thanks.

> >  1. About this guide
> > +===================
> 
> Should we drop the numbering of sections as part of this conversion?
> I'd be inclined to.
>
yes, sphix can generate the numbering.

> >  4.2 Using MSI
> > +-------------
> >  
> >  Most of the hard work is done for the driver in the PCI layer.  The driver
> >  simply has to request that the PCI layer set up the MSI capability for this
> >  device.
> >  
> >  To automatically use MSI or MSI-X interrupt vectors, use the following
> > -function:
> > +function::
> >  
> >    int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
> >  		unsigned int max_vecs, unsigned int flags);
> 
> This should really be turned into kernel-doc and moved to pci.h, but
> that seems like an awfully large amount of work to ask you to do when
> you're already doing so much to improve the situation.
> 
> This is also a really bad document.  It has three audiences; people
> configuring their kernel, people writing device drivers and people trying
> to debug why their kernel doesn't work.  Again, that's not on you to
> fix, but it's pretty frustrating to see so much good information so
> badly organised.
I agree. But content improvment is out of this topic. So I will just
do the conversion in this serias.

-- 
Cheers,
Changbin Du