RE: [PATCH v3 6/8] transport-ccw: Refer to the vq by its number

[Parav Pandit <parav@nvidia.com>]

> From: Michael S. Tsirkin <mst@redhat.com>
> Sent: Tuesday, March 21, 2023 11:53 PM
> 
> On Wed, Mar 22, 2023 at 02:45:00AM +0000, Parav Pandit wrote:
> >
> > > From: Michael S. Tsirkin <mst@redhat.com>
> > > Sent: Tuesday, March 21, 2023 6:22 PM
> >
> > > > +\begin{note}
> > > > +\field{queue_select} was previously named as index.
> > >
> > > sounds a bit strange, and \field{} is missing. If you insist I'd say
> > > 	in previous versions of this specification,
> > > 	field{queue_select} was also called queue \field{index}
> > >
> > The field is missing because field index is no longer there.
> 
> But it was there. Look what it does, it formats in italics so it stands out from
> rest of text, making it clear it is field name (former one) and not the word
> "index" in english.
True, but since that field index was written what would it refer to.
Anyway, not important once its part of the structure comment.
> 
> > >
> > > e.g. in blk we have this:
> > >   In the legacy interface, VIRTIO_BLK_F_FLUSH was also
> > >   called VIRTIO_BLK_F_WCE.
> > >
> > >
> > > but I really feel this misses the point, the compat is needed in the
> > > struct definition, not split out after usage is described. This is
> > > why I proposed just making this a comment in the struct. Why not?
> > >
> > Sure comment is good to me too.
> > In v0 you specifically asked to add note with example.
> > You said "like "Note: this was previously known as QueueNumMax""
> > It is hard to guess to write a comment when you mean "Note". :)
> 
> That referred to MMIO where it's a table not a listing.
> I did not check the generated PDF the point is to make the note appear near the
> field and also not damage the layout.
Yes, the note is next to the field. I looked in the PDF.
> Pls take a look at how it looks in PDF - another option is a footnote though it's a
> bit harder for readers to find these and bad for accessibility. Again I don't think
> these work in listings, there we are kind of limited to code comments.
> 
I was trying to have uniform note for mmio and ccw regardless off struct vs table.
But comment is fine too.
I will change to comment format for the struct.