Re: [arm] Too strict linker assert?

2019-04-10 Thread Christophe Lyon
On Wed, 10 Apr 2019 at 00:30, Richard Earnshaw
 wrote:
>
> On 09/04/2019 13:26, Christophe Lyon wrote:
> > Hi,
> >
> > While building a newlib-based arm-eabi toolchain with
> > --with-multilib-list=rmprofile, I faced a linker assertion failure in
> > elf32_arm_merge_eabi_attributes (bfd/elf32-arm.c):
> > BFD_ASSERT (in_attr[Tag_ABI_HardFP_use].i == 0)
> >
> > I traced this down to newlib's impure.o containing only data, and thus
> > GCC does not emit a .fpu directive when compiling impure.c.
> >
> > When the linker merges impure.o's attributes with the other
> > contributions that already have
> > Tag_FP_arch, this assertion fails because in my multilib case (-mthumb
> > -march=armv7e-m+fp -mfloat-abi=softfp) all the object files have
> >   Tag_ABI_HardFP_use: SP only
> >
> > Put differently, all objects but impure.o have
> >   Tag_ABI_HardFP_use: SP only
> >   Tag_FP_arch: VFPv4-D16
> > but impure.o has only:
> >   Tag_ABI_HardFP_use: SP only
> > (and no Tag_FP_arch)
> >
> > Removing the linker assertion makes the build succeed, so I guess my
> > question is: should I submit a linker patch to remove the assert
> > because it is too strict, or should I find a way to make GCC emit the
> > needed .fpu directive?
> >
> > Thanks,
> >
> > Christophe
> >
>
> I think removing the assert will remove entirely the check that a user
> is not mixing code with incompatible ABIs.  So probably this is a bug.
>
> Which version of GCC were you using, and which version of binutils?  I
> thought I'd addressed this when doing the rework of the FPU option code;
> but perhaps I've missed something somewhere.  I'll check in more detail
> tomorrow.
>

This was with binutils-2.28-branch from Apr 11th, 2017  and GCC trunk
from Nov 15th, 2018 (r266188), newlib master from Apr 1st 2019.

However, upgrading to binutils master avoided the problem.

Thanks,

Christophe


Re: [arm] Too strict linker assert?

2019-04-10 Thread Richard Earnshaw (lists)
On 10/04/2019 10:16, Christophe Lyon wrote:
> On Wed, 10 Apr 2019 at 00:30, Richard Earnshaw
>  wrote:
>>
>> On 09/04/2019 13:26, Christophe Lyon wrote:
>>> Hi,
>>>
>>> While building a newlib-based arm-eabi toolchain with
>>> --with-multilib-list=rmprofile, I faced a linker assertion failure in
>>> elf32_arm_merge_eabi_attributes (bfd/elf32-arm.c):
>>> BFD_ASSERT (in_attr[Tag_ABI_HardFP_use].i == 0)
>>>
>>> I traced this down to newlib's impure.o containing only data, and thus
>>> GCC does not emit a .fpu directive when compiling impure.c.
>>>
>>> When the linker merges impure.o's attributes with the other
>>> contributions that already have
>>> Tag_FP_arch, this assertion fails because in my multilib case (-mthumb
>>> -march=armv7e-m+fp -mfloat-abi=softfp) all the object files have
>>>   Tag_ABI_HardFP_use: SP only
>>>
>>> Put differently, all objects but impure.o have
>>>   Tag_ABI_HardFP_use: SP only
>>>   Tag_FP_arch: VFPv4-D16
>>> but impure.o has only:
>>>   Tag_ABI_HardFP_use: SP only
>>> (and no Tag_FP_arch)
>>>
>>> Removing the linker assertion makes the build succeed, so I guess my
>>> question is: should I submit a linker patch to remove the assert
>>> because it is too strict, or should I find a way to make GCC emit the
>>> needed .fpu directive?
>>>
>>> Thanks,
>>>
>>> Christophe
>>>
>>
>> I think removing the assert will remove entirely the check that a user
>> is not mixing code with incompatible ABIs.  So probably this is a bug.
>>
>> Which version of GCC were you using, and which version of binutils?  I
>> thought I'd addressed this when doing the rework of the FPU option code;
>> but perhaps I've missed something somewhere.  I'll check in more detail
>> tomorrow.
>>
> 
> This was with binutils-2.28-branch from Apr 11th, 2017  and GCC trunk
> from Nov 15th, 2018 (r266188), newlib master from Apr 1st 2019.
> 
> However, upgrading to binutils master avoided the problem.
> 
> Thanks,
> 
> Christophe
> 

