Ping: [Patch] Clarify addr2line output in the manual

[Tristan Gingold <gingold at adacore dot com>]

Hi,

any review for a doco patch ?

Thanks,
Tristan.

On 28 May 2014, at 09:54, Tristan Gingold <gingold@adacore.com> wrote:

> Hi,
> 
> I think the current description of addr2line in the manual is a little bit confusing.
> But as I am not a native English speaker, please proof read my changes.
> 
> The sentence
> The file name and line number for each input address is printed on separate lines.
> is ambiguous, so I reformulate it.
> 
> The description for -i ("then the `{FUNCTIONNAME} FILENAME:LINENO' information for the inlining function will be displayed afterwards. This continues recursively until there is no more inlining to report.") is
> not clear.
> 
> The combination of -a and -f (or -a and -i) is not clear.
> 
> The description of -p ("If the -p option is used then the output for each input address is displayed on one, possibly quite long, line.") isn't correct in presence of -i.
> 
> I hope my changes clarify the above points, feel free to comment.
> 
> Checked by make info in binutils/
> 
> Tristan.
> 
> binutils/
> 2014-05-28  Tristan Gingold  <gingold@adacore.com>
> 
> 	* doc/binutils.texi: Clarify addr2line output.
> 
> diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi
> index 3375d36..c22526d 100644
> --- a/binutils/doc/binutils.texi
> +++ b/binutils/doc/binutils.texi
> @@ -3206,26 +3206,33 @@ standard input, and prints the file name and line number for each
> address on standard output.  In this mode, @command{addr2line} may be used
> in a pipe to convert dynamically chosen addresses.
> 
> -The format of the output is @samp{FILENAME:LINENO}.  The file name and
> -line number for each input address is printed on separate lines.
> +The format of the output is @samp{FILENAME:LINENO}.  By default,
> +each input address generates one line.
> 
> -If the @option{-f} option is used, then each @samp{FILENAME:LINENO}
> -line is preceded by @samp{FUNCTIONNAME} which is the name of the
> -function containing the address.
> +Two options can generate additional lines before each
> +@samp{FILENAME:LINENO} line (in that order).
> +
> +If the @option{-a} option is used then a line with the input address
> +is displayed.
> +
> +If the @option{-f} option is used, then a line with the
> +@samp{FUNCTIONNAME} is displayed.  This is the name of the function
> +containing the address.
> +
> +One option can generate additional lines after the
> +@samp{FILENAME:LINENO} line.
> 
> If the @option{-i} option is used and the code at the given address is
> -present there because of inlining by the compiler then the
> -@samp{@{FUNCTIONNAME@} FILENAME:LINENO} information for the inlining
> -function will be displayed afterwards.  This continues recursively
> -until there is no more inlining to report.
> -
> -If the @option{-a} option is used then the output is prefixed by the
> -input address.
> -
> -If the @option{-p} option is used then the output for each input
> -address is displayed on one, possibly quite long, line.  If
> -@option{-p} is not used then the output is broken up into multiple
> -lines, based on the paragraphs above.
> +present there because of inlining by the compiler then additional
> +lines are displayed afterwards.  One or two (if the @option{-f} option
> +is used) are displayed for each inlined function.
> +
> +Finally, if the @option{-p} option is used then the input address, the
> +function name, the filename and the line number are displayed on
> +one, possibly quite long, line.  If the @option{-i} is also used,
> +an inlined function generate one additional line, prefixed with
> +@samp{(inlined by)}.  If @option{-p} is not used then the
> +output is broken up into multiple lines, based on the paragraphs above.
> 
> If the file name or function name can not be determined,
> @command{addr2line} will print two question marks in their place.  If the
> 
>