On Wed, Mar 22, 2023 at 04:52:36PM +0000, Parav Pandit wrote:
>
> > From: Michael S. Tsirkin <[email protected]>
> > 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 <[email protected]>
> > > > 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
