Commit 18841da9 authored by Quentin Monnet's avatar Quentin Monnet Committed by Alexei Starovoitov
Browse files

tools: bpftool: Automate generation for "SEE ALSO" sections in man pages 



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.

v3:
- Fix conflict with a previous patchset that introduced RST2MAN_OPTS
  variable passed to rst2man.

v2:
- Use "echo -n" instead of "printf" in Makefile, to avoid any risk of
  passing a format string directly to the command.

Signed-off-by: default avatarQuentin Monnet <quentin@isovalent.com>
Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
Acked-by: default avatarAndrii Nakryiko <andriin@fb.com>
Link: https://lore.kernel.org/bpf/20200910203935.25304-1-quentin@isovalent.com
parent 1aef5b43

tools/bpf/bpftool/Documentation/Makefile

+11 −1
Original line number Diff line number Diff line
@@ -30,11 +30,21 @@ man8: $(DOC_MAN8) 
RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null)

RST2MAN_OPTS += --verbose



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 $(RST2MAN_OPTS) $< > $@

	$(QUIET_GEN)( cat $< ; echo -n $(call see_also,$<) ) | rst2man $(RST2MAN_OPTS) > $@



clean: helpers-clean

	$(call QUIET_CLEAN, Documentation)

tools/bpf/bpftool/Documentation/bpftool-btf.rst

+0 −17
Original line number Diff line number Diff line
@@ -217,20 +217,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**
 


SEE ALSO

========

	**bpf**\ (2),

	**bpf-helpers**\ (7),

	**bpftool**\ (8),

	**bpftool-btf**\ (8),

	**bpftool-cgroup**\ (8),

	**bpftool-feature**\ (8),

	**bpftool-gen**\ (8),

	**bpftool-iter**\ (8),

	**bpftool-link**\ (8),

	**bpftool-map**\ (8),

	**bpftool-net**\ (8),

	**bpftool-perf**\ (8),

	**bpftool-prog**\ (8),

	**bpftool-struct_ops**\ (8)

tools/bpf/bpftool/Documentation/bpftool-cgroup.rst

+0 −16
Original line number Diff line number Diff line
@@ -143,19 +143,3 @@ EXAMPLES 
::



    ID       AttachType      AttachFlags     Name
 


SEE ALSO

========

	**bpf**\ (2),

	**bpf-helpers**\ (7),

	**bpftool**\ (8),

	**bpftool-btf**\ (8),

	**bpftool-feature**\ (8),

	**bpftool-gen**\ (8),

	**bpftool-iter**\ (8),

	**bpftool-link**\ (8),

	**bpftool-map**\ (8),

	**bpftool-net**\ (8),

	**bpftool-perf**\ (8),

	**bpftool-prog**\ (8),

	**bpftool-struct_ops**\ (8)

tools/bpf/bpftool/Documentation/bpftool-feature.rst

+0 −16
Original line number Diff line number Diff line
@@ -72,19 +72,3 @@ DESCRIPTION 
OPTIONS

=======

	.. include:: common_options.rst
 


SEE ALSO

========

	**bpf**\ (2),

	**bpf-helpers**\ (7),

	**bpftool**\ (8),

	**bpftool-btf**\ (8),

	**bpftool-cgroup**\ (8),

	**bpftool-gen**\ (8),

	**bpftool-iter**\ (8),

	**bpftool-link**\ (8),

	**bpftool-map**\ (8),

	**bpftool-net**\ (8),

	**bpftool-perf**\ (8),

	**bpftool-prog**\ (8),

	**bpftool-struct_ops**\ (8)

tools/bpf/bpftool/Documentation/bpftool-gen.rst

+0 −16
Original line number Diff line number Diff line
@@ -279,19 +279,3 @@ and global variables. 
  my_static_var: 7



This is a stripped-out version of skeleton generated for above example code.
 


SEE ALSO

========

	**bpf**\ (2),

	**bpf-helpers**\ (7),

	**bpftool**\ (8),

	**bpftool-btf**\ (8),

	**bpftool-cgroup**\ (8),

	**bpftool-feature**\ (8),

	**bpftool-iter**\ (8),

	**bpftool-link**\ (8),

	**bpftool-map**\ (8),

	**bpftool-net**\ (8),

	**bpftool-perf**\ (8),

	**bpftool-prog**\ (8),

	**bpftool-struct_ops**\ (8)