gas: Document @ and % as interchangeable for type argument in .section

  In the .section Assembler Directive for the ELF format, both the % and
the @ can be used when writing the type argument. Clarify the documentation.

Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
---
 gas/doc/as.texi | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
  

On 16.05.2026 02:38, Will Hawkins wrote:
> In the .section Assembler Directive for the ELF format, both the % and
> the @ can be used when writing the type argument.

That's not exactly true (the two aren't fully interchangeable), and hence ...

> Clarify the documentation.
> 
> Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
> ---
>  gas/doc/as.texi | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
> 
> diff --git a/gas/doc/as.texi b/gas/doc/as.texi
> index 3e1d2d0e254..201d9c26b7d 100644
> --- a/gas/doc/as.texi
> +++ b/gas/doc/as.texi
> @@ -7118,13 +7118,12 @@ a numeric value to be set as the ELF section header's type field.
>  some targets extend this list with their own types
>  @end table
>  
> +Note - the @code{%} character may be used instead of the @code{@@} character
> +when writing the @var{type} argument constant.
> +
>  Many targets only support the first three section types.  The type may be
>  enclosed in double quotes if necessary.
>  
> -Note on targets where the @code{@@} character is the start of a comment (eg
> -ARM) then another character is used instead.  For example the ARM port uses the
> -@code{%} character.

... removing this paragraph loses information. I'd suggest adding something like
"For example the Arm port uses @code{@@} as comment character." to the new paragraph
you add. (MMIX is the other way around, using % as comment char.)

Jan
  

On Sunday, May 17, 2026, Jan Beulich <jbeulich@suse.com> wrote:

> On 16.05.2026 02:38, Will Hawkins wrote:
> > In the .section Assembler Directive for the ELF format, both the % and
> > the @ can be used when writing the type argument.
>
> That's not exactly true (the two aren't fully interchangeable), and hence
> ...



In obj-elf.c, I saw

else if (c == '@' || c == '%')

which I must have misinterpreted?



>
> > Clarify the documentation.
> >
> > Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
> > ---
> >  gas/doc/as.texi | 7 +++----
> >  1 file changed, 3 insertions(+), 4 deletions(-)
> >
> > diff --git a/gas/doc/as.texi b/gas/doc/as.texi
> > index 3e1d2d0e254..201d9c26b7d 100644
> > --- a/gas/doc/as.texi
> > +++ b/gas/doc/as.texi
> > @@ -7118,13 +7118,12 @@ a numeric value to be set as the ELF section
> header's type field.
> >  some targets extend this list with their own types
> >  @end table
> >
> > +Note - the @code{%} character may be used instead of the @code{@@}
> character
> > +when writing the @var{type} argument constant.
> > +
> >  Many targets only support the first three section types.  The type may
> be
> >  enclosed in double quotes if necessary.
> >
> > -Note on targets where the @code{@@} character is the start of a
> comment (eg
> > -ARM) then another character is used instead.  For example the ARM port
> uses the
> > -@code{%} character.
>
> ... removing this paragraph loses information. I'd suggest adding
> something like
> "For example the Arm port uses @code{@@} as comment character." to the
> new paragraph
> you add. (MMIX is the other way around, using % as comment char.)
>
> Jan
>
  

On Sunday, May 17, 2026, Will Hawkins <hawkinsw@obs.cr> wrote:

>
>
> On Sunday, May 17, 2026, Jan Beulich <jbeulich@suse.com> wrote:
>
>> On 16.05.2026 02:38, Will Hawkins wrote:
>> > In the .section Assembler Directive for the ELF format, both the % and
>> > the @ can be used when writing the type argument.
>>
>> That's not exactly true (the two aren't fully interchangeable), and hence
>> ...
>
>
>
> In obj-elf.c, I saw
>
> else if (c == '@' || c == '%')
>
> which I must have misinterpreted?
>


I guess that they are only treated equivalently in code on platforms where
the @ and % do not have implications for the code in earlier processing
before reaching obj_elf_section.

>
>
>
>>
>> > Clarify the documentation.
>> >
>> > Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
>> > ---
>> >  gas/doc/as.texi | 7 +++----
>> >  1 file changed, 3 insertions(+), 4 deletions(-)
>> >
>> > diff --git a/gas/doc/as.texi b/gas/doc/as.texi
>> > index 3e1d2d0e254..201d9c26b7d 100644
>> > --- a/gas/doc/as.texi
>> > +++ b/gas/doc/as.texi
>> > @@ -7118,13 +7118,12 @@ a numeric value to be set as the ELF section
>> header's type field.
>> >  some targets extend this list with their own types
>> >  @end table
>> >
>> > +Note - the @code{%} character may be used instead of the @code{@@}
>> character
>> > +when writing the @var{type} argument constant.
>> > +
>> >  Many targets only support the first three section types.  The type may
>> be
>> >  enclosed in double quotes if necessary.
>> >
>> > -Note on targets where the @code{@@} character is the start of a
>> comment (eg
>> > -ARM) then another character is used instead.  For example the ARM port
>> uses the
>> > -@code{%} character.
>>
>> ... removing this paragraph loses information. I'd suggest adding
>> something like
>> "For example the Arm port uses @code{@@} as comment character." to the
>> new paragraph
>> you add. (MMIX is the other way around, using % as comment char.)
>>
>> Jan
>>
>
  

