Re: [PATCH 1/3] perf tools: Move callchain help messages to callchain.h

[Ingo Molnar <mingo@kernel.org>]

* Namhyung Kim <namhyung@kernel.org> wrote:

> > Also, I had to go into the code to decode the real meaning of all the other 
> > parameters. I'd have expected them to be more obvious from reading the help 
> > text.
> 
> Did you check the man page also?  I think we have (short) explanation for each 
> parameter and users should read it first to understand the meaning.  But I agree 
> that the help text should also be improved to provide quick reference.

ah, no.

Is there a way to call up the manpage output for any given option, or so?

Such as:

   perf report -g help

Outputs the short-style help text you fixed:

 Usage: perf report [<options>]

    -g, --call-graph <print_type,threshold[,print_limit],order,sort_key[,branch]>
                          Display call graph (stack chain/backtrace):

                                print_type:     call graph printing style (graph|flat|fractal|none)
                                threshold:      minimum call graph inclusion threshold (<percent>)
                                print_limit:    maximum number of call graph entry (<number>)
                                order:          call graph order (caller|callee)
                                sort_key:       call graph sort key (function|address)
                                branch:         include last branch info to call graph (branch)

                                Default: graph,0.5,caller,function

and we could append one more line:

 # Suggestion: By typing 'perf report -g man' you can see the detailed manpage of option

OTOH the manpage is not easily parsed into per option sections, right? So we could 
bring up the whole manpage.

Btw., another usability detail I noticed yesterday is that when I typed 'perf 
report -h' I got so much output that I couldn't find the specific option I was 
looking for, because there's no apparent ordering of the output:

triton:~/tip> perf report -h 2>&1 | grep -e ' -[a-Z],'
    -i, --input <file>    input file name
    -v, --verbose         be more verbose (show symbol address, etc)
    -D, --dump-raw-trace  dump raw trace in ASCII
    -k, --vmlinux <file>  vmlinux pathname
    -f, --force           don't complain, do it
    -m, --modules         load module symbols - WARNING: use only with -k and LIVE kernel
    -n, --show-nr-samples
    -T, --threads         Show per-thread event counters
    -s, --sort <key[,key2...]>
    -F, --fields <key[,keys...]>
    -p, --parent <regex>  regex filter to identify parent, see: '--sort parent'
    -x, --exclude-other   Only display entries with parent-match
    -g, --call-graph <print_type,threshold[,print_limit],order,sort_key[,branch]>
    -G, --inverted        alias for inverted call graph
    -d, --dsos <dso[,dso...]>
    -c, --comms <comm[,comm...]>
    -S, --symbols <symbol[,symbol...]>
    -w, --column-widths <width[,width...]>
    -t, --field-separator <separator>
    -U, --hide-unresolved
    -C, --cpu <cpu>       list of cpus to profile
    -I, --show-info       Display extended information about perf.data file
    -M, --disassembler-style <disassembler style>
    -b, --branch-stack    use branch records for per branch histogram filling

Such (alphabetic) ordering would be easier to navigate:

    -b, --branch-stack    use branch records for per branch histogram filling
    -c, --comms <comm[,comm...]>
    -C, --cpu <cpu>       list of cpus to profile
    -d, --dsos <dso[,dso...]>
    -D, --dump-raw-trace  dump raw trace in ASCII
    -F, --fields <key[,keys...]>
    -f, --force           don't complain, do it
    -g, --call-graph <print_type,threshold[,print_limit],order,sort_key[,branch]>
    -G, --inverted        alias for inverted call graph
    -i, --input <file>    input file name
    -I, --show-info       Display extended information about perf.data file
    -k, --vmlinux <file>  vmlinux pathname
    -M, --disassembler-style <disassembler style>
    -m, --modules         load module symbols - WARNING: use only with -k and LIVE kernel
    -n, --show-nr-samples
    -p, --parent <regex>  regex filter to identify parent, see: '--sort parent'
    -s, --sort <key[,key2...]>
    -S, --symbols <symbol[,symbol...]>
    -t, --field-separator <separator>
    -T, --threads         Show per-thread event counters
    -U, --hide-unresolved
    -v, --verbose         be more verbose (show symbol address, etc)
    -w, --column-widths <width[,width...]>
    -x, --exclude-other   Only display entries with parent-match

Since perf is growing rapidly:

triton:~/tip> L_PREV=0; for v in v2.6.32 v2.6.33 v2.6.34 v2.6.35 v2.6.36 v2.6.37 \
v2.6.38 v2.6.39 v3.0 v3.1 v3.2 v3.3 v3.4 v3.5 v3.6 v3.7 v3.8 v3.9 v3.10 v3.11 \
v3.12 v3.13 v3.14 v3.15 v3.16 v3.17 v3.18 v3.19 v4.0 v4.1 v4.2 master; do printf \ 
"%-10s: " $v; rm -rf tools/perf/; git checkout -f $v >/dev/null 2>&1; L=$(find \
tools/perf/ -type f | xargs cat | wc -l); GROWTH=$((L-L_PREV)); printf \
"%6d  (+%6d) LOC\n" $L $GROWTH; L_PREV=$L; done

v2.6.32   :  27743  (+ 27743) LOC
v2.6.33   :  36676  (+  8933) LOC
v2.6.34   :  41350  (+  4674) LOC
v2.6.35   :  46579  (+  5229) LOC
v2.6.36   :  49377  (+  2798) LOC
v2.6.37   :  51030  (+  1653) LOC
v2.6.38   :  53017  (+  1987) LOC
v2.6.39   :  56141  (+  3124) LOC
v3.0      :  57423  (+  1282) LOC
v3.1      :  58824  (+  1401) LOC
v3.2      :  61403  (+  2579) LOC
v3.3      :  62790  (+  1387) LOC
v3.4      :  66509  (+  3719) LOC
v3.5      :  65967  (+  -542) LOC
v3.6      :  68273  (+  2306) LOC
v3.7      :  74301  (+  6028) LOC
v3.8      :  78281  (+  3980) LOC
v3.9      :  82289  (+  4008) LOC
v3.10     :  84195  (+  1906) LOC
v3.11     :  84536  (+   341) LOC
v3.12     :  90159  (+  5623) LOC
v3.13     :  95169  (+  5010) LOC
v3.14     :  97233  (+  2064) LOC
v3.15     :  98857  (+  1624) LOC
v3.16     : 103760  (+  4903) LOC
v3.17     : 106358  (+  2598) LOC
v3.18     : 109347  (+  2989) LOC
v3.19     : 112867  (+  3520) LOC
v4.0      : 113194  (+   327) LOC
v4.1      : 115992  (+  2798) LOC
v4.2      : 123404  (+  7412) LOC
master    : 143429  (+ 20025) LOC

which is good! ;-) - but managing all the various pieces of documentation will 
become a larger and larger challenge I suspect as time goes on, both for users
and for developers.

Thanks,

	Ingo