options: Clarifications around option definition records' help texts (was: make conflicting help text an error)
Commit Message
Hi!
On 2012-05-13T11:03:36+0000, "Joseph S. Myers" <joseph@codesourcery.com> wrote:
> On Sun, 13 May 2012, Manuel Lpez-Ibez wrote:
>> [an option is duplicated somewhere else]
>>
>> Only 2 options in Ada trigger this warning, and their help text has no
>> effect, since it gest overridden by the ones in c.opt. Fixing this
>> properly would require language-specific namespace, so two options
>> with the same name in different languages can have completely
>> different help text (and Init() and other flags). Not something I am
>> planning to work on in the future.
;-)
> I don't think we want to support different help strings for
> different languages; if an option is supported for multiple languages, we
> should have a generic description of that option that is correct for all
> of them.
To not just bury that in the email archives: OK to push the attached
"options: Clarifications around option definition records' help texts"?
Grüße
Thomas
-----------------
Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955
Comments
On Wed, 30 Mar 2022, Thomas Schwinge wrote:
> > I don't think we want to support different help strings for
> > different languages; if an option is supported for multiple languages, we
> > should have a generic description of that option that is correct for all
> > of them.
>
> To not just bury that in the email archives: OK to push the attached
> "options: Clarifications around option definition records' help texts"?
OK.
From d9cc0118898a7abdd1b7de515f0cc02b752aebec Mon Sep 17 00:00:00 2001
From: Thomas Schwinge <thomas@codesourcery.com>
Date: Wed, 30 Mar 2022 23:00:28 +0200
Subject: [PATCH] options: Clarifications around option definition records'
help texts
gcc/
* doc/options.texi (Option file format): Clarifications around
option definition records' help texts.
---
gcc/doc/options.texi | 11 +++++++++++
1 file changed, 11 insertions(+)
@@ -160,6 +160,17 @@ used instead of the option's name and the text to the right of the
tab forms the help text. This allows you to elaborate on what type
of argument the option takes.
+There is no support for different help texts for different languages.
+If an option is supported for multiple languages, use a generic
+description that is correct for all of them.
+
+If an option has multiple option definition records (in different
+front ends' @file{*.opt} files, and/or @file{gcc/common.opt}, for
+example), convention is to not duplicate the help text for each of
+them, but instead put a comment like @code{; documented in common.opt}
+in place of the help text for all but one of the multiple option
+definition records.
+
@item
A target mask record. These records have one field of the form
@samp{Mask(@var{x})}. The options-processing script will automatically
--
2.25.1