On 9/14/20 9:46 AM, Yonghong Song wrote:
On 9/14/20 1:16 AM, Quentin Monnet wrote:
On 14/09/2020 07:12, Yonghong Song wrote:
When building bpf selftests like
make -C tools/testing/selftests/bpf -j20
I hit the following errors:
...
GEN
/net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-gen.8
<stdin>:75: (WARNING/2) Block quote ends without a blank line;
unexpected unindent.
<stdin>:71: (WARNING/2) Literal block ends without a blank line;
unexpected unindent.
<stdin>:85: (WARNING/2) Literal block ends without a blank line;
unexpected unindent.
<stdin>:57: (WARNING/2) Block quote ends without a blank line;
unexpected unindent.
<stdin>:66: (WARNING/2) Literal block ends without a blank line;
unexpected unindent.
<stdin>:109: (WARNING/2) Literal block ends without a blank line;
unexpected unindent.
<stdin>:175: (WARNING/2) Literal block ends without a blank line;
unexpected unindent.
<stdin>:273: (WARNING/2) Literal block ends without a blank line;
unexpected unindent.
make[1]: ***
[/net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-perf.8]
Error 12
make[1]: *** Waiting for unfinished jobs....
make[1]: ***
[/net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-iter.8]
Error 12
make[1]: ***
[/net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-struct_ops.8]
Error 12
...
I am using:
-bash-4.4$ rst2man --version
rst2man (Docutils 0.11 [repository], Python 2.7.5, on linux2)
-bash-4.4$
Looks like that particular version of rst2man prefers to have a blank
line
after literal blocks. This patch added block lines in related .rst files
and compilation can then pass.
Cc: Quentin Monnet <quentin@xxxxxxxxxxxxx>
Fixes: 18841da98100 ("tools: bpftool: Automate generation for "SEE
ALSO" sections in man pages")
Signed-off-by: Yonghong Song <yhs@xxxxxx>
Hi Yonghong, thanks for the fix! I didn't see those warnings on my
setup. For the record my rst2man version is:
rst2man (Docutils 0.16 [release], Python 3.8.2, on linux)
Your patch looks good, but instead of having blank lines at the end of
most files, could you please check if the following works?
Thanks for the tip! I looked at the generated output again. My above fix
can silent the warning, but certainly not correct.
With the following change, I captured the intermediate result of the
.rst file.
ifndef RST2MAN_DEP
$(error "rst2man not found, but required to generate man pages")
endif
- $(QUIET_GEN)( cat $< ; echo -n $(call see_also,$<) ) | rst2man
$(RST2MAN_OPTS) > $@
+ $(QUIET_GEN)( cat $< ; echo -n $(call see_also,$<) ) | tee
/tmp/tt | rst2man $(RST2MAN_OPTS) > $@
With below command,
make clean && make bpftool-cgroup.8
I can get the new .rst file for bpftool-cgroup.
At the end of file /tmp/tt (changed bpftool-cgroup.rst), I see
ID AttachType AttachFlags Name
\n SEE ALSO\n========\n\t**bpf**\ (2),\n\t**bpf-helpers**\
(7),\n\t**bpftool**\ (8),\n\t**bpftool-btf**\
(8),\n\t**bpftool-feature**\ (8),\n\t**bpftool-gen**\
(8),\n\t**bpftool-iter**\ (8),\n\t**bpftool-link**\
(8),\n\t**bpftool-map**\ (8),\n\t**bpftool-net**\
(8),\n\t**bpftool-perf**\ (8),\n\t**bpftool-prog**\
(8),\n\t**bpftool-struct_ops**\ (8)\n
This sounds correct if we rst2man can successfully transforms '\n'
or '\t' to proper encoding in the man page.
Unfortunately, with my version of rst2man, I got
.IP "System Message: WARNING/2 (<stdin>:, line 146)"
Literal block ends without a blank line; unexpected unindent.
.sp
n SEE
ALSOn========nt**bpf**(2),nt**bpf\-helpers**(7),nt**bpftool**(8),nt**bpftool\-btf**(8),nt**bpftool\-feature**(8),nt**bpftool\-gen**(8),nt**bpftool\-iter**(8),nt**bpftool\-link**(8),nt**bpftool\-map**(8),nt**bpftool\-net**(8),nt**bpftool\-perf**(8),nt**bpftool\-prog**(8),nt**bpftool\-struct_ops**(8)n
.\" Generated by docutils manpage writer.
The rst2man simply considered \n as 'n'. The same for '\t' and
this caused the issue.
I did not find a way to fix the problem yet.
The following change works for me.
@@ -44,7 +44,7 @@ $(OUTPUT)%.8: %.rst
ifndef RST2MAN_DEP
$(error "rst2man not found, but required to generate man pages")
endif
- $(QUIET_GEN)( cat $< ; echo -n $(call see_also,$<) ) | rst2man
$(RST2MAN_OPTS) > $@
+ $(QUIET_GEN)( cat $< ; echo -e $(call see_also,$<) ) | rst2man
$(RST2MAN_OPTS) > $@
clean: helpers-clean
$(call QUIET_CLEAN, Documentation)
-bash-4.4$
I will send revision 2 shortly.
------
diff --git a/tools/bpf/bpftool/Documentation/Makefile
b/tools/bpf/bpftool/Documentation/Makefile
index 4c9dd1e45244..01b30ed86eac 100644
--- a/tools/bpf/bpftool/Documentation/Makefile
+++ b/tools/bpf/bpftool/Documentation/Makefile
@@ -32,7 +32,7 @@ RST2MAN_OPTS += --verbose
list_pages = $(sort $(basename $(filter-out $(1),$(MAN8_RST))))
see_also = $(subst " ",, \
- "\n" \
+ "\n\n" \
"SEE ALSO\n" \
"========\n" \
"\t**bpf**\ (2),\n" \
