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.
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.
Finally, since I suspect that most users refer to the manual for
guidance on the use of options rather than to gcc's output, I've
surveyed all the options that are undocumented in the output to
see which ones are documented in the manual and how much effort
it would be to update it with similar suggestions. I found only
the following options mentioned:
--output
--verbose
-pedantic
-mcpu=
-mfused-madd
I'll see about preparing a separate patch to suggest using the
canonical forms in preference to these.
Martin
2015-10-14 Martin Sebor <mse...@redhat.com>
* options.c (undocumented_msg): Change "switch" to "option" for
consistency with other uses.
(use_other_msg, use_diagnosed_msg): New globals.
(wrap_help): End last sentence in a period.
(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.
diff --git a/gcc/opts.c b/gcc/opts.c
index 2bbf653..eeaaa11 100644
--- a/gcc/opts.c
+++ b/gcc/opts.c
@@ -181,7 +181,9 @@ 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_other_msg[] = N_("Use the latter option instead.");
+static const char use_diagnosed_msg[] = N_("Uses of this option are diagnosed.");
typedef char *char_p; /* For DEF_VEC_P. */
@@ -960,9 +962,19 @@ wrap_help (const char *help,
{
unsigned int col_width = LEFT_COLUMN;
unsigned int remaining, room, len;
+ char *new_help = NULL;
remaining = strlen (help);
-
+ if (remaining && help [remaining - 1] != '.')
+ {
+ /* Help text in .opt files doesn't always end in a period. Make
+ it constistent by appending a period when it's missing. */
+ new_help = XNEWVEC (char, remaining + 2);
+ memcpy (new_help, help, remaining);
+ new_help [remaining++] = '.';
+ new_help [remaining] = '\0';
+ help = new_help;
+ }
do
{
room = columns - 3 - MAX (col_width, item_width);
@@ -995,6 +1007,9 @@ wrap_help (const char *help,
remaining -= len;
}
while (remaining);
+
+ /* Free the help text allocated by this function. */
+ XDELETEVEC (const_cast<char*>(new_help));
}
/* Print help for a specific front-end, etc. */
@@ -1010,7 +1025,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)
{
@@ -1086,9 +1101,55 @@ 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. %s"),
+ cl_options [option->alias_target].opt_text,
+ use_other_msg);
+ }
+ else
+ {
+ /* For documented options with aliases, mention the aliased
+ option's name for reference. */
+ const char *maybe_period =
+ *help && help [strlen (help) - 1] == '.' ? "" : ".";
+
+ snprintf (new_help, sizeof new_help,
+ _("%s%s Same as %s."),
+ help, maybe_period,
+ cl_options [option->alias_target].opt_text);
+ }
+
+ help = new_help;
+ }
+
+ if (option->warn_message)
+ {
+ const char *maybe_period =
+ *help && help [strlen (help) - 1] == '.' ? "" : ".";
+
+ if (help == new_help)
+ snprintf (new_help + strlen (new_help),
+ sizeof new_help - strlen (new_help),
+ "%s %s", maybe_period, use_diagnosed_msg);
+ else
+ snprintf (new_help, sizeof new_help,
+ "%s%s %s", help, maybe_period, use_diagnosed_msg);
+
+ help = new_help;
+ }
+
/* Get the translation. */
help = _(help);