Digging through the archives it does look as though I reached the same
conclusion as you did: that the assert is too harsh.  The patch was this
one:

https://sourceware.org/ml/binutils/2017-06/msg00090.html

R.


Documentation style for options with optional levels

2019-04-10 Thread Jonathan Wakely

For options that can be used as -foo or -foo=level we have a variety
of different styels for documenting what the default level is. See
below for several examples. I find this a bit confusing when try to
see what it means to use the option without a level.

Do we want to pick a style and try to be consistent?


For -Wformat-overflow we show the option with and without the level:

 @item -Wformat-overflow
 @itemx -Wformat-overflow=1
 @opindex Wformat-overflow
 @opindex Wno-format-overflow
 Level @var{1} of @option{-Wformat-overflow} enabled by @option{-Wformat}

For -Wshift-overflow we use prose to say what omitting the level
means:

 @item -Wshift-overflow=1
 This is the warning level of @option{-Wshift-overflow} and is enabled
 by default in C99 and C++11 modes (and newer).

Similarly for -Wunused-const-variable:

 @item -Wunused-const-variable=1
 This is the warning level that is enabled by @option{-Wunused-variable} for
 C.

For -Wstrict-aliasing we add it to the sub-heading for the description
of the corresponding level:

 Level 3 (default for @option{-Wstrict-aliasing}):

For -Wstrict-overflow we add a sentence to the end of the paragraph
about the corresponding level:

 @item -Wstrict-overflow=2
 Also warn about other cases where a comparison is simplified to a
 constant.  For example: @code{abs (x) >= 0}.  This can only be
 simplified when signed integer overflow is undefined, because
 @code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
 zero.  @option{-Wstrict-overflow} (with no level) is the same as
 @option{-Wstrict-overflow=2}.

For -Warray-bounds we list both options separately, and then also list
the forms with levels and say what no level means:

 @item -Warray-bounds
 @itemx -Warray-bounds=@var{n}
 @opindex Wno-array-bounds
 @opindex Warray-bounds
 This option is only active when @option{-ftree-vrp} is active
 (default for @option{-O2} and above). It warns about subscripts to arrays
 that are always out of bounds. This warning is enabled by @option{-Wall}.

 @table @gcctabopt
 @item -Warray-bounds=1
 This is the warning level of @option{-Warray-bounds} and is enabled
 by @option{-Wall}; higher levels are not, and must be explicitly requested.

For -Wattribute-alias and -Wplacement-new we do the same as -Warray-bounds.

For -Wnormalized we use prose:

 There are four levels of warning supported by GCC@.  The default is
 @option{-Wnormalized=nfc}, which warns about any identifier that is

For -g we say:

 @item -g@var{level}
 @itemx -ggdb@var{level}
 @itemx -gstabs@var{level}
 @itemx -gxcoff@var{level}
 @itemx -gvms@var{level}
 Request debugging information and also use @var{level} to specify how
 much information.  The default level is 2.

For -flive-patching we add a paragraph at the end:

 When @option{-flive-patching} is specified without any value, the default value
 is "inline-clone".





Re: [arm] Too strict linker assert?

2019-04-10 Thread Christophe Lyon
On Wed, 10 Apr 2019 at 11:42, Richard Earnshaw (lists)
 wrote:
>
> On 10/04/2019 10:16, Christophe Lyon wrote:
> > On Wed, 10 Apr 2019 at 00:30, Richard Earnshaw
> >  wrote:
> >>
> >> On 09/04/2019 13:26, Christophe Lyon wrote:
> >>> Hi,
> >>>
> >>> While building a newlib-based arm-eabi toolchain with
> >>> --with-multilib-list=rmprofile, I faced a linker assertion failure in
> >>> elf32_arm_merge_eabi_attributes (bfd/elf32-arm.c):
> >>> BFD_ASSERT (in_attr[Tag_ABI_HardFP_use].i == 0)
> >>>
> >>> I traced this down to newlib's impure.o containing only data, and thus
> >>> GCC does not emit a .fpu directive when compiling impure.c.
> >>>
> >>> When the linker merges impure.o's attributes with the other
> >>> contributions that already have
> >>> Tag_FP_arch, this assertion fails because in my multilib case (-mthumb
> >>> -march=armv7e-m+fp -mfloat-abi=softfp) all the object files have
> >>>   Tag_ABI_HardFP_use: SP only
> >>>
> >>> Put differently, all objects but impure.o have
> >>>   Tag_ABI_HardFP_use: SP only
> >>>   Tag_FP_arch: VFPv4-D16
> >>> but impure.o has only:
> >>>   Tag_ABI_HardFP_use: SP only
> >>> (and no Tag_FP_arch)
> >>>
> >>> Removing the linker assertion makes the build succeed, so I guess my
> >>> question is: should I submit a linker patch to remove the assert
> >>> because it is too strict, or should I find a way to make GCC emit the
> >>> needed .fpu directive?
> >>>
> >>> Thanks,
> >>>
> >>> Christophe
> >>>
> >>
> >> I think removing the assert will remove entirely the check that a user
> >> is not mixing code with incompatible ABIs.  So probably this is a bug.
> >>
> >> Which version of GCC were you using, and which version of binutils?  I
> >> thought I'd addressed this when doing the rework of the FPU option code;
> >> but perhaps I've missed something somewhere.  I'll check in more detail
> >> tomorrow.
> >>
> >
> > This was with binutils-2.28-branch from Apr 11th, 2017  and GCC trunk
> > from Nov 15th, 2018 (r266188), newlib master from Apr 1st 2019.
> >
> > However, upgrading to binutils master avoided the problem.
> >
> > Thanks,
> >
> > Christophe
> >
>
> Digging through the archives it does look as though I reached the same
> conclusion as you did: that the assert is too harsh.  The patch was this
> one:
>
> https://sourceware.org/ml/binutils/2017-06/msg00090.html
>

Ha, thanks for the pointer, and sorry for the noise.

Christophe


Re: Documentation style for options with optional levels

2019-04-10 Thread Nathan Sidwell

On 4/10/19 7:13 AM, Jonathan Wakely wrote:

For options that can be used as -foo or -foo=level we have a variety
of different styels for documenting what the default level is. See
below for several examples. I find this a bit confusing when try to
see what it means to use the option without a level.

Do we want to pick a style and try to be consistent?


yes?

All the examples you give leave something to be desired.


For -Wformat-overflow we show the option with and without the level:

  @item -Wformat-overflow
  @itemx -Wformat-overflow=1
  @opindex Wformat-overflow
  @opindex Wno-format-overflow
  Level @var{1} of @option{-Wformat-overflow} enabled by @option{-Wformat}


The @item is the clearest to read, and also the most accurate as it 
shows you can provide it without a level.  But from that snippet there's 
no indication what not giving a level gets you.  There needs to be some 
words somewhere to say what it maps to.



For -Wshift-overflow we use prose to say what omitting the level
means:

  @item -Wshift-overflow=1
  This is the warning level of @option{-Wshift-overflow} and is enabled
  by default in C99 and C++11 modes (and newer).


