[PATCH] gas/doc: clarify local label vs local symbol terminology

[Jan Beulich]

On 08.02.2026 22:40, maskray@sourceware.org wrote:
> From: Fangrui Song <maskray@sourceware.org>
> 
> In ELF, "local symbols" refer to symbols of STB_LOCAL binding. The
> doc is inconsistent: while it uses "local symbol" in places like .local,
> "local symbols" are also used for .L-prefixed symbols (as determined by
> bfd_is_local_label).
> 
> Rename "Local Symbol Names" to "Local Label Names" for .L-prefixed
> symbols,

While I can certainly see where you're coming from, I fear "local label"
also has its downside: These "identifiers" can be used for more than just
"labels", and hence naming them "symbols" (of whatever sort) is imo more
appropriate.

As .local is ELF-only anyway, how about adjusting the wording there, e.g.
to prefer STB_LOCAL where "local" is presently used?

> and rename "Local Labels" to "Numeric Local Labels" for
> N:/Nb/Nf numeric labels.

Not sure "numeric" is helpful here, as this increases the disconnect from
naming within the assembler (where it's "FB labels").

>  This makes the documentation consistent with
> BFD terminology and avoids confusion with ELF STB_LOCAL "local symbols".

How does BFD terminology come into play here? Iirc "local symbols" is a
gas-internal concept; struct local_symbol doesn't reference any BFD
symbol.

> @@ -4005,44 +4005,46 @@ Each symbol has exactly one name.  Each name in an assembly language program
>  refers to exactly one symbol.  You may use that symbol name any number of times
>  in a program.
>  
> -@subheading Local Symbol Names
> +@subheading Local Label Names
>  
> -@cindex local symbol names
> -@cindex symbol names, local
> -A local symbol is any symbol beginning with certain local label prefixes.
> +@cindex local label names
> +@cindex label names, local
> +A local label is any symbol beginning with certain local label prefixes.
>  By default, the local label prefix is @samp{.L} for ELF systems or
>  @samp{L} for traditional a.out systems, but each target may have its own
>  set of local label prefixes.
>  @ifset HPPA
> -On the HPPA local symbols begin with @samp{L$}.
> +On the HPPA local labels begin with @samp{L$}.
>  @end ifset
>  
> -Local symbols are defined and used within the assembler, but they are
> +Local labels are defined and used within the assembler, but they are
>  normally not saved in object files.  Thus, they are not visible when debugging.
> -You may use the @samp{-L} option (@pxref{L, ,Include Local Symbols})
> -to retain the local symbols in the object files.
> +You may use the @samp{-L} option (@pxref{L, ,Include Local Labels})
> +to retain the local labels in the object files.
>  
> -@subheading Local Labels
> +@subheading Numeric Local Labels
>  
> -@cindex local labels
> +@cindex numeric local labels
>  @cindex temporary symbol names
>  @cindex symbol names, temporary
> -Local labels are different from local symbols.  Local labels help compilers and
> +Numeric local labels help compilers and
>  programmers use names temporarily.  They create symbols which are guaranteed to

If we wanted to go with this terminology change, the first sentence imo absolutely
wants retaining (in whichever adjusted shape).

Jan