diff mbox series

[v0,1/3] gas: minor reformatting in command line help and doc

Message ID 20240627135017.1971420-2-matthieu.longo@arm.com
State Superseded
Headers
Series gas: add command line option to inhibit info messages |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_binutils_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_binutils_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_binutils_check--master-aarch64 success Test passed
linaro-tcwg-bot/tcwg_binutils_check--master-arm success Test passed

Commit Message

Matthieu Longo June 27, 2024, 1:50 p.m. UTC 
  - help message: add missing comma between the short and long option
- as doc:
  - brief summary of how to invoke gas: separate [-w] [-x] on a new line as those
  two options have nothing to do with the warning options.
  - reordering of the warning options to have the same order as the listing.
  - no-warn option description: change an "and" to a "or", as it is either the short
  or long option to use, but not both at the same time.
- remove trailing whitespaces.
---
 gas/as.c        | 18 +++++++++---------
 gas/as.h        |  2 +-
 gas/doc/as.texi | 29 ++++++++++++++++-------------
 3 files changed, 26 insertions(+), 23 deletions(-)

Comments

Jan Beulich June 28, 2024, 12:27 p.m. UTC | #1 
On 27.06.2024 15:50, Matthieu Longo wrote:
> 
> - help message: add missing comma between the short and long option

Why "missing"? IOW who or what says there ought to be commas? Looking
at just objcopy, objdump, and readelf, it's objdump being the outlier
in having commas there.

You also move -W / --no-warn down for no apparent reason. Them being
ahead of --warn is more logical imo, as warnings are on by default.
(Same for their handling, where I view the resulting code churn as
yet less relevant.)

> - as doc:
>   - brief summary of how to invoke gas: separate [-w] [-x] on a new line as those
>   two options have nothing to do with the warning options.
>   - reordering of the warning options to have the same order as the listing.

Except that in order to "need" to do that you first had to change the
listing.

>   - no-warn option description: change an "and" to a "or", as it is either the short

Along with that I think "options" there wants to change to singular.

Jan
Matthieu Longo June 28, 2024, 6:14 p.m. UTC | #2 
>On 27.06.2024 15:50, Matthieu Longo wrote:
>>
>> - help message: add missing comma between the short and long option
>
>Why "missing"? IOW who or what says there ought to be commas? Looking at just objcopy, objdump, and readelf, it's objdump being the outlier in having commas there.

ld, nm have commas as well. Python argparse also prints the short and long options separated with a comma. Same for git. The commas seem a bit more common.
Gas has currently a mix of both, so I opted for the comma between short and long options.
Do you have any objection to keep commas here ?

>You also move -W / --no-warn down for no apparent reason. Them being ahead of --warn is more logical imo, as warnings are on by default.
>(Same for their handling, where I view the resulting code churn as yet less relevant.)

I will change it in the next revision.

>> - as doc:
>>   - brief summary of how to invoke gas: separate [-w] [-x] on a new line as those
>>   two options have nothing to do with the warning options.
>>   - reordering of the warning options to have the same order as the listing.
>
>Except that in order to "need" to do that you first had to change the listing.
>
>>   - no-warn option description: change an "and" to a "or", as it is
>> either the short
>
>Along with that I think "options" there wants to change to singular.
>
>Jan
Jan Beulich July 1, 2024, 6:20 a.m. UTC | #3 
On 28.06.2024 20:14, Matthieu Longo wrote:
>> On 27.06.2024 15:50, Matthieu Longo wrote:
>>>
>>> - help message: add missing comma between the short and long option
>>
>> Why "missing"? IOW who or what says there ought to be commas? Looking at just objcopy, objdump, and readelf, it's objdump being the outlier in having commas there.
> 
> ld, nm have commas as well. Python argparse also prints the short and long options separated with a comma. Same for git. The commas seem a bit more common.
> Gas has currently a mix of both, so I opted for the comma between short and long options.
> Do you have any objection to keep commas here ?

I don't strictly mind the change, as long as the justification is at
least "softened" a little. As to some (two) indeed having commas - I
surely value consistency. IOW alternatively those would want the commas
dropped (really: replaced by blanks).

Jan
diff mbox series

Patch

