On Tue, Oct 4, 2022 at 8:56 AM Dave Thaler <dthaler@xxxxxxxxxxxxx> wrote: > > Also worth noting that Quentin has a script that I believe parses the appendix > and uses it to generate a validator for ebpf programs. (Which also > helps validate the appendix). The last thing I want to see is a document becoming a description of the code. We've always been doing it the other way around. The documentation can live next to the code and docs automatically generated from .h or .c files. Doing the other way around sooner or later will be a disaster. Imagine a typo in instruction-set.rst. What should we do next? Fix a typo and say, look, the code behaves differently, so we're fixing the doc. If so, there is close to zero reason to add hex to the doc, since it's not an authoritative answer. On the other hand if instruction-set.rst is the source of the truth then the code would have to change, which we obviously cannot do. So let's not get us into the corner with such tables. > Dave > > > -----Original Message----- > > From: Dave Thaler > > Sent: Tuesday, October 4, 2022 8:55 AM > > To: 'Alexei Starovoitov' <alexei.starovoitov@xxxxxxxxx> > > Cc: bpf@xxxxxxxxxxxxxxx > > Subject: RE: [PATCH 11/15] ebpf-docs: Improve English readability > > > > > > I found it very helpful in verifying that the Appendix table was > > > > correct, and providing a correlation to the text here that shows the > > > > construction of the value. So I'd like to keep them. > > > > > > I think that means that the appendix table shouldn't be there either. > > > I'd like to avoid both. > > > > I've heard from multiple people with different affiliations that the appendix > > is the most useful part of the document, and what they wanted to see > > added. So I added by popular request. These people should speak up then.
