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: <CAEf4BzYFDi2w5mbu1Dgb6aTR2HsAXDs0=QbfUc-hwCHngKsaCg@mail.gmail.com>
Date:   Fri, 4 Sep 2020 14:51:20 -0700
From:   Andrii Nakryiko <andrii.nakryiko@...il.com>
To:     Quentin Monnet <quentin@...valent.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 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

>  tools/bpf/bpftool/Documentation/Makefile        | 12 +++++++++++-
>  tools/bpf/bpftool/Documentation/bpftool-btf.rst | 17 -----------------
>  .../bpftool/Documentation/bpftool-cgroup.rst    | 16 ----------------
>  .../bpftool/Documentation/bpftool-feature.rst   | 16 ----------------
>  tools/bpf/bpftool/Documentation/bpftool-gen.rst | 16 ----------------
>  .../bpf/bpftool/Documentation/bpftool-iter.rst  | 16 ----------------
>  .../bpf/bpftool/Documentation/bpftool-link.rst  | 17 -----------------
>  tools/bpf/bpftool/Documentation/bpftool-map.rst | 16 ----------------
>  tools/bpf/bpftool/Documentation/bpftool-net.rst | 17 -----------------
>  .../bpf/bpftool/Documentation/bpftool-perf.rst  | 17 -----------------
>  .../bpf/bpftool/Documentation/bpftool-prog.rst  | 16 ----------------
>  .../Documentation/bpftool-struct_ops.rst        | 17 -----------------
>  tools/bpf/bpftool/Documentation/bpftool.rst     | 16 ----------------
>  13 files changed, 11 insertions(+), 198 deletions(-)
>
> 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..." ?

>
>  clean: helpers-clean
>         $(call QUIET_CLEAN, Documentation)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-btf.rst b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
> index 0020bb55cf7e..b3e909ef6791 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-btf.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
> @@ -214,20 +214,3 @@ All the standard ways to specify map or program are supported:
>  **# bpftool btf dump prog tag b88e0a09b1d9759d**
>
>  **# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**

[...]