On Wed, 20 Jul 2022 at 22:07, Alejandro Colomar <alx.manpages@xxxxxxxxx> wrote: > > Hi Quentin, > > On 7/20/22 22:40, Quentin Monnet wrote: > > On Wed, 20 Jul 2022 at 10:50, Alejandro Colomar <alx.manpages@xxxxxxxxx> wrote: > >> > >> Hi Rumen, > >> > >> On 7/19/22 19:21, Rumen Telbizov wrote: > >>> Hi Alejandro, > >>> > >>> Thanks for following up on this. > >>> Quentin will send you the script these days for you to rerun. > >>> However, I'm wondering if there's a way to run it automatically when a change is > >>> detected or otherwise without needing manual intervention? This way > >>> the published > >>> page will not get out of date. I am not sure what that mechanism might be but > >>> just a thought. > >> > >> I'm not sure an automated mechanism would be easy to set up. > >> But, I'm planning to add a RELEASE file to the man-pages repo with > >> instructions to make a release. I can add there a step that reminds to > >> refresh the bpf-helpers(7) manual page before every release. > > > > Hi Alejandro, Rumen, > > > > Thank you Rumen for raising this. Yes, the bpf-helpers(7) man page is > > generated from a script: it's scripts/bpf_doc.py under the kernel > > repository [0], which parses the UAPI header at > > include/uapi/linux/bpf.h [1] to generate a rST file that can be > > converted to a man page. From the root of the Linux repository, one > > can generate and read the manual page with the following command: > > > > $ ./scripts/bpf_doc.py helpers | rst2man | man -l - > > > > (Note that the name of the script has changed since man-page commit > > 53666f6c3045.) > > Okay, that makes sense (I tried to find the script mentioned in that > commit, and din't find it). > > > > Given that the script is maintained in the Linux repository (it is run > > through the BPF CI [2], and it is also used to generate a C header > > that is shipped along with libbpf [3]), I would recommend against > > copying it to the man-pages repository, so that we avoid getting two > > copies out-of-sync. It is probably best to pick it up from the Linux > > repo (since the UAPI header is also required anyway) when regenerating > > the page. > > > > Yes, having it in the kernel, since you also use it for other thing, > makes sense to me. I can make a note of that in our future RELEASE > instructions. For now, I'll document it in a new commit message. > > > If automation is not doable, I would be very happy to have someone > > running this step before each project release. > > If you send a man-pages patch after every kernel release, that would be > great. We can also do that ourselves, as long as the tools are there; Since you're offering, I wouldn't mind leaving it to you to run the script before each release. I'm willing to help, but I don't really trust myself with remembering this every time, so having it written down as one of the steps in your RELEASE file is probably the best way to make sure the update happens. Please do reach out if the script didn't behave as expected, though. I'll be happy to assist. > but if something changes in that script, it would be nice to notify us, > if we're using them. I do realise we failed to send a notice when we renamed the script, please accept my apologies for that. I'll be more careful in the future. Thanks, Quentin
