[PATCH bpf-next] bpftool: work-around rst2man conversion bug

[PATCH bpf-next] bpftool: work-around rst2man conversion bug

[Andrii Nakryiko]

Work-around what appears to be a bug in rst2man convertion tool, used to
create man pages out of reStructureText-formatted documents. If text line
starts with dot, rst2man will put it in resulting man file verbatim. This
seems to cause man tool to interpret it as a directive/command (e.g., `.bs`), and
subsequently not render entire line because it's unrecognized one.

Enclose '.xxx' words in extra formatting to work around.

Fixes: cb21ac588546 ("bpftool: Add gen subcommand manpage")
Reported-by: Alexei Starovoitov <ast@kernel.org>
Signed-off-by: Andrii Nakryiko <andriin@fb.com>
---
 tools/bpf/bpftool/Documentation/bpftool-gen.rst | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/tools/bpf/bpftool/Documentation/bpftool-gen.rst b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
index b6a114bf908d..86a87da97d0b 100644
--- a/tools/bpf/bpftool/Documentation/bpftool-gen.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
@@ -112,13 +112,14 @@ DESCRIPTION
 
 		  If BPF object has global variables, corresponding structs
 		  with memory layout corresponding to global data data section
-		  layout will be created. Currently supported ones are: .data,
-		  .bss, .rodata, and .extern structs/data sections. These
-		  data sections/structs can be used to set up initial values of
-		  variables, if set before **example__load**. Afterwards, if
-		  target kernel supports memory-mapped BPF arrays, same
-		  structs can be used to fetch and update (non-read-only)
-		  data from userspace, with same simplicity as for BPF side.
+		  layout will be created. Currently supported ones are: *.data*,
+		  *.bss*, *.rodata*, and *.kconfig* structs/data sections.
+		  These data sections/structs can be used to set up initial
+		  values of variables, if set before **example__load**.
+		  Afterwards, if target kernel supports memory-mapped BPF
+		  arrays, same structs can be used to fetch and update
+		  (non-read-only) data from userspace, with same simplicity
+		  as for BPF side.
 
 	**bpftool gen help**
 		  Print short help message.
-- 
2.17.1

Re: [PATCH bpf-next] bpftool: work-around rst2man conversion bug

[Yonghong Song]

On 12/18/19 2:17 PM, Andrii Nakryiko wrote:
> Work-around what appears to be a bug in rst2man convertion tool, used to
> create man pages out of reStructureText-formatted documents. If text line
> starts with dot, rst2man will put it in resulting man file verbatim. This
> seems to cause man tool to interpret it as a directive/command (e.g., `.bs`), and
> subsequently not render entire line because it's unrecognized one.
> 
> Enclose '.xxx' words in extra formatting to work around.
> 
> Fixes: cb21ac588546 ("bpftool: Add gen subcommand manpage")
> Reported-by: Alexei Starovoitov <ast@kernel.org>
> Signed-off-by: Andrii Nakryiko <andriin@fb.com>
> ---
>   tools/bpf/bpftool/Documentation/bpftool-gen.rst | 15 ++++++++-------
>   1 file changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-gen.rst b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
> index b6a114bf908d..86a87da97d0b 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-gen.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
> @@ -112,13 +112,14 @@ DESCRIPTION
>   
>   		  If BPF object has global variables, corresponding structs
>   		  with memory layout corresponding to global data data section
> -		  layout will be created. Currently supported ones are: .data,
> -		  .bss, .rodata, and .extern structs/data sections. These
> -		  data sections/structs can be used to set up initial values of
> -		  variables, if set before **example__load**. Afterwards, if
> -		  target kernel supports memory-mapped BPF arrays, same
> -		  structs can be used to fetch and update (non-read-only)
> -		  data from userspace, with same simplicity as for BPF side.
> +		  layout will be created. Currently supported ones are: *.data*,
> +		  *.bss*, *.rodata*, and *.kconfig* structs/data sections.
> +		  These data sections/structs can be used to set up initial
> +		  values of variables, if set before **example__load**.
> +		  Afterwards, if target kernel supports memory-mapped BPF
> +		  arrays, same structs can be used to fetch and update
> +		  (non-read-only) data from userspace, with same simplicity
> +		  as for BPF side.

Still does not look right.

After build, I did `man ./bpftool-gen.8`, and I got the following,

                  sponding to global data data section layout will be 
created. Currently supported ones
                  are: .data, data sections/structs can be used to set 
up initial values of  variables,

.bss, .rodata .kconfig etc. are missing. I am using:

-bash-4.4$ man --version
man 2.6.3

>   
>   	**bpftool gen help**
>   		  Print short help message.
> 

Re: [PATCH bpf-next] bpftool: work-around rst2man conversion bug

[Andrii Nakryiko]