On 17.05.2026 13:35, Will Hawkins wrote:
> On Sunday, May 17, 2026, Will Hawkins <hawkinsw@obs.cr> wrote:
>> On Sunday, May 17, 2026, Jan Beulich <jbeulich@suse.com> wrote:
>>> On 16.05.2026 02:38, Will Hawkins wrote:
>>>> In the .section Assembler Directive for the ELF format, both the % and
>>>> the @ can be used when writing the type argument.
>>>
>>> That's not exactly true (the two aren't fully interchangeable), and hence
>>> ...
>>
>>
>>
>> In obj-elf.c, I saw
>>
>> else if (c == '@' || c == '%')
>>
>> which I must have misinterpreted?
> 
> I guess that they are only treated equivalently in code on platforms where
> the @ and % do not have implications for the code in earlier processing
> before reaching obj_elf_section.

Correct, comments are being removed much earlier. (If they were fully
equivalent, in that testcase of yours you also wouldn't have had to
switch from @ to %.)

Jan
  

On Mon, May 18, 2026 at 1:57 AM Jan Beulich <jbeulich@suse.com> wrote:
>
> On 17.05.2026 13:35, Will Hawkins wrote:
> > On Sunday, May 17, 2026, Will Hawkins <hawkinsw@obs.cr> wrote:
> >> On Sunday, May 17, 2026, Jan Beulich <jbeulich@suse.com> wrote:
> >>> On 16.05.2026 02:38, Will Hawkins wrote:
> >>>> In the .section Assembler Directive for the ELF format, both the % and
> >>>> the @ can be used when writing the type argument.
> >>>
> >>> That's not exactly true (the two aren't fully interchangeable), and hence
> >>> ...
> >>
> >>
> >>
> >> In obj-elf.c, I saw
> >>
> >> else if (c == '@' || c == '%')
> >>
> >> which I must have misinterpreted?
> >
> > I guess that they are only treated equivalently in code on platforms where
> > the @ and % do not have implications for the code in earlier processing
> > before reaching obj_elf_section.
>
> Correct, comments are being removed much earlier. (If they were fully

I am glad that my reading of the code was not wildly inaccurate: _If_
there were no preprocessor implications for those characters, then
they would be equivalent.

> equivalent, in that testcase of yours you also wouldn't have had to
> switch from @ to %.)

Yes, I agree.

Before I propose an alternate, I figured it might be worth describing
why I wanted to make the change in the first place:

My local system is an x86-64. When I started developing a test case
for objdump and I was running the testsuite, the test in objdump.exp
based on the code in dw5-op.S passed. I could read the documentation
and see that @progbits should be the syntax.

I interpreted the existing note to imply mutually exclusive options
for @ vs %. And yet the test was passing. I used as to compile it --
just to be sure. Once I dug into the code and saw the aforementioned
if statement, I realized _why_ the test author used %: because % is
not a comment indicator on x86-64, using the % means that one version
of the test code works for both x86-64 and ARM platforms.

I proposed the change so that others would not have to search as much
as I did. With that as background, would you be amenable to rewriting

Note on targets where the @ character is the start of a comment (eg
ARM) then another character is used instead. For example the ARM port
uses the % character.

to

Note - certain targets treat @ as the start of a comment (e.g., ARM).
On such platforms, % is used instead. On platforms where neither @ nor
% indicate the start of a comment, @ and % may be used
interchangeably.

I hope that my (albeit modest) efforts at helping "future me" by
updating the docs are helpful. If they are not, please tell me!

Will

>
> Jan
  

