tools: bpftool: Include common options from separate file

Nearly all man pages for bpftool have the same common set of option
flags (--help, --version, --json, --pretty, --debug). The description is
duplicated across all the pages, which is more difficult to maintain if
the description of an option changes. It may also be confusing to sort
out what options are not "common" and should not be copied when creating
new manual pages.

Let's move the description for those common options to a separate file,
which is included with a RST directive when generating the man pages.

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/20200909162500.17010-3-quentin@isovalent.com

diff --git a/tools/bpf/bpftool/Documentation/Makefile b/tools/bpf/bpftool/Documentation/Makefile
index a45b51d984689c7f8dd239529da751ac82e7cb4e..5e3815320dab593c7e878a430a1fe553d02b9147 100644 (file)
--- a/tools/bpf/bpftool/Documentation/Makefile
+++ b/tools/bpf/bpftool/Documentation/Makefile
@@ -19,7 +19,7 @@ man8dir = $(mandir)/man8
 # Load targets for building eBPF helpers man page.
 include ../../Makefile.helpers
 
-MAN8_RST = $(filter-out $(HELPERS_RST),$(wildcard *.rst))
+MAN8_RST = $(wildcard bpftool*.rst)
 
 _DOC_MAN8 = $(patsubst %.rst,%.8,$(MAN8_RST))
 DOC_MAN8 = $(addprefix $(OUTPUT),$(_DOC_MAN8))

diff --git a/tools/bpf/bpftool/Documentation/bpftool-btf.rst b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
index 864553e62af427c0806905bc7091fec0765639c5..52a7b2f6c9cb47e85205486a00d1bc42b454b4b6 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-btf.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
@@ -71,22 +71,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
-
-       -d, --debug
-                 Print all logs available from libbpf, including debug-level
-                 information.
+       .. include:: common_options.rst
 
 EXAMPLES
 ========

diff --git a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
index a226aee3574fd34a552825758fcac49232954b64..3dba89db000ea35ca8c5d2bc60443a38d175de9e 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
@@ -116,26 +116,11 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
+       .. include:: common_options.rst
 
        -f, --bpffs
                  Show file names of pinned programs.
 
-       -d, --debug
-                 Print all logs available from libbpf, including debug-level
-                 information.
-
 EXAMPLES
 ========
 |

diff --git a/tools/bpf/bpftool/Documentation/bpftool-feature.rst b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
index 8609f06e71de036d94bc2c6242f7dd1f0dc29c39..f1aae5690e3c88c7d410c2e4d322c92db3000cc9 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-feature.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
@@ -71,22 +71,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
-
-       -d, --debug
-                 Print all logs available from libbpf, including debug-level
-                 information.
+       .. include:: common_options.rst
 
 SEE ALSO
 ========

diff --git a/tools/bpf/bpftool/Documentation/bpftool-gen.rst b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
index d52b03a352d72abd7d8d94ac82ea69e32e33796f..29d4cf4c3422c33eb619183657724659fdc2322c 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-gen.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
@@ -126,22 +126,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON,
-                 this option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
-
-       -d, --debug
-                 Print all logs available from libbpf, including debug-level
-                 information.
+       .. include:: common_options.rst
 
 EXAMPLES
 ========

diff --git a/tools/bpf/bpftool/Documentation/bpftool-iter.rst b/tools/bpf/bpftool/Documentation/bpftool-iter.rst
index 070ffacb42b523a294bf7950ae3a70ac2da80f74..b688cf11805c3d335da61c3ca8445dd2ef8cb22b 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-iter.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-iter.rst
@@ -51,16 +51,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -d, --debug
-                 Print all logs available, even debug-level information. This
-                 includes logs from libbpf as well as from the verifier, when
-                 attempting to load programs.
+       .. include:: common_options.rst
 
 EXAMPLES
 ========

diff --git a/tools/bpf/bpftool/Documentation/bpftool-link.rst b/tools/bpf/bpftool/Documentation/bpftool-link.rst
index dc7693b5e606c6563ec38f8d9fc0b829bbef3c60..ce122be58baeef753c82a3b52052f6dfe75067b0 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-link.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-link.rst
@@ -62,18 +62,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
+       .. include:: common_options.rst
 
        -f, --bpffs
                  When showing BPF links, show file names of pinned
@@ -83,10 +72,6 @@ OPTIONS
                  Do not automatically attempt to mount any virtual file system
                  (such as tracefs or BPF virtual file system) when necessary.
 
-       -d, --debug
-                 Print all logs available, even debug-level information. This
-                 includes logs from libbpf.
-
 EXAMPLES
 ========
 **# bpftool link show**

diff --git a/tools/bpf/bpftool/Documentation/bpftool-map.rst b/tools/bpf/bpftool/Documentation/bpftool-map.rst
index 8f187c6416cd56a35d4dafd431a001f1c75eec39..4b42629ade3e1ddcab5c05ddce5a83d730975417 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-map.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-map.rst
@@ -155,18 +155,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
+       .. include:: common_options.rst
 
        -f, --bpffs
                  Show file names of pinned maps.