On Wed, Dec 18, 2019 at 3:35 PM Yonghong Song <yhs@fb.com> wrote:
>
>
>
> On 12/18/19 2:17 PM, Andrii Nakryiko wrote:
> > Work-around what appears to be a bug in rst2man convertion tool, used to
> > create man pages out of reStructureText-formatted documents. If text line
> > starts with dot, rst2man will put it in resulting man file verbatim. This
> > seems to cause man tool to interpret it as a directive/command (e.g., `.bs`), and
> > subsequently not render entire line because it's unrecognized one.
> >
> > Enclose '.xxx' words in extra formatting to work around.
> >
> > Fixes: cb21ac588546 ("bpftool: Add gen subcommand manpage")
> > Reported-by: Alexei Starovoitov <ast@kernel.org>
> > Signed-off-by: Andrii Nakryiko <andriin@fb.com>
> > ---
> >   tools/bpf/bpftool/Documentation/bpftool-gen.rst | 15 ++++++++-------
> >   1 file changed, 8 insertions(+), 7 deletions(-)
> >
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-gen.rst b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
> > index b6a114bf908d..86a87da97d0b 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool-gen.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
> > @@ -112,13 +112,14 @@ DESCRIPTION
> >
> >                 If BPF object has global variables, corresponding structs
> >                 with memory layout corresponding to global data data section
> > -               layout will be created. Currently supported ones are: .data,
> > -               .bss, .rodata, and .extern structs/data sections. These
> > -               data sections/structs can be used to set up initial values of
> > -               variables, if set before **example__load**. Afterwards, if
> > -               target kernel supports memory-mapped BPF arrays, same
> > -               structs can be used to fetch and update (non-read-only)
> > -               data from userspace, with same simplicity as for BPF side.
> > +               layout will be created. Currently supported ones are: *.data*,
> > +               *.bss*, *.rodata*, and *.kconfig* structs/data sections.
> > +               These data sections/structs can be used to set up initial
> > +               values of variables, if set before **example__load**.
> > +               Afterwards, if target kernel supports memory-mapped BPF
> > +               arrays, same structs can be used to fetch and update
> > +               (non-read-only) data from userspace, with same simplicity
> > +               as for BPF side.
>
> Still does not look right.
>
> After build, I did `man ./bpftool-gen.8`, and I got the following,
>
>                   sponding to global data data section layout will be
> created. Currently supported ones
>                   are: .data, data sections/structs can be used to set
> up initial values of  variables,
>
> .bss, .rodata .kconfig etc. are missing. I am using:
>

looks like stale man page, can you please try re-building? Double
checked on my side, it looks good here.

> -bash-4.4$ man --version
> man 2.6.3
>
> >
> >       **bpftool gen help**
> >                 Print short help message.
> >

Re: [PATCH bpf-next] bpftool: work-around rst2man conversion bug

[Yonghong Song]

On 12/18/19 3:35 PM, Yonghong Song wrote:
> 
> 
> On 12/18/19 2:17 PM, Andrii Nakryiko wrote:
>> Work-around what appears to be a bug in rst2man convertion tool, used to
>> create man pages out of reStructureText-formatted documents. If text line
>> starts with dot, rst2man will put it in resulting man file verbatim. This
>> seems to cause man tool to interpret it as a directive/command (e.g., `.bs`), and
>> subsequently not render entire line because it's unrecognized one.
>>
>> Enclose '.xxx' words in extra formatting to work around.
>>
>> Fixes: cb21ac588546 ("bpftool: Add gen subcommand manpage")
>> Reported-by: Alexei Starovoitov <ast@kernel.org>
>> Signed-off-by: Andrii Nakryiko <andriin@fb.com>

Acked-by: Yonghong Song <yhs@fb.com

[...]
>> +		  *.bss*, *.rodata*, and *.kconfig* structs/data sections.
>> +		  These data sections/structs can be used to set up initial
>> +		  values of variables, if set before **example__load**.
>> +		  Afterwards, if target kernel supports memory-mapped BPF
>> +		  arrays, same structs can be used to fetch and update
>> +		  (non-read-only) data from userspace, with same simplicity
>> +		  as for BPF side.
> 
> Still does not look right.
> 
> After build, I did `man ./bpftool-gen.8`, and I got the following,
> 
>                    sponding to global data data section layout will be
> created. Currently supported ones
>                    are: .data, data sections/structs can be used to set
> up initial values of  variables,
> 
> .bss, .rodata .kconfig etc. are missing. I am using:
> 
> -bash-4.4$ man --version
> man 2.6.3

Sorry. Actually this patch works. I applied the previous patch
"bpftool: simplify format string to not use positional args" and got
the above result.

Re: [PATCH bpf-next] bpftool: work-around rst2man conversion bug

[Alexei Starovoitov]

On Wed, Dec 18, 2019 at 4:42 PM Yonghong Song <yhs@fb.com> wrote:
>
>
>
> On 12/18/19 3:35 PM, Yonghong Song wrote:
> >
> >
> > On 12/18/19 2:17 PM, Andrii Nakryiko wrote:
> >> Work-around what appears to be a bug in rst2man convertion tool, used to
> >> create man pages out of reStructureText-formatted documents. If text line
> >> starts with dot, rst2man will put it in resulting man file verbatim. This
> >> seems to cause man tool to interpret it as a directive/command (e.g., `.bs`), and
> >> subsequently not render entire line because it's unrecognized one.
> >>
> >> Enclose '.xxx' words in extra formatting to work around.
> >>
> >> Fixes: cb21ac588546 ("bpftool: Add gen subcommand manpage")
> >> Reported-by: Alexei Starovoitov <ast@kernel.org>
> >> Signed-off-by: Andrii Nakryiko <andriin@fb.com>
>
> Acked-by: Yonghong Song <yhs@fb.com

Applied. Thanks