| Message ID | 20220721110821.8240-1-alx.manpages@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 5cb62b7598f2413f54650d5124d7863e23f82a44 |
| Delegated to: | BPF |
| Headers | show |
| Series | bpf_doc.py: Use SPDX-License-Identifier | expand |
| Context | Check | Description |
|---|---|---|
| bpf/vmtest-bpf-next-VM_Test-1 | success | Logs for Kernel LATEST on ubuntu-latest with gcc |
| bpf/vmtest-bpf-next-VM_Test-2 | success | Logs for Kernel LATEST on ubuntu-latest with llvm-15 |
| bpf/vmtest-bpf-next-PR | success | PR summary |
| bpf/vmtest-bpf-next-VM_Test-3 | success | Logs for Kernel LATEST on z15 with gcc |
| netdev/tree_selection | success | Not a local patch, async |
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!
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
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
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
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
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
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(-)