.. for example that, I can't tell if I can say just -Wshift-overflow and 
get level 1, or if I'll get level 1 whatever unless I say 
-Wno-shift-overflow



For -Warray-bounds we list both options separately, and then also list
the forms with levels and say what no level means:

  @item -Warray-bounds
  @itemx -Warray-bounds=@var{n}
  @opindex Wno-array-bounds
  @opindex Warray-bounds
  This option is only active when @option{-ftree-vrp} is active
  (default for @option{-O2} and above). It warns about subscripts to arrays
  that are always out of bounds. This warning is enabled by @option{-Wall}.

  @table @gcctabopt
  @item -Warray-bounds=1
  This is the warning level of @option{-Warray-bounds} and is enabled
  by @option{-Wall}; higher levels are not, and must be explicitly 
requested.


In context with the other levels, I see that is trying to tell you that 
1 is the default, but it's unclear.  My first reading was that 1 gets 
you a warning level, (with the implication that 2 got you an error level 
or something?)


nathan


--
Nathan Sidwell


Re: Documentation style for options with optional levels

2019-04-10 Thread Jonathan Wakely

On 10/04/19 08:42 -0400, Nathan Sidwell wrote:

On 4/10/19 7:13 AM, Jonathan Wakely wrote:

For options that can be used as -foo or -foo=level we have a variety
of different styels for documenting what the default level is. See
below for several examples. I find this a bit confusing when try to
see what it means to use the option without a level.

Do we want to pick a style and try to be consistent?


yes?


Thought so. "Somebody" should do something about this ;-)



All the examples you give leave something to be desired.


For -Wformat-overflow we show the option with and without the level:

 @item -Wformat-overflow
 @itemx -Wformat-overflow=1
 @opindex Wformat-overflow
 @opindex Wno-format-overflow
 Level @var{1} of @option{-Wformat-overflow} enabled by @option{-Wformat}


The @item is the clearest to read, and also the most accurate as it 
shows you can provide it without a level.  But from that snippet 
there's no indication what not giving a level gets you.  There needs 
to be some words somewhere to say what it maps to.



For -Wshift-overflow we use prose to say what omitting the level
means:

 @item -Wshift-overflow=1
 This is the warning level of @option{-Wshift-overflow} and is enabled
 by default in C99 and C++11 modes (and newer).


.. for example that, I can't tell if I can say just -Wshift-overflow 
and get level 1, or if I'll get level 1 whatever unless I say 
-Wno-shift-overflow



For -Warray-bounds we list both options separately, and then also list
the forms with levels and say what no level means:

 @item -Warray-bounds
 @itemx -Warray-bounds=@var{n}
 @opindex Wno-array-bounds
 @opindex Warray-bounds
 This option is only active when @option{-ftree-vrp} is active
 (default for @option{-O2} and above). It warns about subscripts to arrays
 that are always out of bounds. This warning is enabled by @option{-Wall}.

 @table @gcctabopt
 @item -Warray-bounds=1
 This is the warning level of @option{-Warray-bounds} and is enabled
 by @option{-Wall}; higher levels are not, and must be explicitly 
requested.


In context with the other levels, I see that is trying to tell you 
that 1 is the default, but it's unclear.  My first reading was that 1 
gets you a warning level, (with the implication that 2 got you an 
error level or something?)


Right. Too often you have to try and infer what it's saying, and when
every case is presented differently you can't even apply the same
inferences to different options!

If we decide on a way to document these cases that is clear and
unambiguous, I'll volunteer to go through the existing docs and usee
that style.




Re: Documentation style for options with optional levels

2019-04-10 Thread Sandra Loosemore

On 4/10/19 5:13 AM, Jonathan Wakely wrote:

For options that can be used as -foo or -foo=level we have a variety
of different styels for documenting what the default level is. See
below for several examples. I find this a bit confusing when try to
see what it means to use the option without a level.

