Skip to content

Commit 18841da

Browse files
qmonnetAlexei Starovoitov
qmonnet
authored and
Alexei Starovoitov
committed
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: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Andrii Nakryiko <andriin@fb.com> Link: https://lore.kernel.org/bpf/20200910203935.25304-1-quentin@isovalent.com
1 parent 1aef5b4 commit 18841da

File tree

13 files changed

+11
-198
lines changed

13 files changed

+11
-198
lines changed

‎tools/bpf/bpftool/Documentation/Makefile‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,21 @@ man8: $(DOC_MAN8)
3030
RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null)
3131
RST2MAN_OPTS += --verbose
3232

33+
list_pages = $(sort $(basename $(filter-out $(1),$(MAN8_RST))))
34+
see_also = $(subst " ",, \
35+
"\n" \
36+
"SEE ALSO\n" \
37+
"========\n" \
38+
"\t**bpf**\ (2),\n" \
39+
"\t**bpf-helpers**\\ (7)" \
40+
$(foreach page,$(call list_pages,$(1)),",\n\t**$(page)**\\ (8)") \
41+
"\n")
42+
3343
$(OUTPUT)%.8: %.rst
3444
ifndef RST2MAN_DEP
3545
$(error "rst2man not found, but required to generate man pages")
3646
endif
37-
$(QUIET_GEN)rst2man $(RST2MAN_OPTS) $< > $@
47+
$(QUIET_GEN)( cat $< ; echo -n $(call see_also,$<) ) | rst2man $(RST2MAN_OPTS) > $@
3848

3949
clean: helpers-clean
4050
$(call QUIET_CLEAN, Documentation)

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

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -217,20 +217,3 @@ All the standard ways to specify map or program are supported:
217217
**# bpftool btf dump prog tag b88e0a09b1d9759d**
218218

219219
**# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
220-
221-
SEE ALSO
222-
========
223-
**bpf**\ (2),
224-
**bpf-helpers**\ (7),
225-
**bpftool**\ (8),
226-
**bpftool-btf**\ (8),
227-
**bpftool-cgroup**\ (8),
228-
**bpftool-feature**\ (8),
229-
**bpftool-gen**\ (8),
230-
**bpftool-iter**\ (8),
231-
**bpftool-link**\ (8),
232-
**bpftool-map**\ (8),
233-
**bpftool-net**\ (8),
234-
**bpftool-perf**\ (8),
235-
**bpftool-prog**\ (8),
236-
**bpftool-struct_ops**\ (8)

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

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -143,19 +143,3 @@ EXAMPLES
143143
::
144144

145145
ID AttachType AttachFlags Name
146-
147-
SEE ALSO
148-
========
149-
**bpf**\ (2),
150-
**bpf-helpers**\ (7),
151-
**bpftool**\ (8),
152-
**bpftool-btf**\ (8),
153-
**bpftool-feature**\ (8),
154-
**bpftool-gen**\ (8),
155-
**bpftool-iter**\ (8),
156-
**bpftool-link**\ (8),
157-
**bpftool-map**\ (8),
158-
**bpftool-net**\ (8),
159-
**bpftool-perf**\ (8),
160-
**bpftool-prog**\ (8),
161-
**bpftool-struct_ops**\ (8)

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

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -72,19 +72,3 @@ DESCRIPTION
7272
OPTIONS
7373
=======
7474
.. include:: common_options.rst
75-
76-
SEE ALSO
77-
========
78-
**bpf**\ (2),
79-
**bpf-helpers**\ (7),
80-
**bpftool**\ (8),
81-
**bpftool-btf**\ (8),
82-
**bpftool-cgroup**\ (8),
83-
**bpftool-gen**\ (8),
84-
**bpftool-iter**\ (8),
85-
**bpftool-link**\ (8),
86-
**bpftool-map**\ (8),
87-
**bpftool-net**\ (8),
88-
**bpftool-perf**\ (8),
89-
**bpftool-prog**\ (8),
90-
**bpftool-struct_ops**\ (8)

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

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -279,19 +279,3 @@ and global variables.
279279
my_static_var: 7
280280

281281
This is a stripped-out version of skeleton generated for above example code.
282-
283-
SEE ALSO
284-
========
285-
**bpf**\ (2),
286-
**bpf-helpers**\ (7),
287-
**bpftool**\ (8),
288-
**bpftool-btf**\ (8),
289-
**bpftool-cgroup**\ (8),
290-
**bpftool-feature**\ (8),
291-
**bpftool-iter**\ (8),
292-
**bpftool-link**\ (8),
293-
**bpftool-map**\ (8),
294-
**bpftool-net**\ (8),
295-
**bpftool-perf**\ (8),
296-
**bpftool-prog**\ (8),
297-
**bpftool-struct_ops**\ (8)

