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; but if something changes in that script, it would be nice to notify us, if we're using them.
Whatever you prefer. Thanks, Alex
Many thanks, Quentin [0] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/bpf_doc.py?h=v5.18 [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/bpf.h?h=v5.18#n1526 [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/Makefile.docs?h=v5.18 [3] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/bpf/Makefile?h=v5.18#n159
-- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