On 18.05.2026 15:00, Will Hawkins wrote:
> On Mon, May 18, 2026 at 1:57 AM Jan Beulich <jbeulich@suse.com> wrote:
>> On 17.05.2026 13:35, Will Hawkins wrote:
>>> On Sunday, May 17, 2026, Will Hawkins <hawkinsw@obs.cr> wrote:
>>>> On Sunday, May 17, 2026, Jan Beulich <jbeulich@suse.com> wrote:
>>>>> On 16.05.2026 02:38, Will Hawkins wrote:
>>>>>> In the .section Assembler Directive for the ELF format, both the % and
>>>>>> the @ can be used when writing the type argument.
>>>>>
>>>>> That's not exactly true (the two aren't fully interchangeable), and hence
>>>>> ...
>>>>
>>>>
>>>>
>>>> In obj-elf.c, I saw
>>>>
>>>> else if (c == '@' || c == '%')
>>>>
>>>> which I must have misinterpreted?
>>>
>>> I guess that they are only treated equivalently in code on platforms where
>>> the @ and % do not have implications for the code in earlier processing
>>> before reaching obj_elf_section.
>>
>> Correct, comments are being removed much earlier. (If they were fully
> 
> I am glad that my reading of the code was not wildly inaccurate: _If_
> there were no preprocessor implications for those characters, then
> they would be equivalent.
> 
>> equivalent, in that testcase of yours you also wouldn't have had to
>> switch from @ to %.)
> 
> Yes, I agree.
> 
> Before I propose an alternate, I figured it might be worth describing
> why I wanted to make the change in the first place:
> 
> My local system is an x86-64. When I started developing a test case
> for objdump and I was running the testsuite, the test in objdump.exp
> based on the code in dw5-op.S passed. I could read the documentation
> and see that @progbits should be the syntax.
> 
> I interpreted the existing note to imply mutually exclusive options
> for @ vs %. And yet the test was passing. I used as to compile it --
> just to be sure. Once I dug into the code and saw the aforementioned
> if statement, I realized _why_ the test author used %: because % is
> not a comment indicator on x86-64, using the % means that one version
> of the test code works for both x86-64 and ARM platforms.
> 
> I proposed the change so that others would not have to search as much
> as I did. With that as background, would you be amenable to rewriting
> 
> Note on targets where the @ character is the start of a comment (eg
> ARM) then another character is used instead. For example the ARM port
> uses the % character.
> 
> to
> 
> Note - certain targets treat @ as the start of a comment (e.g., ARM).
> On such platforms, % is used instead. On platforms where neither @ nor
> % indicate the start of a comment, @ and % may be used
> interchangeably.

This reads okay to me.

Jan
  

On Mon, May 18, 2026 at 9:17 AM Jan Beulich <jbeulich@suse.com> wrote:
>
> On 18.05.2026 15:00, Will Hawkins wrote:
> > On Mon, May 18, 2026 at 1:57 AM Jan Beulich <jbeulich@suse.com> wrote:
> >> On 17.05.2026 13:35, Will Hawkins wrote:
> >>> On Sunday, May 17, 2026, Will Hawkins <hawkinsw@obs.cr> wrote:
> >>>> On Sunday, May 17, 2026, Jan Beulich <jbeulich@suse.com> wrote:
> >>>>> On 16.05.2026 02:38, Will Hawkins wrote:
> >>>>>> In the .section Assembler Directive for the ELF format, both the % and
> >>>>>> the @ can be used when writing the type argument.
> >>>>>
> >>>>> That's not exactly true (the two aren't fully interchangeable), and hence
> >>>>> ...
> >>>>
> >>>>
> >>>>
> >>>> In obj-elf.c, I saw
> >>>>
> >>>> else if (c == '@' || c == '%')
> >>>>
> >>>> which I must have misinterpreted?
> >>>
> >>> I guess that they are only treated equivalently in code on platforms where
> >>> the @ and % do not have implications for the code in earlier processing
> >>> before reaching obj_elf_section.
> >>
> >> Correct, comments are being removed much earlier. (If they were fully
> >
> > I am glad that my reading of the code was not wildly inaccurate: _If_
> > there were no preprocessor implications for those characters, then
> > they would be equivalent.
> >
> >> equivalent, in that testcase of yours you also wouldn't have had to
> >> switch from @ to %.)
> >
> > Yes, I agree.
> >
> > Before I propose an alternate, I figured it might be worth describing
> > why I wanted to make the change in the first place:
> >
> > My local system is an x86-64. When I started developing a test case
> > for objdump and I was running the testsuite, the test in objdump.exp
> > based on the code in dw5-op.S passed. I could read the documentation
> > and see that @progbits should be the syntax.
> >
> > I interpreted the existing note to imply mutually exclusive options
> > for @ vs %. And yet the test was passing. I used as to compile it --
> > just to be sure. Once I dug into the code and saw the aforementioned
> > if statement, I realized _why_ the test author used %: because % is
> > not a comment indicator on x86-64, using the % means that one version
> > of the test code works for both x86-64 and ARM platforms.
> >
> > I proposed the change so that others would not have to search as much
> > as I did. With that as background, would you be amenable to rewriting
> >
> > Note on targets where the @ character is the start of a comment (eg
> > ARM) then another character is used instead. For example the ARM port
> > uses the % character.
> >
> > to
> >
> > Note - certain targets treat @ as the start of a comment (e.g., ARM).
> > On such platforms, % is used instead. On platforms where neither @ nor
> > % indicate the start of a comment, @ and % may be used
> > interchangeably.
>
> This reads okay to me.

Thank you! I will send a v2!
Will


>
> Jan