Re: Update bpf-helpers(7) man page

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3227 bytes --]

Hi Quentin,

On 7/20/22 22:40, Quentin Monnet wrote:
> On Wed, 20 Jul 2022 at 10:50, Alejandro Colomar <alx.manpages@gmail.com> 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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]