[PATCH] binutils: Fix broken numbering in strip/objcopy --only-keep-debug doc

[Jan Beulich]

On 21.01.2026 09:35, Thiago C Silva wrote:
> The documentation for --only-keep-debug displayed the procedure steps as
> "1. 1. 1. 1." in the man pages, despite using the @enumerate command.
> 
> This patch moves the item text to the line following the @item tag and
> adds whitespace between items. This forces the man page generator to
> correctly distinguish the items and increment the list counter.

Not being a .texi specialist at all, looks both plausible and in line with
what is being done elsewhere. Just two small nits:

> --- a/binutils/doc/binutils.texi
> +++ b/binutils/doc/binutils.texi
> @@ -2086,14 +2086,20 @@ needed if debugging abilities are required.  The suggested procedure
>  to create these files is as follows:
>  
>  @enumerate
> -@item Link the executable as normal.  Assuming that it is called
> -@code{foo} then...
> -@item Run @code{objcopy --only-keep-debug foo foo.dbg} to
> -create a file containing the debugging info.
> -@item Run @code{objcopy --strip-debug foo} to create a
> -stripped executable.
> -@item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
> -to add a link to the debugging info into the stripped executable.
> +@item
> +Link the executable as normal.  Assuming that it is called @code{foo}
> +then...
> +
> +@item
> +Run @code{objcopy --only-keep-debug foo foo.dbg} to create a file
> +containing the debugging info.
> +
> +@item
> +Run @code{objcopy --strip-debug foo} to create a stripped executable.
> +
> +@item
> +Run @code{objcopy --add-gnu-debuglink=foo.dbg foo} to add a link to the
> +debugging info into the stripped executable.
>  @end enumerate
>  
>  Note---the choice of @code{.dbg} as an extension for the debug info
> @@ -2101,10 +2107,17 @@ file is arbitrary.  Also the @code{--only-keep-debug} step is
>  optional.  You could instead do this:
>  
>  @enumerate
> -@item Link the executable as normal.
> -@item Copy @code{foo} to  @code{foo.full}
> -@item Run @code{objcopy --strip-debug foo}
> -@item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
> +@item
> +Link the executable as normal.
> +
> +@item
> +Copy @code{foo} to  @code{foo.full}.

The excess blank would be nice to be removed here while moving the sentence
around.

> @@ -3809,14 +3822,20 @@ needed if debugging abilities are required.  The suggested procedure
>  to create these files is as follows:
>  
>  @enumerate
> -@item Link the executable as normal.  Assuming that it is called
> -@code{foo} then...
> -@item Run @code{objcopy --only-keep-debug foo foo.dbg} to
> -create a file containing the debugging info.
> -@item Run @code{objcopy --strip-debug foo} to create a
> -stripped executable.
> -@item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
> -to add a link to the debugging info into the stripped executable.
> +@item
> +Link the executable as normal.  Assuming that it is called @code{foo}
> +then...
> +
> +@item
> +Run @code{objcopy --only-keep-debug foo foo.dbg} to create a file
> +containing the debugging info.
> +
> +@item
> +Run @code{objcopy --strip-debug foo} to create a stripped executable.

Imo this being strip's description, it might be nice use strip here, in
line with ...

> +@item
> +Run @code{objcopy --add-gnu-debuglink=foo.dbg foo} to add a link to the
> +debugging info into the stripped executable.
>  @end enumerate
>  
>  Note---the choice of @code{.dbg} as an extension for the debug info
> @@ -3824,10 +3843,17 @@ file is arbitrary.  Also the @code{--only-keep-debug} step is
>  optional.  You could instead do this:
>  
>  @enumerate
> -@item Link the executable as normal.
> -@item Copy @code{foo} to @code{foo.full}
> -@item Run @code{strip --strip-debug foo}
> -@item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
> +@item
> +Link the executable as normal.
> +
> +@item
> +Copy @code{foo} to @code{foo.full}.
> +
> +@item
> +Run @code{strip --strip-debug foo}.

... this. Without that minor delta to the objcopy doc it would be hard to
see why there couldn't simply be a cross reference.

Assuming you don't have write access, I could make those small adjustments
while committing this for you. Provided you agree.

Jan