@@ -175,10 +164,6 @@ OPTIONS
                  Do not automatically attempt to mount any virtual file system
                  (such as tracefs or BPF virtual file system) when necessary.
 
-       -d, --debug
-                 Print all logs available from libbpf, including debug-level
-                 information.
-
 EXAMPLES
 ========
 **# bpftool map show**

diff --git a/tools/bpf/bpftool/Documentation/bpftool-net.rst b/tools/bpf/bpftool/Documentation/bpftool-net.rst
index aa7450736179fe87523358c51b8557be083b6cf2..56439c32934d7f04d8752cc85de9f39213cb83fc 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-net.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-net.rst
@@ -75,22 +75,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
-
-       -d, --debug
-                 Print all logs available from libbpf, including debug-level
-                 information.
+       .. include:: common_options.rst
 
 EXAMPLES
 ========

diff --git a/tools/bpf/bpftool/Documentation/bpftool-perf.rst b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
index 9c592b7c6775fe5fdbb57f734ab19d30d5994971..36d257a36e9b30861dfe38ebb76a6f20caf3558e 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-perf.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
@@ -40,22 +40,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
-
-       -d, --debug
-                 Print all logs available from libbpf, including debug-level
-                 information.
+       .. include:: common_options.rst
 
 EXAMPLES
 ========

diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.rst b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
index 82e356b664e8d80cb707b6f7ce9db96e045d855a..9b2b18e2a3acc676a2ef783b0481a7b5583042ce 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-prog.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
@@ -210,18 +210,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
+       .. include:: common_options.rst
 
        -f, --bpffs
                  When showing BPF programs, show file names of pinned
@@ -234,11 +223,6 @@ OPTIONS
                  Do not automatically attempt to mount any virtual file system
                  (such as tracefs or BPF virtual file system) when necessary.
 
-       -d, --debug
-                 Print all logs available, even debug-level information. This
-                 includes logs from libbpf as well as from the verifier, when
-                 attempting to load programs.
-
 EXAMPLES
 ========
 **# bpftool prog show**

diff --git a/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst b/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
index d93cd1cb8b0fc7f61b3588f1f0c588effd9f6249..315f1f21f2ba2e06e8fc7f55dcdba4f81a518c1e 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
@@ -60,23 +60,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short generic help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
-
-       -d, --debug
-                 Print all logs available, even debug-level information. This
-                 includes logs from libbpf as well as from the verifier, when
-                 attempting to load programs.
+       .. include:: common_options.rst
 
 EXAMPLES
 ========

diff --git a/tools/bpf/bpftool/Documentation/bpftool.rst b/tools/bpf/bpftool/Documentation/bpftool.rst
index a3629a3f117506a8ec05ab43ab047cf23f333f3b..b87f8c2df49dd06e4470689ddba77e7b417df09d 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool.rst
@@ -46,24 +46,7 @@ DESCRIPTION
 
 OPTIONS
 =======
-       -h, --help
-                 Print short help message (similar to **bpftool help**).
-
-       -V, --version
-                 Print version number (similar to **bpftool version**), and
-                 optional features that were included when bpftool was
-                 compiled. Optional features include linking against libbfd to
-                 provide the disassembler for JIT-ted programs (**bpftool prog
-                 dump jited**) and usage of BPF skeletons (some features like
-                 **bpftool prog profile** or showing pids associated to BPF
-                 objects may rely on it).
-
-       -j, --json
-                 Generate JSON output. For commands that cannot produce JSON, this
-                 option has no effect.
-
-       -p, --pretty
-                 Generate human-readable JSON output. Implies **-j**.
+       .. include:: common_options.rst
 
        -m, --mapcompat
                  Allow loading maps with unknown map definitions.
@@ -72,11 +55,6 @@ OPTIONS
                  Do not automatically attempt to mount any virtual file system
                  (such as tracefs or BPF virtual file system) when necessary.
 
-       -d, --debug
-                 Print all logs available, even debug-level information. This
-                 includes logs from libbpf as well as from the verifier, when
-                 attempting to load programs.
-
 SEE ALSO
 ========
        **bpf**\ (2),

diff --git a/tools/bpf/bpftool/Documentation/common_options.rst b/tools/bpf/bpftool/Documentation/common_options.rst
new file mode 100644 (file)
index 0000000..05d06c7
--- /dev/null
+++ b/tools/bpf/bpftool/Documentation/common_options.rst
@@ -0,0 +1,22 @@
+-h, --help
+         Print short help message (similar to **bpftool help**).
+
+-V, --version
+         Print version number (similar to **bpftool version**), and optional
+         features that were included when bpftool was compiled. Optional
+         features include linking against libbfd to provide the disassembler
+         for JIT-ted programs (**bpftool prog dump jited**) and usage of BPF
+         skeletons (some features like **bpftool prog profile** or showing
+         pids associated to BPF objects may rely on it).
+
+-j, --json
+         Generate JSON output. For commands that cannot produce JSON, this
+         option has no effect.
+
+-p, --pretty
+         Generate human-readable JSON output. Implies **-j**.
+
+-d, --debug
+         Print all logs available, even debug-level information. This includes
+         logs from libbpf as well as from the verifier, when attempting to
+         load programs.