‎tools/bpf/bpftool/Documentation/bpftool-iter.rst‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -68,19 +68,3 @@ EXAMPLES
6868

6969
Create a file-based bpf iterator from bpf_iter_hashmap.o and map with
7070
id 20, and pin it to /sys/fs/bpf/my_hashmap
71-
72-
SEE ALSO
73-
========
74-
**bpf**\ (2),
75-
**bpf-helpers**\ (7),
76-
**bpftool**\ (8),
77-
**bpftool-btf**\ (8),
78-
**bpftool-cgroup**\ (8),
79-
**bpftool-feature**\ (8),
80-
**bpftool-gen**\ (8),
81-
**bpftool-link**\ (8),
82-
**bpftool-map**\ (8),
83-
**bpftool-net**\ (8),
84-
**bpftool-perf**\ (8),
85-
**bpftool-prog**\ (8),
86-
**bpftool-struct_ops**\ (8)

‎tools/bpf/bpftool/Documentation/bpftool-link.rst‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -106,20 +106,3 @@ EXAMPLES
106106
::
107107

108108
-rw------- 1 root root 0 Apr 23 21:39 link
109-
110-
111-
SEE ALSO
112-
========
113-
**bpf**\ (2),
114-
**bpf-helpers**\ (7),
115-
**bpftool**\ (8),
116-
**bpftool-btf**\ (8),
117-
**bpftool-cgroup**\ (8),
118-
**bpftool-feature**\ (8),
119-
**bpftool-gen**\ (8),
120-
**bpftool-iter**\ (8),
121-
**bpftool-map**\ (8),
122-
**bpftool-net**\ (8),
123-
**bpftool-perf**\ (8),
124-
**bpftool-prog**\ (8),
125-
**bpftool-struct_ops**\ (8)

‎tools/bpf/bpftool/Documentation/bpftool-map.rst‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -270,19 +270,3 @@ would be lost as soon as bpftool exits).
270270

271271
key: 00 00 00 00 value: 22 02 00 00
272272
Found 1 element
273-
274-
SEE ALSO
275-
========
276-
**bpf**\ (2),
277-
**bpf-helpers**\ (7),
278-
**bpftool**\ (8),
279-
**bpftool-btf**\ (8),
280-
**bpftool-cgroup**\ (8),
281-
**bpftool-feature**\ (8),
282-
**bpftool-gen**\ (8),
283-
**bpftool-iter**\ (8),
284-
**bpftool-link**\ (8),
285-
**bpftool-net**\ (8),
286-
**bpftool-perf**\ (8),
287-
**bpftool-prog**\ (8),
288-
**bpftool-struct_ops**\ (8)

‎tools/bpf/bpftool/Documentation/bpftool-net.rst‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -172,20 +172,3 @@ EXAMPLES
172172
::
173173

174174
xdp:
175-
176-
177-
SEE ALSO
178-
========
179-
**bpf**\ (2),
180-
**bpf-helpers**\ (7),
181-
**bpftool**\ (8),
182-
**bpftool-btf**\ (8),
183-
**bpftool-cgroup**\ (8),
184-
**bpftool-feature**\ (8),
185-
**bpftool-gen**\ (8),
186-
**bpftool-iter**\ (8),
187-
**bpftool-link**\ (8),
188-
**bpftool-map**\ (8),
189-
**bpftool-perf**\ (8),
190-
**bpftool-prog**\ (8),
191-
**bpftool-struct_ops**\ (8)

‎tools/bpf/bpftool/Documentation/bpftool-perf.rst‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -63,20 +63,3 @@ EXAMPLES
6363
{"pid":21765,"fd":5,"prog_id":7,"fd_type":"kretprobe","func":"__x64_sys_nanosleep","offset":0}, \
6464
{"pid":21767,"fd":5,"prog_id":8,"fd_type":"tracepoint","tracepoint":"sys_enter_nanosleep"}, \
6565
{"pid":21800,"fd":5,"prog_id":9,"fd_type":"uprobe","filename":"/home/yhs/a.out","offset":1159}]
66-
67-
68-
SEE ALSO
69-
========
70-
**bpf**\ (2),
71-
**bpf-helpers**\ (7),
72-
**bpftool**\ (8),
73-
**bpftool-btf**\ (8),
74-
**bpftool-cgroup**\ (8),
75-
**bpftool-feature**\ (8),
76-
**bpftool-gen**\ (8),
77-
**bpftool-iter**\ (8),
78-
**bpftool-link**\ (8),
79-
**bpftool-map**\ (8),
80-
**bpftool-net**\ (8),
81-
**bpftool-prog**\ (8),
82-
**bpftool-struct_ops**\ (8)

0 commit comments

Comments
 (0)