Re: [PATCH] bpf, docs: Use consistent names for the same field

[David Vernet <void@manifault.com>]

On Fri, Jan 27, 2023 at 02:09:28AM +0000, Dave Thaler wrote:
> David Vernet <void@manifault.com> wrote: 
> > In the future, if sending subsequent iterations of a patch, could you please
> > follow the typical versioning  and changelog convention described in [0]?
> 
> Thanks for being patient with a newcomer to this particular process :)

No problem, the process can be a bit arcane :-)

> 
> > >  =============  =======  ===============  ====================
> > ============
> > >  32 bits (MSB)  16 bits  4 bits           4 bits                8 bits (LSB)
> > >  =============  =======  ===============  ====================
> > ============
> > > -immediate      offset   source register  destination register  opcode
> > > +imm            offset   src              dst                   opcode
> > 
> > What's the rationale for changing source register and destination register to
> > src and dst respectively here? Below you clarify that they mean something
> > other than register number after this section in the document, so why not
> > just leave them as is here to avoid any confusion?
> 
> Fair point, will update.
> 
> > Can we make all of these bold, just to slightly improve readability.
> > E.g.:
> > 
> > **imm**
> 
> My view was that it was up to the RST renderer to do so. For example,
> if you look at https://github.com/ebpffoundation/ebpf-docs/blob/update/rst/instruction-set.rst which is what I used
> to validate the look of this patch plus other patches, it is already
> bolded because the github RST renderer bolds definition list terms.
> 
> On the other hand, https://htmlpreview.github.io/?https://raw.githubusercontent.com/ebpffoundation/ebpf-docs/pdf/draft-thaler-bpf-isa.html#section-3 is the output of RST -> xml2rfcv3 -> HTML
> doesn't do so.  That could be addressed either by me updating the
> RST -> xml2rfcv3 converter to automatically bold (i.e., add <strong> to the XML)
> or by adding an explicit bolding as you suggest.
> 
> I guess the benefit of adding the bolding into the RST itself is if there
> are other RST renderers that don't automatically bold definition list terms but
> we want them to.  I see other RST files in the Documentation/bpf directory
> vary in terms of whether any explicit bolding is used, but I see maps.rst
> does so, so I will go ahead and do this and make the RST -> xml2rfcv3
> converter map bolding correctly to xml.

Yeah, definition list items are weird. Not a huge deal either way, but
my preference would be to just force the issue by using the ** ... **
syntax to make it bold. Sounds like we're in agreement.

Thanks,
David