I went ahead and fixed all the .opt files as you suggested.
Even with scripting it was a lot more work that I initially
planned or expected but it's done now. Since those changes
are large and mechanical, I will submit them in a standalone
patch, separate from code changes that I include in this
message.
Attached is patch 1 with the changes to opts.c you mention
below, adding periods to the help output printed by the driver,
and some tweaks to the test suite, plus changelogs for both
sets.
Martin
gcc/ChangeLog:
2015-10-21 Martin Sebor <mse...@redhat.com>
PR driver/68043
* opts.c (undocumented_msg, use_diagnosed_msg): New globals.
(print_filtered_help): Reference aliased option's name and
encourage
readers to use it in preference to the alias if the former is not
documented. Mention when using an option is diagnosed.
* gcc.c (display_help): End each sentence with a period.
* ada/gcc-interface/lang.opt: End each sentence that describes
an option with a period.
* c-family/c.opt: Same.
* common.opt: Same.
* config/aarch64/aarch64.opt: Same.
* config/alpha/alpha.opt: Same.
* config/arc/arc.opt: Same.
* config/arm/arm.opt: Same.
* config/avr/avr.opt: Same.
* config/bfin/bfin.opt: Same.
* config/c6x/c6x.opt: Same.
* config/cr16/cr16.opt: Same.
* config/cris/cris.opt: Same.
* config/cris/linux.opt: Same.
* config/darwin.opt: Same.
* config/epiphany/epiphany.opt: Same.
* config/fr30/fr30.opt: Same.
* config/frv/frv.opt: Same.
* config/ft32/ft32.opt: Same.
* config/g.opt: Same.
* config/h8300/h8300.opt: Same.
* config/i386/cygming.opt: Same.
* config/i386/djgpp.opt: Same.
* config/i386/i386.opt: Same.
* config/i386/interix.opt: Same.
* config/i386/mingw-w64.opt: Same.
* config/i386/mingw.opt: Same.
* config/ia64/ia64.opt: Same.
* config/ia64/ilp32.opt: Same.
* config/iq2000/iq2000.opt: Same.
* config/linux.opt: Same.
* config/lm32/lm32.opt: Same.
* config/lynx.opt: Same.
* config/m32c/m32c.opt: Same.
* config/m32r/m32r.opt: Same.
* config/m68k/ieee.opt: Same.
* config/m68k/m68k.opt: Same.
* config/mcore/mcore.opt: Same.
* config/mep/mep.opt: Same.
* config/microblaze/microblaze.opt: Same.
* config/mips/mips.opt: Same.
* config/mmix/mmix.opt: Same.
* config/mn10300/mn10300.opt: Same.
* config/moxie/moxie.opt: Same.
* config/msp430/msp430.opt: Same.
* config/nios2/elf.opt: Same.
* config/nios2/nios2.opt: Same.
* config/nvptx/nvptx.opt: Same.
* config/pa/pa-hpux.opt: Same.
* config/pa/pa-hpux1010.opt: Same.
* config/pa/pa-hpux1111.opt: Same.
* config/pa/pa-hpux1131.opt: Same.
* config/pa/pa.opt: Same.
* config/pa/pa64-hpux.opt: Same.
* config/pdp11/pdp11.opt: Same.
* config/rl78/rl78.opt: Same.
* config/rs6000/476.opt: Same.
* config/rs6000/aix64.opt: Same.
* config/rs6000/darwin.opt: Same.
* config/rs6000/linux64.opt: Same.
* config/rs6000/rs6000.opt: Same.
* config/rs6000/sysv4.opt: Same.
* config/s390/s390.opt: Same.
* config/s390/tpf.opt: Same.
* config/sh/sh.opt: Same.
* config/sol2.opt: Same.
* config/sparc/long-double-switch.opt: Same.
* config/sparc/sparc.opt: Same.
* config/spu/spu.opt: Same.
* config/stormy16/stormy16.opt: Same.
* config/tilegx/tilegx.opt: Same.
* config/tilepro/tilepro.opt: Same.
* config/v850/v850.opt: Same.
* config/vax/vax.opt: Same.
* config/visium/visium.opt: Same.
* config/vms/vms.opt: Same.
* config/vxworks.opt: Same.
* config/xtensa/xtensa.opt: Same.
* fortran/lang.opt: Same.
gcc/testsuite/ChangeLog:
2015-10-21 Martin Sebor <mse...@redhat.com>
PR driver/68043
* gcc.misc-tests/help.exp: Adjust.
* lib/options.exp (check_for_options): Add detail to output.
On 10/15/2015 03:46 PM, Joseph Myers wrote:
On Wed, 14 Oct 2015, Martin Sebor wrote:
On 10/14/2015 01:40 PM, Joseph Myers wrote:
On Wed, 14 Oct 2015, Martin Sebor wrote:
IMO, printing the aliased option's help text makes using the output
easier for users who find the undocumented option first, in that
they don't then have to go look for the one that does have
documentation, so I left that part in place. If you or someone
feels strongly that it shouldn't be there I'll remove it.
Well, I think it might also encourage people to use the aliases, when for
the most part we'd rather people used the canonical names (and so made it
easier e.g. to search for other uses of the same option).
This seems like a sensible argument. I think we're more likely
to achieve this goal if we're explicit about it than if we just
make it difficult for users to find what they're looking for.
To that end, the attached patch replaces the help text with
a suggestion to use the aliased option instead. For example,
for the --assert option, it prints:
--assert Same as -A. Use the latter option instead.
The code isn't using _() around use_other_msg, meaning translations
wouldn't be used. I think it would be more helpful for translators if you
just put "Same as %s. Use the latter option instead." in a single string,
surrounded by _(), to give them the maximum context for translation.
I'm concerned about whether the code relating to adding '.' is genuinely
universal to all languages. I think it would be better to make the
English messages in the .opt files consistent regarding English
punctuation, and let translators determine what punctuation to use
consistently in their translations, rather than forcing '.'.
<https://en.wikipedia.org/wiki/Full_stop#Full_stops_in_other_scripts>
lists a range of other punctuation marks used in some languages for this
purpose.
This in turn implies adding '.' for documented options with aliases is
also problematic. Most simply, avoid having documentation for aliases in
.opt files and handle all aliases the same whether or not such
documentation is there. Otherwise, a detailed comment for translators
would be needed on the line above _("%s Same as %s.") to explain what
each %s is and that translators should include appropriate punctuation in
translations of this message if not in translations of option help texts.
I also added text indicating when using an option is diagnosed.
This results in, for example:
-falt-external-templates No longer supported. Uses of this
option are diagnosed.
Again, you need to avoid inserting '.'; ensure that translators have the
information needed to insert their own punctuation if needed; and ensure
that use_diagnosed_msg does actually get translated (i.e. surrounded by
_(), or included directly in a so-surrounded string), not just extracted
to the .pot file.
diff --git a/gcc/gcc.c b/gcc/gcc.c
index 7f5a36e..bbc9b23 100644
--- a/gcc/gcc.c
+++ b/gcc/gcc.c
@@ -3366,63 +3366,63 @@ display_help (void)
printf (_("Usage: %s [options] file...\n"), progname);
fputs (_("Options:\n"), stdout);
- fputs (_(" -pass-exit-codes Exit with highest error code from a phase\n"), stdout);
- fputs (_(" --help Display this information\n"), stdout);
- fputs (_(" --target-help Display target specific command line options\n"), stdout);
- fputs (_(" --help={common|optimizers|params|target|warnings|[^]{joined|separate|undocumented}}[,...]\n"), stdout);
- fputs (_(" Display specific types of command line options\n"), stdout);
+ fputs (_(" -pass-exit-codes Exit with highest error code from a phase.\n"), stdout);
+ fputs (_(" --help Display this information.\n"), stdout);
+ fputs (_(" --target-help Display target specific command line options.\n"), stdout);
+ fputs (_(" --help={common|optimizers|params|target|warnings|[^]{joined|separate|undocumented}}[,...].\n"), stdout);
+ fputs (_(" Display specific types of command line options.\n"), stdout);
if (! verbose_flag)
- fputs (_(" (Use '-v --help' to display command line options of sub-processes)\n"), stdout);
- fputs (_(" --version Display compiler version information\n"), stdout);
- fputs (_(" -dumpspecs Display all of the built in spec strings\n"), stdout);
- fputs (_(" -dumpversion Display the version of the compiler\n"), stdout);
- fputs (_(" -dumpmachine Display the compiler's target processor\n"), stdout);
- fputs (_(" -print-search-dirs Display the directories in the compiler's search path\n"), stdout);
- fputs (_(" -print-libgcc-file-name Display the name of the compiler's companion library\n"), stdout);
- fputs (_(" -print-file-name=<lib> Display the full path to library <lib>\n"), stdout);
- fputs (_(" -print-prog-name=<prog> Display the full path to compiler component <prog>\n"), stdout);
+ fputs (_(" (Use '-v --help' to display command line options of sub-processes).\n"), stdout);
+ fputs (_(" --version Display compiler version information.\n"), stdout);
+ fputs (_(" -dumpspecs Display all of the built in spec strings.\n"), stdout);
+ fputs (_(" -dumpversion Display the version of the compiler.\n"), stdout);
+ fputs (_(" -dumpmachine Display the compiler's target processor.\n"), stdout);
+ fputs (_(" -print-search-dirs Display the directories in the compiler's search path.\n"), stdout);
+ fputs (_(" -print-libgcc-file-name Display the name of the compiler's companion library.\n"), stdout);
+ fputs (_(" -print-file-name=<lib> Display the full path to library <lib>.\n"), stdout);
+ fputs (_(" -print-prog-name=<prog> Display the full path to compiler component <prog>.\n"), stdout);
fputs (_("\
-print-multiarch Display the target's normalized GNU triplet, used as\n\
- a component in the library path\n"), stdout);
- fputs (_(" -print-multi-directory Display the root directory for versions of libgcc\n"), stdout);
+ a component in the library path.\n"), stdout);
+ fputs (_(" -print-multi-directory Display the root directory for versions of libgcc.\n"), stdout);
fputs (_("\
-print-multi-lib Display the mapping between command line options and\n\
- multiple library search directories\n"), stdout);
- fputs (_(" -print-multi-os-directory Display the relative path to OS libraries\n"), stdout);
- fputs (_(" -print-sysroot Display the target libraries directory\n"), stdout);
- fputs (_(" -print-sysroot-headers-suffix Display the sysroot suffix used to find headers\n"), stdout);
- fputs (_(" -Wa,<options> Pass comma-separated <options> on to the assembler\n"), stdout);
- fputs (_(" -Wp,<options> Pass comma-separated <options> on to the preprocessor\n"), stdout);
- fputs (_(" -Wl,<options> Pass comma-separated <options> on to the linker\n"), stdout);
- fputs (_(" -Xassembler <arg> Pass <arg> on to the assembler\n"), stdout);
- fputs (_(" -Xpreprocessor <arg> Pass <arg> on to the preprocessor\n"), stdout);
- fputs (_(" -Xlinker <arg> Pass <arg> on to the linker\n"), stdout);
- fputs (_(" -save-temps Do not delete intermediate files\n"), stdout);
- fputs (_(" -save-temps=<arg> Do not delete intermediate files\n"), stdout);
+ multiple library search directories.\n"), stdout);
+ fputs (_(" -print-multi-os-directory Display the relative path to OS libraries.\n"), stdout);
+ fputs (_(" -print-sysroot Display the target libraries directory.\n"), stdout);
+ fputs (_(" -print-sysroot-headers-suffix Display the sysroot suffix used to find headers.\n"), stdout);
+ fputs (_(" -Wa,<options> Pass comma-separated <options> on to the assembler.\n"), stdout);
+ fputs (_(" -Wp,<options> Pass comma-separated <options> on to the preprocessor.\n"), stdout);
+ fputs (_(" -Wl,<options> Pass comma-separated <options> on to the linker.\n"), stdout);
+ fputs (_(" -Xassembler <arg> Pass <arg> on to the assembler.\n"), stdout);
+ fputs (_(" -Xpreprocessor <arg> Pass <arg> on to the preprocessor.\n"), stdout);
+ fputs (_(" -Xlinker <arg> Pass <arg> on to the linker.\n"), stdout);
+ fputs (_(" -save-temps Do not delete intermediate files.\n"), stdout);
+ fputs (_(" -save-temps=<arg> Do not delete intermediate files.\n"), stdout);
fputs (_("\
-no-canonical-prefixes Do not canonicalize paths when building relative\n\
- prefixes to other gcc components\n"), stdout);
- fputs (_(" -pipe Use pipes rather than intermediate files\n"), stdout);
- fputs (_(" -time Time the execution of each subprocess\n"), stdout);
- fputs (_(" -specs=<file> Override built-in specs with the contents of <file>\n"), stdout);
- fputs (_(" -std=<standard> Assume that the input sources are for <standard>\n"), stdout);
+ prefixes to other gcc components.\n"), stdout);
+ fputs (_(" -pipe Use pipes rather than intermediate files.\n"), stdout);
+ fputs (_(" -time Time the execution of each subprocess.\n"), stdout);
+ fputs (_(" -specs=<file> Override built-in specs with the contents of <file>.\n"), stdout);
+ fputs (_(" -std=<standard> Assume that the input sources are for <standard>.\n"), stdout);
fputs (_("\
--sysroot=<directory> Use <directory> as the root directory for headers\n\
- and libraries\n"), stdout);
- fputs (_(" -B <directory> Add <directory> to the compiler's search paths\n"), stdout);
- fputs (_(" -v Display the programs invoked by the compiler\n"), stdout);
- fputs (_(" -### Like -v but options quoted and commands not executed\n"), stdout);
- fputs (_(" -E Preprocess only; do not compile, assemble or link\n"), stdout);
- fputs (_(" -S Compile only; do not assemble or link\n"), stdout);
- fputs (_(" -c Compile and assemble, but do not link\n"), stdout);
- fputs (_(" -o <file> Place the output into <file>\n"), stdout);
- fputs (_(" -pie Create a position independent executable\n"), stdout);
- fputs (_(" -shared Create a shared library\n"), stdout);
+ and libraries.\n"), stdout);
+ fputs (_(" -B <directory> Add <directory> to the compiler's search paths.\n"), stdout);
+ fputs (_(" -v Display the programs invoked by the compiler.\n"), stdout);
+ fputs (_(" -### Like -v but options quoted and commands not executed.\n"), stdout);
+ fputs (_(" -E Preprocess only; do not compile, assemble or link.\n"), stdout);
+ fputs (_(" -S Compile only; do not assemble or link.\n"), stdout);
+ fputs (_(" -c Compile and assemble, but do not link.\n"), stdout);
+ fputs (_(" -o <file> Place the output into <file>.\n"), stdout);
+ fputs (_(" -pie Create a position independent executable.\n"), stdout);
+ fputs (_(" -shared Create a shared library.\n"), stdout);
fputs (_("\
- -x <language> Specify the language of the following input files\n\
+ -x <language> Specify the language of the following input files.\n\
Permissible languages include: c c++ assembler none\n\
'none' means revert to the default behavior of\n\
- guessing the language based on the file's extension\n\
+ guessing the language based on the file's extension.\n\
"), stdout);
printf (_("\
diff --git a/gcc/opts.c b/gcc/opts.c
index 89b3e79..9d7cc5a 100644
--- a/gcc/opts.c
+++ b/gcc/opts.c
@@ -181,7 +181,8 @@ base_of_path (const char *path, const char **base_out)
}
/* What to print when a switch has no documentation. */
-static const char undocumented_msg[] = N_("This switch lacks documentation");
+static const char undocumented_msg[] = N_("This option lacks documentation.");
+static const char use_diagnosed_msg[] = N_("Uses of this option are diagnosed.");
typedef char *char_p; /* For DEF_VEC_P. */
@@ -1012,7 +1013,7 @@ print_filtered_help (unsigned int include_flags,
const char *help;
bool found = false;
bool displayed = false;
- char new_help[128];
+ char new_help[256];
if (include_flags == CL_PARAMS)
{
@@ -1088,9 +1089,48 @@ print_filtered_help (unsigned int include_flags,
{
if (exclude_flags & CL_UNDOCUMENTED)
continue;
+
help = undocumented_msg;
}
+ if (option->alias_target < N_OPTS
+ && cl_options [option->alias_target].help)
+ {
+ if (help == undocumented_msg)
+ {
+ /* For undocumented options that are aliases for other options
+ that are documented, point the reader to the other option in
+ preference of the former. */
+ snprintf (new_help, sizeof new_help,
+ _("Same as %s. Use the latter option instead."),
+ cl_options [option->alias_target].opt_text);
+ }
+ else
+ {
+ /* For documented options with aliases, mention the aliased
+ option's name for reference. */
+ snprintf (new_help, sizeof new_help,
+ _("%s Same as %s."),
+ help, cl_options [option->alias_target].opt_text);
+ }
+
+ help = new_help;
+ }
+
+ if (option->warn_message)
+ {
+ /* Mention that the use of the option will trigger a warning. */
+ if (help == new_help)
+ snprintf (new_help + strlen (new_help),
+ sizeof new_help - strlen (new_help),
+ " %s", _(use_diagnosed_msg));
+ else
+ snprintf (new_help, sizeof new_help,
+ "%s %s", help, _(use_diagnosed_msg));
+
+ help = new_help;
+ }
+
/* Get the translation. */
help = _(help);
@@ -1180,7 +1220,7 @@ print_filtered_help (unsigned int include_flags,
options supported by a specific front end. */
for (i = 0; (1U << i) < CL_LANG_ALL; i ++)
if ((1U << i) & langs)
- printf (_(" None found. Use --help=%s to show *all* the options supported by the %s front-end\n"),
+ printf (_(" None found. Use --help=%s to show *all* the options supported by the %s front-end.\n"),
lang_names[i], lang_names[i]);
}
diff --git a/gcc/testsuite/gcc.misc-tests/help.exp b/gcc/testsuite/gcc.misc-tests/help.exp
index e913919..be36c85 100644
--- a/gcc/testsuite/gcc.misc-tests/help.exp
+++ b/gcc/testsuite/gcc.misc-tests/help.exp
@@ -31,7 +31,7 @@ gcc_parallel_test_enable 0
# Document --version. Ideally, there should be no undocumented switches
# in --help.
-check_for_options c "--help" "--version" "This switch lacks documentation" ""
+check_for_options c "--help" "--version" "This option lacks documentation" ""
# Output from different subprocesses should not be intermingled
# (we check for some patterns that could be seen with a missing
@@ -43,7 +43,7 @@ check_for_options c "-v --help" "" {
} ""
# There are still undocumented switches in -v --help.
-check_for_options c "-v --help" "" "This switch lacks documentation" "xfail"
+check_for_options c "-v --help" "" "This option lacks documentation" "xfail"
# Check whether multiline conversion in optc-gen is broken.
check_for_options c "-v --help" "" {are likely to\n -std} ""
@@ -54,10 +54,10 @@ check_for_options c "--help=params" "maximum number of" "-Wunsafe-loop-optimizat
check_for_options c "--help=C" "-ansi" "-gnatO" ""
check_for_options c {--help=C++} {-std=c\+\+} "-gnatO" ""
check_for_options c "--help=common" "-dumpbase" "-gnatO" ""
-check_for_options c "--help=undocumented" "This switch lacks documentation" "" ""
+check_for_options c "--help=undocumented" "This option lacks documentation" "" ""
# Undocumented flags are not yet consistently marked as such.
-check_for_options c "--help=^undocumented" "-Wall" "This switch lacks documentation" "xfail"
+check_for_options c "--help=^undocumented" "-Wall" "This option lacks documentation" "xfail"
# Try some --help=* examples from the manual.
check_for_options c "--help=target,undocumented" "" "" ""
@@ -78,14 +78,27 @@ maximum number of
} "" ""
# Ensure PR 37805 is fixed.
-check_for_options c "--help=joined" "Wformat=" "-fstrict-prototype" ""
-check_for_options c "--help=separate" "-MF" "-fstrict-prototype" ""
-check_for_options c "--help=warnings,joined" "Wformat=" "Wtrigraphs" ""
-check_for_options c "--help=warnings,^joined" "Wtrigraphs" "Wformat=" ""
-check_for_options c "--help=joined,separate" "-I" "" ""
-check_for_options c "--help=^joined,separate" "--param " "" ""
-check_for_options c "--help=joined,^separate" "--help=" "" ""
+# Specify patterns (arguments 3 and later) that match option names
+# at the beginning of the line and not when they are referenced by
+# some other options later on.
+# The (?w) Tcl embedded option tells the Tcl regexp parser to treat
+# the '^' character as an anchor.
+check_for_options c "--help=joined" \
+ "(?w)^ *-Wformat=" "(?w)^ *-fstrict-prototype" ""
+check_for_options c "--help=separate" \
+ "(?w)^ *-MF" "(?w)^ *-fstrict-prototype" ""
+check_for_options c "--help=warnings,joined" \
+ "(?w)^ *-Wformat=" "(?w)^ *-Wtrigraphs" ""
+check_for_options c "--help=warnings,^joined" \
+ "(?w)^ *-Wtrigraphs" "(?w)^ *-Wformat=" ""
+check_for_options c "--help=joined,separate" \
+ "(?w)^ *-I" "" ""
+check_for_options c "--help=^joined,separate" \
+ "(?w)^ *--param " "" ""
+check_for_options c "--help=joined,^separate" \
+ "(?w)^ *--help=" "" ""
check_for_options c "--help=joined,undocumented" "" "" ""
+
# Listing only excludes gives empty results.
check_for_options c "--help=^joined,^separate" "" "" ""
diff --git a/gcc/testsuite/lib/options.exp b/gcc/testsuite/lib/options.exp
index dcce433..d1dacda 100644
--- a/gcc/testsuite/lib/options.exp
+++ b/gcc/testsuite/lib/options.exp
@@ -47,28 +47,31 @@ proc check_for_options {language gcc_options compiler_patterns compiler_non_patt
set gcc_output [gcc_target_compile $filename.c $filename.x executable $gcc_options]
remote_file build delete $filename.c $filename.x $filename.gcno
+ # Verify that COMPILER_PATTERRNS appear in gcc output.
foreach pattern [split $compiler_patterns "\n"] {
if {$pattern != ""} {
if {[regexp -- "$pattern" $gcc_output]} {
pass "$test $pattern"
} else {
if {$expected_failure != ""} {
- xfail "$test $pattern"
+ xfail "$test \"$pattern\" present in output"
} else {
- fail "$test $pattern"
+ fail "$test \"$pattern\" present in output"
}
}
}
}
+
+ # Verify that COMPILER_NON_PATTERRNS do not appear in gcc output.
foreach pattern [split $compiler_non_patterns "\n"] {
if {$pattern != ""} {
if {![regexp -- "$pattern" $gcc_output]} {
pass "$test $pattern"
} else {
if {$expected_failure != ""} {
- xfail "$test $pattern"
+ xfail "$test \"$pattern\" absent from output"
} else {
- fail "$test $pattern"
+ fail "$test \"$pattern\" absent from output"
}
}
}
