[PATCH] bpf_doc.py: Use SPDX-License-Identifier

[PATCH] bpf_doc.py: Use SPDX-License-Identifier

[Alejandro Colomar]

The Linux man-pages project now uses SPDX tags,
instead of the full license text.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 scripts/bpf_doc.py | 22 +---------------------
 1 file changed, 1 insertion(+), 21 deletions(-)

diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py
index 096625242475..74df2955737a 100755
--- a/scripts/bpf_doc.py
+++ b/scripts/bpf_doc.py
@@ -333,27 +333,7 @@ class PrinterRST(Printer):
 .. Copyright (C) All BPF authors and contributors from 2014 to present.
 .. See git log include/uapi/linux/bpf.h in kernel tree for details.
 .. 
-.. %%%LICENSE_START(VERBATIM)
-.. Permission is granted to make and distribute verbatim copies of this
-.. manual provided the copyright notice and this permission notice are
-.. preserved on all copies.
-.. 
-.. Permission is granted to copy and distribute modified versions of this
-.. manual under the conditions for verbatim copying, provided that the
-.. entire resulting derived work is distributed under the terms of a
-.. permission notice identical to this one.
-.. 
-.. Since the Linux kernel and libraries are constantly changing, this
-.. manual page may be incorrect or out-of-date.  The author(s) assume no
-.. responsibility for errors or omissions, or for damages resulting from
-.. the use of the information contained herein.  The author(s) may not
-.. have taken the same level of care in the production of this manual,
-.. which is licensed free of charge, as they might when working
-.. professionally.
-.. 
-.. Formatted or processed versions of this manual, if unaccompanied by
-.. the source, must acknowledge the copyright and authors of this work.
-.. %%%LICENSE_END
+.. SPDX-License-Identifier:  Linux-man-pages-copyleft
 .. 
 .. Please do not edit this file. It was generated from the documentation
 .. located in file include/uapi/linux/bpf.h of the Linux kernel sources
-- 
2.36.1

Re: [PATCH] bpf_doc.py: Use SPDX-License-Identifier

[patchwork-bot+netdevbpf]

Hello:

This patch was applied to bpf/bpf-next.git (master)
by Daniel Borkmann <daniel@iogearbox.net>:

On Thu, 21 Jul 2022 13:08:22 +0200 you wrote:
> The Linux man-pages project now uses SPDX tags,
> instead of the full license text.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  scripts/bpf_doc.py | 22 +---------------------
>  1 file changed, 1 insertion(+), 21 deletions(-)

Here is the summary with links:
  - bpf_doc.py: Use SPDX-License-Identifier
    https://git.kernel.org/bpf/bpf-next/c/5cb62b7598f2

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html

bpf-helpers.7: .TH line is... meh (was: [PATCH] bpf_doc.py: Use SPDX-License-Identifier)

[Alejandro Colomar]

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

Hi Daniel,

On 7/22/22 00:50, patchwork-bot+netdevbpf@kernel.org wrote:
> Hello:
> 
> This patch was applied to bpf/bpf-next.git (master)
> by Daniel Borkmann <daniel@iogearbox.net>:
> 
> On Thu, 21 Jul 2022 13:08:22 +0200 you wrote:
>> The Linux man-pages project now uses SPDX tags,
>> instead of the full license text.
>>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>> ---
>>   scripts/bpf_doc.py | 22 +---------------------
>>   1 file changed, 1 insertion(+), 21 deletions(-)
> 
> Here is the summary with links:
>    - bpf_doc.py: Use SPDX-License-Identifier
>      https://git.kernel.org/bpf/bpf-next/c/5cb62b7598f2
> 
> You are awesome, thank you!

Oh, what a nice bot :)


I've been running a linter on the man-pages, and had this triggered from 
bpf-helpers.7:

[
$ make lint V=1
LINT (groff)	tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch
groff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww  -z 
man7/bpf-helpers.7
an.tmac:man7/bpf-helpers.7:3: style: .TH missing third argument; suggest 
document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:man7/bpf-helpers.7:3: style: .TH missing fourth argument; 
suggest package/project name and version (e.g., "groff 1.23.0")
an.tmac:man7/bpf-helpers.7:3: style: .TH missing fifth argument and 
second argument '7' not a recognized manual section; specify volume title
found style problems; aborting
make: *** [lib/lint-man.mk:49: 
tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch] Error 1

]

See what a normal .TH line looks like, and what bpf-helpers.7 has:

[
$ grep ^.TH man2/bpf.2
.TH BPF 2 2021-08-27 "Linux" "Linux Programmer's Manual"
$ grep ^.TH man7/bpf-helpers.7
.TH BPF-HELPERS 7 "" "" ""
]


I don't know if you can fix that, or if it's a limitation of the 
generator?  I can live with it, but it would be nice if it could be 
fixed.  It provides the headers and footers of the manual page.


Cheers,

Alex

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

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

Re: bpf-helpers.7: .TH line is... meh (was: [PATCH] bpf_doc.py: Use SPDX-License-Identifier)

[Quentin Monnet]

On 01/08/2022 23:13, Alejandro Colomar wrote:
> Hi Daniel,

Hi Alejandro,

I'm probably more familiar with this matter than Daniel, so let's see.

> 
> On 7/22/22 00:50, patchwork-bot+netdevbpf@kernel.org wrote:
>> Hello:
>>
>> This patch was applied to bpf/bpf-next.git (master)
>> by Daniel Borkmann <daniel@iogearbox.net>:
>>
>> On Thu, 21 Jul 2022 13:08:22 +0200 you wrote:
>>> The Linux man-pages project now uses SPDX tags,
>>> instead of the full license text.
>>>
>>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>>> ---
>>>   scripts/bpf_doc.py | 22 +---------------------
>>>   1 file changed, 1 insertion(+), 21 deletions(-)
>>
>> Here is the summary with links:
>>    - bpf_doc.py: Use SPDX-License-Identifier
>>      https://git.kernel.org/bpf/bpf-next/c/5cb62b7598f2
>>
>> You are awesome, thank you!
> 
> Oh, what a nice bot :)
> 
> 
> I've been running a linter on the man-pages, and had this triggered from
> bpf-helpers.7:
> 
> [
> $ make lint V=1
> LINT (groff)    tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch
> groff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww  -z
> man7/bpf-helpers.7
> an.tmac:man7/bpf-helpers.7:3: style: .TH missing third argument; suggest
> document modification date in ISO 8601 format (YYYY-MM-DD)
> an.tmac:man7/bpf-helpers.7:3: style: .TH missing fourth argument;
> suggest package/project name and version (e.g., "groff 1.23.0")
> an.tmac:man7/bpf-helpers.7:3: style: .TH missing fifth argument and
> second argument '7' not a recognized manual section; specify volume title
> found style problems; aborting

Not sure I understand this last one. Isn't "7" a valid man section?

> make: *** [lib/lint-man.mk:49:
> tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch] Error 1
> 
> ]
> 
> See what a normal .TH line looks like, and what bpf-helpers.7 has:
> 
> [
> $ grep ^.TH man2/bpf.2
> .TH BPF 2 2021-08-27 "Linux" "Linux Programmer's Manual"
> $ grep ^.TH man7/bpf-helpers.7
> .TH BPF-HELPERS 7 "" "" ""
> ]
> 
> 
> I don't know if you can fix that, or if it's a limitation of the
> generator?  I can live with it, but it would be nice if it could be
> fixed.  It provides the headers and footers of the manual page.

I had never really looked into completing this line before, but it seems
that Docutils/rst2man has a few (albeit not much documented) docinfo
elements available to complete _some_ of these fields. We currently have
":Manual section: 7" in the generated page. I can generate a page close
to the result above with:

    :Manual section: 7
    :Manual group: Linux Programmer's Manual
    :Version: Linux
    :Date: 2022-08-02

With these fields, I get:

    .TH BPF-HELPERS 7 "2022-08-03" "Linux" "Linux Programmer's Manual"

Caveats: First, we get additional double quotes around the date, not
sure if this matters.

