options: Clarifications around option definition records' help texts (was: make conflicting help text an error)

[Thomas Schwinge <thomas@codesourcery.com>]

[-- Attachment #1: Type: text/plain, Size: 1258 bytes --]

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

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-options-Clarifications-around-option-definition-reco.patch --]
[-- Type: text/x-diff, Size: 1476 bytes --]

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(+)

diff --git a/gcc/doc/options.texi b/gcc/doc/options.texi
index d552b64d1f4..94dceaafbc5 100644
--- a/gcc/doc/options.texi
+++ b/gcc/doc/options.texi
@@ -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