Re: [PATCH bpf-next] scripts/bpf: Fix attributes for bpf-helpers(7) man page

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

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

Hi Quentin,

On 8/23/22 16:23, Quentin Monnet wrote:
> Wow, I'm two days late!

;-)

[...]
>>
>> You could append the version here.  Or maybe put a placeholder that the
>> script should fill with information from the makefile or git-describe(1)?
> 
> So if I understand correctly, running bpf_doc.py should currently
> produce the following string:
> 
>      .TH BPF-HELPERS 7 "" "Linux (5.19.0)" ""
> 
> Is this what you expect?

Almost.  I expect:

.TH BPF-HELPERS 7 "" "Linux 5.19.0"

Notice the differences:
- No 5th empty field "".
- No parentheses in the version string.

But since you're not in control of the last field, and it's just a bug 
in rst2man, an empty 5th arg as you suggested is the best you can 
provide.  I'll file the bug.

As for the parentheses in the version, I wouldn't put them; I only put 
them in the man-pages unreleased string, to make it clear that it's a 
version, but in the final version I remove them.

See:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/version.mk>
and
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/dist.mk#n33>

> 
> I can make the script call "make kernelversion" to produce the above.
> I'm not 100% convinced it should be the role of that script vs. when
> copying it (we risk having some inaccuracies, for example I generated
> the above from the bpf-next, so it doesn't really correspond to 5.19),
> but maybe it's easier that way and avoids adding another script in the
> middle of the generation so OK.

I like it that way.  Moreover, I'll always run this script from a 
release tag from Linus' repo, so the version should match exactly the code.

Anyway, and I think this affects many projects out there have the same 
issue:

The versioning should always be correct.  git-describe(1) should be 
preferred, or in absence of that, a generic (unreleased) string should 
be used.  Describing any commit after v5.18 and before v5.19-rc1 to be 
'5.18.0' is plain wrong/misleading.  The Makefile should probably 
autogenerate that info from git-describe(1).  See how the Linux 
man-pages do it (in the links above you can see it) for example.

Cheers,

Alex


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]