Second: “Version” does not seem a relevant field name in that case, but
this is apparently the only option that we have to insert a value at
this location [0]. Apparently the manpage writer for Docutils assumes
that this line contains a version number [1].

Third: The date should of course be updated when generating the page. I
found that rst2man has a "--date" option, but it does not insert it at
the location we want. Instead, it would probably be a matter of adding a
sed command to the pipeline, something along:

    $ ./scripts/bpf_docs.py helpers | \
        sed -e "s/__DATE__/$(date -I)/" | \
        rst2man | man -l -

If it looks better for the man-pages repo, I can send a patch for the
man-page template in bpf_docs.py to set ":Manual group:" and
":Version:". I can also ask on the docutils mailing list if there is a
cleaner way to proceed, without falling back to this ":Version:" field.

Regards,
Quentin

[0]
https://repo.or.cz/docutils.git/blob/f031167579bdbe30781ea51d516d14db2cb5f60e:/docutils/writers/manpage.py#l377
[1] https://docutils.sourceforge.io/docs/user/manpage.html

Re: bpf-helpers.7: .TH line is... meh (was: [PATCH] bpf_doc.py: Use SPDX-License-Identifier)

[Alejandro Colomar]

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

Hi Quentin,

On 8/2/22 12:28, Quentin Monnet wrote:
>> I've been running a linter on the man-pages, and had this triggered from
>> bpf-helpers.7:
>>
>> [
>> $ make lint V=1
>> LINT (groff)    tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch
>> groff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww  -z
>> man7/bpf-helpers.7
>> an.tmac:man7/bpf-helpers.7:3: style: .TH missing third argument; suggest
>> document modification date in ISO 8601 format (YYYY-MM-DD)
>> an.tmac:man7/bpf-helpers.7:3: style: .TH missing fourth argument;
>> suggest package/project name and version (e.g., "groff 1.23.0")
>> an.tmac:man7/bpf-helpers.7:3: style: .TH missing fifth argument and
>> second argument '7' not a recognized manual section; specify volume title
>> found style problems; aborting
> 
> Not sure I understand this last one. Isn't "7" a valid man section?

It is a valid section.  I don't understand it either.  Maybe groff(1) 
has gone crazy after so many errors.  I'll report a bug to groff.

> 
>> make: *** [lib/lint-man.mk:49:
>> tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch] Error 1
>>
>> ]
>>
>> See what a normal .TH line looks like, and what bpf-helpers.7 has:
>>
>> [
>> $ grep ^.TH man2/bpf.2
>> .TH BPF 2 2021-08-27 "Linux" "Linux Programmer's Manual"
>> $ grep ^.TH man7/bpf-helpers.7
>> .TH BPF-HELPERS 7 "" "" ""
>> ]
>>
>>
>> I don't know if you can fix that, or if it's a limitation of the
>> generator?  I can live with it, but it would be nice if it could be
>> fixed.  It provides the headers and footers of the manual page.
> 
> I had never really looked into completing this line before, but it seems
> that Docutils/rst2man has a few (albeit not much documented) docinfo
> elements available to complete _some_ of these fields. We currently have
> ":Manual section: 7" in the generated page. I can generate a page close
> to the result above with:
> 
>      :Manual section: 7
>      :Manual group: Linux Programmer's Manual
>      :Version: Linux
>      :Date: 2022-08-02
> 
> With these fields, I get:
> 
>      .TH BPF-HELPERS 7 "2022-08-03" "Linux" "Linux Programmer's Manual"
> 
> Caveats: First, we get additional double quotes around the date, not
> sure if this matters.

Nah, quotes are only for spaces (they are ignored in this case).  You're 
fine with or without them.

> 
> Second: “Version” does not seem a relevant field name in that case, but
> this is apparently the only option that we have to insert a value at
> this location [0]. Apparently the manpage writer for Docutils assumes
> that this line contains a version number [1].

That field seems to be different, depending on who you ask.

In most cases, it's a "project and version" (see for example the groff 
warning text).

