[virtio-dev] 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 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.

> > 
> > 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.
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 will change to comment format.


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org