diff --git a/gas/as.c b/gas/as.c
index 9e059f99ef1..81a0925184c 100644
--- a/gas/as.c
+++ b/gas/as.c
@@ -333,7 +333,7 @@  Options:\n\
   fprintf (stream, _("\
   -f                      skip whitespace and comment preprocessing\n"));
   fprintf (stream, _("\
-  -g --gen-debug          generate debugging information\n"));
+  -g, --gen-debug         generate debugging information\n"));
   fprintf (stream, _("\
   --gstabs                generate STABS debugging information\n"));
   fprintf (stream, _("\
@@ -361,9 +361,9 @@  Options:\n\
   fprintf (stream, _("\
   -K                      warn when differences altered for long displacements\n"));
   fprintf (stream, _("\
-  -L,--keep-locals        keep local symbols (e.g. starting with `L')\n"));
+  -L, --keep-locals       keep local symbols (e.g. starting with `L')\n"));
   fprintf (stream, _("\
-  -M,--mri                assemble in MRI compatibility mode\n"));
+  -M, --mri               assemble in MRI compatibility mode\n"));
   fprintf (stream, _("\
   --MD FILE               write dependency information in FILE (default none)\n"));
   fprintf (stream, _("\
@@ -388,10 +388,10 @@  Options:\n\
   fprintf (stream, _("\
   --version               print assembler version number and exit\n"));
   fprintf (stream, _("\
-  -W  --no-warn           suppress warnings\n"));
-  fprintf (stream, _("\
   --warn                  don't suppress warnings\n"));
   fprintf (stream, _("\
+  -W, --no-warn           suppress warnings\n"));
+  fprintf (stream, _("\
   --fatal-warnings        treat warnings as errors\n"));
 #ifdef HAVE_ITBL_CPU
   fprintf (stream, _("\
@@ -968,15 +968,15 @@  This program has absolutely no warranty.\n"));
 	  flag_readonly_data_in_text = 1;
 	  break;
 
-	case 'W':
-	  flag_no_warnings = 1;
-	  break;
-
 	case OPTION_WARN:
 	  flag_no_warnings = 0;
 	  flag_fatal_warnings = 0;
 	  break;
 
+	case 'W':
+	  flag_no_warnings = 1;
+	  break;
+
 	case OPTION_WARN_FATAL:
 	  flag_no_warnings = 0;
 	  flag_fatal_warnings = 1;
diff --git a/gas/as.h b/gas/as.h
index 69d7ae2cd17..24bf66eb8a7 100644
--- a/gas/as.h
+++ b/gas/as.h
@@ -315,7 +315,7 @@  COMMON bool flag_macro_alternate;
 COMMON unsigned char flag_readonly_data_in_text; /* -R */
 
 /* True if warnings should be inhibited.  */
-COMMON int flag_no_warnings; /* -W */
+COMMON int flag_no_warnings; /* -W, --no-warn */
 
 /* True if warnings count as errors.  */
 COMMON int flag_fatal_warnings; /* --fatal-warnings */
diff --git a/gas/doc/as.texi b/gas/doc/as.texi
index 33169a5ad34..ad86b8f5a74 100644
--- a/gas/doc/as.texi
+++ b/gas/doc/as.texi
@@ -260,7 +260,8 @@  gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
  [@b{--size-check=[error|warning]}]
  [@b{--statistics}]
  [@b{-v}] [@b{-version}] [@b{--version}]
- [@b{-W}] [@b{--warn}] [@b{--fatal-warnings}] [@b{-w}] [@b{-x}]
+ [@b{--warn}] [@b{-W}] [@b{--no-warn}] [@b{--fatal-warnings}]
+ [@b{-w}] [@b{-x}]
  [@b{-Z}] [@b{@@@var{FILE}}]
  [@var{target-options}]
  [@b{--}|@var{files} @dots{}]
@@ -979,6 +980,9 @@  Print the @command{as} version.
 @item --version
 Print the @command{as} version and exit.
 
+@item --warn
+Don't suppress warning messages or treat them as errors.
+
 @item -W
 @itemx --no-warn
 Suppress warning messages.
@@ -986,9 +990,6 @@  Suppress warning messages.
 @item --fatal-warnings
 Treat warnings as errors.
 
-@item --warn
-Don't suppress warning messages or treat them as errors.
-
 @item -w
 Ignored.
 
@@ -2463,7 +2464,7 @@  assembler.)
 * statistics::    --statistics to see statistics about assembly
 * traditional-format:: --traditional-format for compatible output
 * v::             -v to announce version
-* W::             -W, --no-warn, --warn, --fatal-warnings to control warnings
+* W::             --warn, -W, --no-warn, --fatal-warnings to control warnings
 * Z::             -Z to make object file even after errors
 @end menu
 
@@ -2863,18 +2864,25 @@  option @samp{-v} (which you can also spell as @samp{-version}) on the
 command line.
 
 @node W
-@section Control Warnings: @option{-W}, @option{--warn}, @option{--no-warn}, @option{--fatal-warnings}
+@section Control Warnings: @option{--warn}, @option{-W}, @option{--no-warn}, @option{--fatal-warnings}
 
 @command{@value{AS}} should never give a warning or error message when
 assembling compiler output.  But programs written by people often
 cause @command{@value{AS}} to give a warning that a particular assumption was
 made.  All such warnings are directed to the standard error file.
 
+@kindex --warn
+@cindex outputing warnings
+@cindex warnings, switching on
+Warnings are switched on by default. They can be switched off with @option{-W} or
+@option{--no-warn}. Specifying the @option{--warn} again later on the command line
+will switch on warnings again, and cause them to be output as usual.
+
 @kindex -W
 @kindex --no-warn
 @cindex suppressing warnings
 @cindex warnings, suppressing
-If you use the @option{-W} and @option{--no-warn} options, no warnings are issued.
+If you use the @option{-W} or @option{--no-warn} options, no warnings are issued.
 This only affects the warning messages: it does not change any particular of
 how @command{@value{AS}} assembles your file.  Errors, which stop the assembly,
 are still reported.
@@ -2885,11 +2893,6 @@  are still reported.
 If you use the @option{--fatal-warnings} option, @command{@value{AS}} considers
 files that generate warnings to be in error.
 
-@kindex --warn
-@cindex warnings, switching on
-You can switch these options off again by specifying @option{--warn}, which
-causes warnings to be output as usual.
-
 @node Z
 @section Generate Object File in Spite of Errors: @option{-Z}
 @cindex object file, after errors
@@ -7785,7 +7788,7 @@  section, using the endian model of the target.  If an expression will not fit
 in two bytes, a warning message is displayed and the least significant two
 bytes of the expression's value are used.  If an expression cannot be evaluated
 at assembly time then relocations will be generated in order to compute the
-value at link time.  
+value at link time.
 
 This directive does not apply any alignment before or after inserting the
 values.  As a result of this, if relocations are generated, they may be