But in the linux man-pages, since we cover many projects and versions, 
we just say which project we're documenting (to avoid having to update 
the version every time, I guess).

See man-pages(7):
[
    Title line
        The first command in a man page should be a TH command:

               .TH title section date source manual

        The arguments of the command are as follows:

        [...]

        source The source of the  command,  function,  or  system
               call.

               For those few man‐pages pages in Sections 1 and 8,
               probably you just want to write GNU.

               For  system  calls, just write Linux.  (An earlier
               practice was to write the version  number  of  the
               kernel  from which the manual page was being writ‐
               ten/checked.  However, this was never done consis‐
               tently, and so was probably worse  than  including
               no  version number.  Henceforth, avoid including a
               version number.)

               For library calls that are part of glibc or one of
               the other common GNU libraries, just use GNU C Li‐
               brary, GNU, or an empty string.

               For Section 4 pages, use Linux.

               In cases of doubt, just write Linux, or GNU.

        [...]
]

So, just saying ':Version: Linux' would be fine.

> 
> Third: The date should of course be updated when generating the page. I
> found that rst2man has a "--date" option, but it does not insert it at
> the location we want. Instead, it would probably be a matter of adding a
> sed command to the pipeline, something along:
> 
>      $ ./scripts/bpf_docs.py helpers | \
>          sed -e "s/__DATE__/$(date -I)/" | \
>          rst2man | man -l -

The date, yeah, I can add it to the pipeline.
BTW, I reported a bug to rst2man (I CCd you, so you probably already 
know :)).

> 
> If it looks better for the man-pages repo, I can send a patch for the
> man-page template in bpf_docs.py to set ":Manual group:" and
> ":Version:". I can also ask on the docutils mailing list if there is a
> cleaner way to proceed, without falling back to this ":Version:" field.

Yeah, please patch :Manual group:.  Also patch :Version: (I think we can 
live with it), although of course feel free to ask about better 
alternatives to it.

But don't patch :Date: yet.  Let's see what they answer to the bug 
report.  (And if you want, you can wait for the bug report to resolve to 
patch everything at once, of course.)

Cheers,

Alex

> 
> Regards,
> Quentin
> 
> [0]
> https://repo.or.cz/docutils.git/blob/f031167579bdbe30781ea51d516d14db2cb5f60e:/docutils/writers/manpage.py#l377
> [1] https://docutils.sourceforge.io/docs/user/manpage.html

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

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

Re: bpf-helpers.7: .TH line is... meh (was: [PATCH] bpf_doc.py: Use SPDX-License-Identifier)

[Quentin Monnet]