Do we want to pick a style and try to be consistent?


I think part of the problem here is that it collides with the existing 
convention that we document the -foo form for options that default to 
off and the -no-foo form for options that default to on, and we probably 
have instances of both flavors that were originally binary options but 
now take an optional level.  Plus people tack on to the documentation 
incrementally for new options and don't always check for or copy the 
style of documentation for similar option syntax elsewhere.


I suspect anything we do will eventually get bit-rotten anyway, but if 
you want a convention, I'd propose that we always document -foo=level as 
the primary form and explicitly list whichever of -foo and/or -no-foo 
are also supported (regardless of the default), with information in the 
text about what level they correspond to, what the default is, etc. 
E.g. roughly following this organization:


@item -foo=@var{level}
@itemx -foo
@itemx -no-foo
@opindex foo

This option controls
The @var{level} may be one of

@option{-foo} without a @var{level} is equivalent to
@option{-fno-foo} is equivalent to

The default is  [and/or information about what setting is implied by 
other options].


-Sandra


GCC 8: adding, thru a plugin, an analyzing RTL pass after pro_and_epilogue issue with its reference_pass_name

2019-04-10 Thread Basile Starynkevitch

Hello All,

This is work done for the CHARIOT H2020 project (see 
https://www.chariotproject.eu/ for more context) in relation with my 
BISMON project (see http://github.com/bstarynk/bismon/ for more, and, if 
you want more context, read the draft report on 
http://starynkevitch.net/Basile/bismon-chariot-doc.pdf but skip the few 
first pages for H2020 managers).


I have to make a preliminary proof-of-concept that my BISMON project 
could be useful, with some ad-hoc GCC 8.3 plugin, to compute a crude 
approximation of the call stack of a tiny freestanding kernel (for x86 
in 32 bits, so compiled with: gcc-8 -ffreestanding -m32 -O2 -Wall 
-fstack-usage and my plugin).


I am working right now on that hand-written GCC 8.3 plugin. It inserts 
two GCC passes, and both passes are only analyzing passes (they don't 
change a single bit of GIMPLE or RTL representations).


The first pass, named chariot_callgraph, is (oversimplifying) printing 
the call graph (and I will improve later that pass to communicate with 
BISMON).  It is a pass of kind GIMPLE_PASS successfully inserted after 
the reference_pass_name "sra" and it works well enough.


The second pass, named chariot_framesize, is (oversimplifying) expected 
to run with the printing the call frame size (and I will improve later 
that pass to communicate with BISMON).


I want to insert that second pass following this explanation (in a 
comment of mine).


  /* the fun->su exists as soon as -fstack-usage is passed, but it is
 filled much later, by the RTL pass named "pro_and_epilogue" at
 gcc-8.3.0/gcc/config/i386/i386.c:13930 in function
 ix86_expand_prologue; that pass is
 pass_data_thread_prologue_and_epilogue defined in gcc/function.c
 line 6553 ... */


To insert that second pass, I tried many things and failed. I was 
expecting that an rtl- prefix is needed for an RTL pass. My plugin_init 
contains



  struct register_pass_info my_framesize_pass_info;
  my_framesize_pass_info.pass = make_pass_chariot_framesize (g);
  //#warning the below reference pass name is wrong for 
my_framesize_pass_info

  my_framesize_pass_info.reference_pass_name = "rtl-pro_and_epilogue";
  my_framesize_pass_info.ref_pass_instance_number = 1;
  my_framesize_pass_info.pos_op = PASS_POS_INSERT_AFTER;
  register_callback (plugin_name, PLUGIN_PASS_MANAGER_SETUP, NULL,
 &my_framesize_pass_info);

But for some reason I cannot understand the reference_pass_name is 
wrong. Using "rtl-pro_and_epilogue" don't work. And I tried many 
variants without any success during several hours.



So what is the reference_pass_name to use with register_callback like 
above to mention that pass_data_thread_prologue_and_epilogue defined in 
gcc/function.c line 6553 ?



The entire code (of that proof-of-concept work in progress) is 
temporarily available on 
http://starynkevitch.net/Basile/chariotdemo-2019-Apr-10-5414f7e3a173.tar.bz2 
which is a small archive of 14340 bytes. Please notice that the code I 
have written in collaboration with my colleagues Franck Védrine (in BCC) 
and Yves Lhuillier at CEA LIST is under GPLv3+ license. But that example 
also contains some third-party tiny code taken from 
https://wiki.osdev.org/Bare_Bones and in good faith we don't know what 
license is that code (files kernel.c etc...) but we guess it is morally 
in the public domain or open source (but we are not lawyers) since given 
as an example on some wiki page.


Regards


--
Basile STARYNKEVITCH   == http://starynkevitch.net/Basile
opinions are mine only - les opinions sont seulement miennes
Bourg La Reine, France



Re: GCC 8: adding, thru a plugin, an analyzing RTL pass after pro_and_epilogue issue with its reference_pass_name

2019-04-10 Thread David Malcolm
On Wed, 2019-04-10 at 17:53 +0200, Basile Starynkevitch wrote:
> Hello All,
> 
> This is work done for the CHARIOT H2020 project (see 
> https://www.chariotproject.eu/ for more context) in relation with my 
> BISMON project (see http://github.com/bstarynk/bismon/ for more, and,
> if 
> you want more context, read the draft report on 
> http://starynkevitch.net/Basile/bismon-chariot-doc.pdf but skip the
> few 
> first pages for H2020 managers).
> 
> I have to make a preliminary proof-of-concept that my BISMON project 
> could be useful, with some ad-hoc GCC 8.3 plugin, to compute a crude 
> approximation of the call stack of a tiny freestanding kernel (for
> x86 
> in 32 bits, so compiled with: gcc-8 -ffreestanding -m32 -O2 -Wall 
> -fstack-usage and my plugin).
> 
> I am working right now on that hand-written GCC 8.3 plugin. It
> inserts 
> two GCC passes, and both passes are only analyzing passes (they
> don't 
> change a single bit of GIMPLE or RTL representations).
> 
> The first pass, named chariot_callgraph, is (oversimplifying)
> printing 
> the call graph (and I will improve later that pass to communicate
> with 
> BISMON).  It is a pass of kind GIMPLE_PASS successfully inserted
> after 
> the reference_pass_name "sra" and it works well enough.
> 
> The second pass, named chariot_framesize, is (oversimplifying)
> expected 
> to run with the printing the call frame size (and I will improve
> later 
> that pass to communicate with BISMON).
> 
> I want to insert that second pass following this explanation (in a 
> comment of mine).
> 
>/* the fun->su exists as soon as -fstack-usage is passed, but it
> is
>   filled much later, by the RTL pass named "pro_and_epilogue" at
>   gcc-8.3.0/gcc/config/i386/i386.c:13930 in function
>   ix86_expand_prologue; that pass is
>   pass_data_thread_prologue_and_epilogue defined in
> gcc/function.c
>   line 6553 ... */
> 
> 
> To insert that second pass, I tried many things and failed. I was 
> expecting that an rtl- prefix is needed for an RTL pass. My
> plugin_init 
> contains
> 
> 
>struct register_pass_info my_framesize_pass_info;
>my_framesize_pass_info.pass = make_pass_chariot_framesize (g);
>//#warning the below reference pass name is wrong for 
> my_framesize_pass_info
>my_framesize_pass_info.reference_pass_name = "rtl-
> pro_and_epilogue";
>my_framesize_pass_info.ref_pass_instance_number = 1;
>my_framesize_pass_info.pos_op = PASS_POS_INSERT_AFTER;
>register_callback (plugin_name, PLUGIN_PASS_MANAGER_SETUP, NULL,
>   &my_framesize_pass_info);
> 
> But for some reason I cannot understand the reference_pass_name is 
> wrong. Using "rtl-pro_and_epilogue" don't work. And I tried many 
> variants without any success during several hours.
> 
> 
> So what is the reference_pass_name to use with register_callback
> like 
> above to mention that pass_data_thread_prologue_and_epilogue defined
> in 
> gcc/function.c line 6553 ?

It's been a long time since I touched this code, but the gcc-python-
plugin has an example of an RTL pass in a plugin (albeit in Python)
https://github.com/davidmalcolm/gcc-python-plugin/blob/master/tests/plugin/new-passes/script.py#L97

I just smoketested it and the pass appears to get run.

Specifically, my example registers the plugin pass after "expand" (so I
don't think you need the "rtl-" prefix there; I think these prefixes
are for dump names rather than pass names).

Hope this is helpful
Dave



> 
> The entire code (of that proof-of-concept work in progress) is 
> temporarily available on 
> http://starynkevitch.net/Basile/chariotdemo-2019-Apr-10-5414f7e3a173.
> tar.bz2 
> which is a small archive of 14340 bytes. Please notice that the code
> I 
> have written in collaboration with my colleagues Franck Védrine (in
> BCC) 
> and Yves Lhuillier at CEA LIST is under GPLv3+ license. But that
> example 
> also contains some third-party tiny code taken from 
> https://wiki.osdev.org/Bare_Bones and in good faith we don't know
> what 
> license is that code (files kernel.c etc...) but we guess it is
> morally 
> in the public domain or open source (but we are not lawyers) since
> given 
> as an example on some wiki page.
> 
> Regards
> 
> 


Apache CouchDB users list

2019-04-10 Thread Lana
Hi,

Would you be interested in Apache CouchDB users list for your business
campaign?

Also have users of MongoDB, Amazon DynamoDB, MariaDB, Apache Hadoop, Redis,
Cassandra, Cloudant, RethinkDB etc.

If you are interested let me know your targeted criteria, so that I will
run the counts and pricing for your review.

Await your response.

Regards,

*Lana*

Marketing Leadgen





For unsubscribe reply back in subject line with “ Opt-Out”
[image: beacon]


Re: Documentation style for options with optional levels

2019-04-10 Thread Martin Sebor

On 4/10/19 9:46 AM, Sandra Loosemore wrote:

On 4/10/19 5:13 AM, Jonathan Wakely wrote:

For options that can be used as -foo or -foo=level we have a variety
of different styels for documenting what the default level is. See
below for several examples. I find this a bit confusing when try to
see what it means to use the option without a level.

Do we want to pick a style and try to be consistent?


I think part of the problem here is that it collides with the existing 
convention that we document the -foo form for options that default to 
off and the -no-foo form for options that default to on, and we probably 
have instances of both flavors that were originally binary options but 
now take an optional level.  Plus people tack on to the documentation 
incrementally for new options and don't always check for or copy the 
style of documentation for similar option syntax elsewhere.


I suspect anything we do will eventually get bit-rotten anyway, but if 
you want a convention, I'd propose that we always document -foo=level as 
the primary form and explicitly list whichever of -foo and/or -no-foo 
are also supported (regardless of the default), with information in the 
text about what level they correspond to, what the default is, etc. E.g. 
roughly following this organization:


@item -foo=@var{level}
@itemx -foo
@itemx -no-foo
@opindex foo

This option controls
The @var{level} may be one of

@option{-foo} without a @var{level} is equivalent to
@option{-fno-foo} is equivalent to

The default is  [and/or information about what setting is implied by 
other options].


I find the -ffoo vs -fno-foo convention very confusing, not only
because I never know if the manual is correct.

Rather than trusting ourselves to get it right, could these details
be generated instead?  It seems the option processing AWK scripts
should be able to extract this from the .opt files fill it in
the right places in the .texi files, shouldn't they?  All they
would need is some markup to know what to replace.

Martin