Document -std= values for different languages

[dim]

Summary

After a remark on a FreeBSD mailing list that the clang man page did
not have any list of possible values for the -std= flag, I have now
attempted to exhaustively list those, for each available language.

This also includes a number of deprecated aliases, but since some of
those are still used, we might as well include them. They are marked
with '(deprecated)`.

I also documented the default standard for each language, if there was
more than one choice.

Suggestions on how to make the values and descriptions line up more
nicely in RST are welcome.

[mgorny]

To be honest, I find those '(deprecated)' confusing — the user may mistakenly assume that it's about all values rather than the alias.

docs/CommandGuide/clang.rst

105

s/options/values/ I think.

[dim]

In D45406#1060768, @mgorny wrote:

To be honest, I find those '(deprecated)' confusing — the user may mistakenly assume that it's about all values rather than the alias.

Sure, what would you suggest as an alternative? Not listing them, listing them separately, using some sort of "*" suffix, or anything else?

[rsmith]

In D45406#1060773, @dim wrote:

In D45406#1060768, @mgorny wrote:

To be honest, I find those '(deprecated)' confusing — the user may mistakenly assume that it's about all values rather than the alias.

Sure, what would you suggest as an alternative? Not listing them, listing them separately, using some sort of "*" suffix, or anything else?

I think not listing them is probably best. We don't want anyone to specify them, after all.

[dim]

• Use "values" instead of "options"
• Remove deprecated standard values

[mgorny]

Well, my idea was to list the standards one per line (like on GCC manpage), and then the '(deprecated)' comments would probably stand out enough to apply to a single line. Also, FWICS the gcc manpage simply lists which aliases are deprecated in the description text. But skipping them entirely also works for me.

[dim]

In D45406#1060914, @mgorny wrote:

Well, my idea was to list the standards one per line (like on GCC manpage), and then the '(deprecated)' comments would probably stand out enough to apply to a single line. Also, FWICS the gcc manpage simply lists which aliases are deprecated in the description text. But skipping them entirely also works for me.

Right, I see what you mean (as per https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html#index-std-1), I'm not completely sure how to force a line break in RST with itemized lists, though.

[mgorny]

I think you'd want a definition list instead then. But I haven't tested if they can be nested inside option lists.

[dim]

Attempt to put the standard values in to definition lists. In the HTML
output, this looks fairly nice, but as a man page, it seems a bit
strange, for example:

-std=<standard>
       Specify the language standard to compile for.

       Supported values for the C language are:
          c89
          c90
          iso9899:1990

             ISO C 1990
          iso9899:199409

             ISO C 1990 with amendment 1
          gnu89
          gnu90

             ISO C 1990 with GNU extensions
          c99
          iso9899:1999

             ISO C 1999
          gnu99

             ISO C 1999 with GNU extensions
          c11
          iso9899:2011

             ISO C 2011
          gnu11

             ISO C 2011 with GNU extensions
          c17
          iso9899:2017

             ISO C 2017
          gnu17

             ISO C 2017 with GNU extensions

       The default C language standard is gnu11, except on PS4, where
       it is gnu99.

[dim]

So, does this look good enough to commit?

[dim]

Ping

[rsmith]

Looks good to me, thank you

docs/CommandGuide/clang.rst

 
 Language Selection and Mode Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. option:: -x <language>
 
  Treat subsequent input files as having type language.
 
-.. option:: -std=<language>
+.. option:: -std=<standard>
 
  Specify the language standard to compile for.
 
+ Supported values for the C language are:
+
+ - ``c89``, ``c90`` or ``iso9899:1990``: ISO C 1990
+ - ``iso9899:199409``: ISO C 1990 with amendment 1
+ - ``gnu89`` or ``gnu90``: ISO C 1990 with GNU extensions
+ - ``c99`` or ``iso9899:1999``: ISO C 1999
+ - ``gnu99``: ISO C 1999 with GNU extensions
+ - ``c11`` or ``iso9899:2011``: ISO C 2011
+ - ``gnu11``: ISO C 2011 with GNU extensions
+ - ``c17`` or ``iso9899:2017``: ISO C 2017
+ - ``gnu17``: ISO C 2017 with GNU extensions
+
+ The default C language standard is ``gnu11``, except on PS4, where it is
+ ``gnu99``.
+
+ Supported values for the C++ language are:
+
+ - ``c++98`` or ``c++03``: ISO C++ 1998 with amendments
+ - ``gnu++98`` or ``gnu++03``: ISO C++ 1998 with amendments and GNU extensions
+ - ``c++11``: ISO C++ 2011 with amendments
+ - ``gnu++11``: ISO C++ 2011 with amendments and
+   GNU extensions
+ - ``c++14``: ISO C++ 2014 with amendments
+ - ``gnu++14``: ISO C++ 2014 with amendments and
+   GNU extensions
+ - ``c++17``: ISO C++ 2017 with amendments
+ - ``gnu++17``: ISO C++ 2017 with amendments and
+   GNU extensions
+ - ``c++2a``: Working draft for ISO C++ 2020
+ - ``gnu++2a``: Working draft for ISO C++ 2020 with GNU extensions
+
+ The default C++ language standard is ``gnu++14``.
+
+ Supported values for the OpenCL language are:
+
+ - ``cl1.0``: OpenCL 1.0
+ - ``cl1.1``: OpenCL 1.1
+ - ``cl1.2``: OpenCL 1.2
+ - ``cl2.0``: OpenCL 2.0
+
+ The default OpenCL language standard is ``cl1.0``.
+
+ Supported values for the CUDA language are:
+
+ - ``cuda``: NVIDIA CUDA(tm)
+
 .. option:: -stdlib=<library>
 
  Specify the C++ standard library to use; supported options are libstdc++ and
  libc++. If not specified, platform default will be used.
 
 .. option:: -rtlib=<library>
 
  Specify the compiler runtime library to use; supported options are libgcc and