On 02/08/2022 11:59, Alejandro Colomar wrote:
> Hi Quentin,
> 
> On 8/2/22 12:28, Quentin Monnet wrote:
>>> I've been running a linter on the man-pages, and had this triggered from
>>> bpf-helpers.7:
>>>
>>> [
>>> $ make lint V=1
>>> LINT (groff)    tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch
>>> groff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww  -z
>>> man7/bpf-helpers.7
>>> an.tmac:man7/bpf-helpers.7:3: style: .TH missing third argument; suggest
>>> document modification date in ISO 8601 format (YYYY-MM-DD)
>>> an.tmac:man7/bpf-helpers.7:3: style: .TH missing fourth argument;
>>> suggest package/project name and version (e.g., "groff 1.23.0")
>>> an.tmac:man7/bpf-helpers.7:3: style: .TH missing fifth argument and
>>> second argument '7' not a recognized manual section; specify volume
>>> title
>>> found style problems; aborting
>>
>> Not sure I understand this last one. Isn't "7" a valid man section?
> 
> It is a valid section.  I don't understand it either.  Maybe groff(1)
> has gone crazy after so many errors.  I'll report a bug to groff.
> 
>>
>>> make: *** [lib/lint-man.mk:49:
>>> tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch] Error 1
>>>
>>> ]
>>>
>>> See what a normal .TH line looks like, and what bpf-helpers.7 has:
>>>
>>> [
>>> $ grep ^.TH man2/bpf.2
>>> .TH BPF 2 2021-08-27 "Linux" "Linux Programmer's Manual"
>>> $ grep ^.TH man7/bpf-helpers.7
>>> .TH BPF-HELPERS 7 "" "" ""
>>> ]
>>>
>>>
>>> I don't know if you can fix that, or if it's a limitation of the
>>> generator?  I can live with it, but it would be nice if it could be
>>> fixed.  It provides the headers and footers of the manual page.
>>
>> I had never really looked into completing this line before, but it seems
>> that Docutils/rst2man has a few (albeit not much documented) docinfo
>> elements available to complete _some_ of these fields. We currently have
>> ":Manual section: 7" in the generated page. I can generate a page close
>> to the result above with:
>>
>>      :Manual section: 7
>>      :Manual group: Linux Programmer's Manual
>>      :Version: Linux
>>      :Date: 2022-08-02
>>
>> With these fields, I get:
>>
>>      .TH BPF-HELPERS 7 "2022-08-03" "Linux" "Linux Programmer's Manual"
>>
>> Caveats: First, we get additional double quotes around the date, not
>> sure if this matters.
> 
> Nah, quotes are only for spaces (they are ignored in this case).  You're
> fine with or without them.
> 
>>
>> Second: “Version” does not seem a relevant field name in that case, but
>> this is apparently the only option that we have to insert a value at
>> this location [0]. Apparently the manpage writer for Docutils assumes
>> that this line contains a version number [1].
> 
> That field seems to be different, depending on who you ask.
> 
> In most cases, it's a "project and version" (see for example the groff
> warning text).
> 
> But in the linux man-pages, since we cover many projects and versions,
> we just say which project we're documenting (to avoid having to update
> the version every time, I guess).
> 
> See man-pages(7):
> [
>    Title line
>        The first command in a man page should be a TH command:
> 
>               .TH title section date source manual
> 
>        The arguments of the command are as follows:
> 
>        [...]
> 
>        source The source of the  command,  function,  or  system
>               call.
> 
>               For those few man‐pages pages in Sections 1 and 8,
>               probably you just want to write GNU.
> 
>               For  system  calls, just write Linux.  (An earlier
>               practice was to write the version  number  of  the
>               kernel  from which the manual page was being writ‐
>               ten/checked.  However, this was never done consis‐
>               tently, and so was probably worse  than  including
>               no  version number.  Henceforth, avoid including a
>               version number.)
> 
>               For library calls that are part of glibc or one of
>               the other common GNU libraries, just use GNU C Li‐
>               brary, GNU, or an empty string.
> 
>               For Section 4 pages, use Linux.
> 
>               In cases of doubt, just write Linux, or GNU.
> 
>        [...]
> ]
> 
> So, just saying ':Version: Linux' would be fine.
> 
>>
>> Third: The date should of course be updated when generating the page. I
>> found that rst2man has a "--date" option, but it does not insert it at
>> the location we want. Instead, it would probably be a matter of adding a
>> sed command to the pipeline, something along:
>>
>>      $ ./scripts/bpf_docs.py helpers | \
>>          sed -e "s/__DATE__/$(date -I)/" | \
>>          rst2man | man -l -
> 
> The date, yeah, I can add it to the pipeline.
> BTW, I reported a bug to rst2man (I CCd you, so you probably already
> know :)).
> 
>>
>> If it looks better for the man-pages repo, I can send a patch for the
>> man-page template in bpf_docs.py to set ":Manual group:" and
>> ":Version:". I can also ask on the docutils mailing list if there is a
>> cleaner way to proceed, without falling back to this ":Version:" field.
> 
> Yeah, please patch :Manual group:.  Also patch :Version: (I think we can
> live with it), although of course feel free to ask about better
> alternatives to it.
> 
> But don't patch :Date: yet.  Let's see what they answer to the bug
> report.  (And if you want, you can wait for the bug report to resolve to
> patch everything at once, of course.)

Thanks for the precisions, and for opening the bug!
OK, I'll follow the discussion on the bug and wait to see how it goes.
I've set a reminder to myself to update the other info in a few weeks if
nothing happens by then.

Thanks,
Quentin