netdev - Re: [PATCH bpf-next 3/3] tools: bpftool: automate generation for "SEE ALSO" sections in man pages

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <ca595fd6-e807-ac8e-f15f-68bfc7b7dbc4@isovalent.com>
Date:   Mon, 7 Sep 2020 15:50:53 +0100
From:   Quentin Monnet <quentin@...valent.com>
To:     Andrii Nakryiko <andrii.nakryiko@...il.com>
Cc:     Alexei Starovoitov <ast@...nel.org>,
        Daniel Borkmann <daniel@...earbox.net>,
        bpf <bpf@...r.kernel.org>, Networking <netdev@...r.kernel.org>
Subject: Re: [PATCH bpf-next 3/3] tools: bpftool: automate generation for "SEE
 ALSO" sections in man pages

On 04/09/2020 22:51, Andrii Nakryiko wrote:
> On Fri, Sep 4, 2020 at 1:58 PM Quentin Monnet <quentin@...valent.com> wrote:
>>
>> The "SEE ALSO" sections of bpftool's manual pages refer to bpf(2),
>> bpf-helpers(7), then all existing bpftool man pages (save the current
>> one).
>>
>> This leads to nearly-identical lists being duplicated in all manual
>> pages. Ideally, when a new page is created, all lists should be updated
>> accordingly, but this has led to omissions and inconsistencies multiple
>> times in the past.
>>
>> Let's take it out of the RST files and generate the "SEE ALSO" sections
>> automatically in the Makefile when generating the man pages. The lists
>> are not really useful in the RST anyway because all other pages are
>> available in the same directory.
>>
>> Signed-off-by: Quentin Monnet <quentin@...valent.com>
>> ---
> 
> Acked-by: Andrii Nakryiko <andriin@...com>
> 
> but see note about printf and format string below

Thanks!

>> diff --git a/tools/bpf/bpftool/Documentation/Makefile b/tools/bpf/bpftool/Documentation/Makefile
>> index becbb8c52257..86233619215c 100644
>> --- a/tools/bpf/bpftool/Documentation/Makefile
>> +++ b/tools/bpf/bpftool/Documentation/Makefile
>> @@ -29,11 +29,21 @@ man8: $(DOC_MAN8)
>>
>>  RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null)
>>
>> +list_pages = $(sort $(basename $(filter-out $(1),$(MAN8_RST))))
>> +see_also = $(subst " ",, \
>> +       "\n" \
>> +       "SEE ALSO\n" \
>> +       "========\n" \
>> +       "\t**bpf**\ (2),\n" \
>> +       "\t**bpf-helpers**\\ (7)" \
>> +       $(foreach page,$(call list_pages,$(1)),",\n\t**$(page)**\\ (8)") \
>> +       "\n")
>> +
>>  $(OUTPUT)%.8: %.rst
>>  ifndef RST2MAN_DEP
>>         $(error "rst2man not found, but required to generate man pages")
>>  endif
>> -       $(QUIET_GEN)rst2man $< > $@
>> +       $(QUIET_GEN)( cat $< ; printf $(call see_also,$<) ) | rst2man > $@
> 
> a bit dangerous to pass string directly as a format string due to %
> interpretation. Did you try echo -e "...\n..." ?

I believe printf is supposed to be more portable, this is why I used it.
It seems unlikely we end up with a percent sign in a bpftool man page
name, but I can switch to "echo -e" for v2.

Quentin