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

["Michael S. Tsirkin" <mst@redhat.com>]

On Wed, Mar 22, 2023 at 04:52:36PM +0000, Parav Pandit wrote:
> 
> > 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.

Refer how?  \field{} is not a cross reference. It's a way to make
field names stand out to make sure readers do not think
this is plain english.

> 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.

That would involve rewriting MMIO description to match ccw and pci
using structs and not a table :)

> But comment is fine too.
> I will change to comment format for the struct.