[gcc r12-7943] options: Clarifications around option definition records' help texts

[Thomas Schwinge]

https://gcc.gnu.org/g:58d78650da3c6e4830b8350f4e6cbe87dc893c9f

commit r12-7943-g58d78650da3c6e4830b8350f4e6cbe87dc893c9f
Author: Thomas Schwinge <thomas@codesourcery.com>
Date:   Wed Mar 30 23:00:28 2022 +0200

    options: Clarifications around option definition records' help texts
    
            gcc/
            * doc/options.texi (Option file format): Clarifications around
            option definition records' help texts.

Diff:
---
 gcc/doc/options.texi | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/gcc/doc/options.texi b/gcc/doc/options.texi
index 50674938e3d..17ba923890e 100644
--- a/gcc/doc/options.texi
+++ b/gcc/doc/options.texi
@@ -175,6 +175,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