Improve documentation of -std option for C++

This patch corrects the manual w.r.t the default -std mode for C++,
which changed from -std=gnu++98 to -std=gnu++14 in GCC 6. (I was
slightly surprised to find that -ansi didn't change to mean -std=c++14
at the same time, but now I think that makes sense.)

I added a cross-reference from the C++ options section to the C
options section, so people looking for documentation of -std for C++
know where to look.

I also documented C++14 and the Concepts TS in standards.texi and
removed the description of C++11 as experimental (I left C++14
described as experimental, as that's still what it says at
https://gcc.gnu.org/projects/cxx1y.html).

Rather then repeating the "to obtain all the diagnostics required by
the standard" text about -pedantic/-pedantic-errors I left it only on
the first paragraph and then added a new paragraph about it later. I
also clarified that the extensions enabled by -std=gnu++XX are
different to the ones enabled without -pedantic, taking the wording
from the previous @section about C Standards.

OK for trunk?

On 01/13/2016 06:28 AM, Jonathan Wakely wrote:
> This patch corrects the manual w.r.t the default -std mode for C++,
> which changed from -std=gnu++98 to -std=gnu++14 in GCC 6. (I was
> slightly surprised to find that -ansi didn't change to mean -std=c++14
> at the same time, but now I think that makes sense.)
>
> I added a cross-reference from the C++ options section to the C
> options section, so people looking for documentation of -std for C++
> know where to look.
>
> I also documented C++14 and the Concepts TS in standards.texi and
> removed the description of C++11 as experimental (I left C++14
> described as experimental, as that's still what it says at
> https://gcc.gnu.org/projects/cxx1y.html).
>
> Rather then repeating the "to obtain all the diagnostics required by
> the standard" text about -pedantic/-pedantic-errors I left it only on
> the first paragraph and then added a new paragraph about it later. I
> also clarified that the extensions enabled by -std=gnu++XX are
> different to the ones enabled without -pedantic, taking the wording
> from the previous @section about C Standards.
>
> OK for trunk?
>

Thanks for doing this.  I have a one big question not addressed by your 
patch, and few nit-picky tech-writerish comments.

The big question is: the existing text in standards.texi says that "GCC 
implements the majority of C++98 (@code{export} is a notable exception) 
and most of the changes in C++03."  Is it still the case that there are 
unimplemented language features from these older versions of the 
standard?  If so, is there a detailed list anywhere of what features are 
not supported, as there is for the C++11 feature status?

For the nit-picking:

> @@ -2128,6 +2128,9 @@ In this example, only @option{-fstrict-enums} is an option meant
>  only for C++ programs; you can use the other options with any
>  language supported by GCC@.
>
> +@xref{C Dialect Options,,Options Controlling C Dialect} for the description

Texinfo style is to put a comma (or other punctuation) after "@xref{}".

> +of @option{-std} and other options which are also relevant for C++ programs.

s/which/that/

> +
>  Here is a list of options that are @emph{only} for compiling C++ programs:
>
>  @table @gcctabopt

> @@ -188,25 +188,48 @@ warnings).
>  A revised ISO C++ standard was published in 2011 as ISO/IEC
>  14882:2011, and is referred to as C++11; before its publication it was
>  commonly referred to as C++0x.  C++11 contains several
> -changes to the C++ language, most of which have been implemented in an
> -experimental C++11 mode in GCC@.  For information
> -regarding the C++11 features available in the experimental C++11 mode,
> -see @uref{http://gcc.gnu.org/projects/@/cxx0x.html}. To select this
> -standard in GCC, use the option @option{-std=c++11}; to obtain all the
> -diagnostics required by the standard, you should also specify
> -@option{-pedantic} (or @option{-pedantic-errors} if you want them to
> -be errors rather than warnings).
> +changes to the C++ language, all of which have been implemented in GCC@.
> +For information regarding the C++11 features available in C++11 mode,

You could make that a lot less verbose by just saying "For details,".

> +see @uref{https://gcc.gnu.org/projects/@/cxx0x.html}. To select this
> +standard in GCC, use the option @option{-std=c++11}.
> +
> +Another revised ISO C++ standard was published in 2014 as ISO/IEC
> +14882:2014, and is referred to as C++14; before its publication it was
> +sometimes referred to as C++1y.  C++14 contains several further
> +changes to the C++ language, all of which have been implemented in GCC@.
> +For information
> +regarding the C++14 features available in the experimental C++14 mode,

Ditto here.

> +see @uref{https://gcc.gnu.org/projects/@/cxx1y.html}. To select this
> +standard in GCC, use the option @option{-std=c++14}.
> +
> +GCC also supports the C++ Concepts Technical Specification,
> +ISO/IEC TS 19217:2015, which allows constraints to be defined for templates,
> +allowing template arguments to be checked and for templates to be
> +overloaded or specialized based on the constraints. Support for C++ Concepts
> +is included in an experimental C++1z mode that corresponds to the next
> +revision of the ISO C++ standard, expected to be published in 2017. To enable
> +C++1z support in GCC, use the option @option{-std=c++17} or
> +@option{-std=c++1z}.
>
>  More information about the C++ standards is available on the ISO C++
>  committee's web site at @uref{http://www.open-std.org/@/jtc1/@/sc22/@/wg21/}.
>
> -By default, GCC provides some extensions to the C++ language; @xref{C++
> +To obtain all the diagnostics required by any of the standard versions
> +described above you should specify @option{-pedantic}
> +or @option{-pedantic-errors}, otherwise GCC will allow some non-ISO C++
> +features as extensions. @xref{Warning Options}.
> +
> +By default, GCC also provides some additional extensions to the C++ language
> +that on rare occasions conflict with the C++ standard.  @xref{C++
>  Dialect Options,Options Controlling C++ Dialect}.  Use of the
> -@option{-std} option listed above will disable these extensions.  You
> -may also select an extended version of the C++ language explicitly with
> -@option{-std=gnu++98} (for C++98 with GNU extensions) or
> -@option{-std=gnu++11} (for C++11 with GNU extensions).  The default, if
> -no C++ language dialect options are given, is @option{-std=gnu++98}.
> +@option{-std} options listed above will disable these extensions where they

s/will disable/disables/
(assuming this is an already-implemented feature and not something that 
will be added at some future date....)

> +they conflict with the C++ standard version selected.  You may also
> +select an extended version of the C++ language explicitly with
> +@option{-std=gnu++98} (for C++98 with GNU extensions), or
> +@option{-std=gnu++11} (for C++11 with GNU extensions), or
> +@option{-std=gnu++14} (for C++14 with GNU extensions), or
> +@option{-std=gnu++1z} (for C++1z with GNU extensions).  The default, if
> +no C++ language dialect options are given, is @option{-std=gnu++14}.
>
>  @section Objective-C and Objective-C++ Languages
>  @cindex Objective-C

-Sandra

On 13/01/16 09:53 -0700, Sandra Loosemore wrote:
>On 01/13/2016 06:28 AM, Jonathan Wakely wrote:
>>This patch corrects the manual w.r.t the default -std mode for C++,
>>which changed from -std=gnu++98 to -std=gnu++14 in GCC 6. (I was
>>slightly surprised to find that -ansi didn't change to mean -std=c++14
>>at the same time, but now I think that makes sense.)
>>
>>I added a cross-reference from the C++ options section to the C
>>options section, so people looking for documentation of -std for C++
>>know where to look.
>>
>>I also documented C++14 and the Concepts TS in standards.texi and
>>removed the description of C++11 as experimental (I left C++14
>>described as experimental, as that's still what it says at
>>https://gcc.gnu.org/projects/cxx1y.html).
>>
>>Rather then repeating the "to obtain all the diagnostics required by
>>the standard" text about -pedantic/-pedantic-errors I left it only on
>>the first paragraph and then added a new paragraph about it later. I
>>also clarified that the extensions enabled by -std=gnu++XX are
>>different to the ones enabled without -pedantic, taking the wording
>>from the previous @section about C Standards.
>>
>>OK for trunk?
>>
>
>Thanks for doing this.  I have a one big question not addressed by 
>your patch, and few nit-picky tech-writerish comments.
>
>The big question is: the existing text in standards.texi says that 
>"GCC implements the majority of C++98 (@code{export} is a notable 
>exception) and most of the changes in C++03."  Is it still the case 
>that there are unimplemented language features from these older 
>versions of the standard?  If so, is there a detailed list anywhere of 
>what features are not supported, as there is for the C++11 feature 
>status?

The 'export' feature is definitely still not implemented, and never
will be.

The only other missing C++03 feature I can think of is
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=2316

Jason?


>For the nit-picking:
>
>>@@ -2128,6 +2128,9 @@ In this example, only @option{-fstrict-enums} is an option meant
>> only for C++ programs; you can use the other options with any
>> language supported by GCC@.
>>
>>+@xref{C Dialect Options,,Options Controlling C Dialect} for the description
>
>Texinfo style is to put a comma (or other punctuation) after "@xref{}".

OK. I originally had "For the description of -std @xref{...}" but the
"See" that @xref inserts is capitalized, so I moved it to the start of
the sentence.

How about:

Some options for compiling C programs, such as @option{-std}, are also
relevant for C++ programs.
@xref{C Dialect Options,,Options Controlling C Dialect}.

?

>>+of @option{-std} and other options which are also relevant for C++ programs.
>
>s/which/that/
>
>>+
>> Here is a list of options that are @emph{only} for compiling C++ programs:
>>
>> @table @gcctabopt
>
>>@@ -188,25 +188,48 @@ warnings).
>> A revised ISO C++ standard was published in 2011 as ISO/IEC
>> 14882:2011, and is referred to as C++11; before its publication it was
>> commonly referred to as C++0x.  C++11 contains several
>>-changes to the C++ language, most of which have been implemented in an
>>-experimental C++11 mode in GCC@.  For information
>>-regarding the C++11 features available in the experimental C++11 mode,
>>-see @uref{http://gcc.gnu.org/projects/@/cxx0x.html}. To select this
>>-standard in GCC, use the option @option{-std=c++11}; to obtain all the
>>-diagnostics required by the standard, you should also specify
>>-@option{-pedantic} (or @option{-pedantic-errors} if you want them to
>>-be errors rather than warnings).
>>+changes to the C++ language, all of which have been implemented in GCC@.
>>+For information regarding the C++11 features available in C++11 mode,
>
>You could make that a lot less verbose by just saying "For details,".
>
>>+see @uref{https://gcc.gnu.org/projects/@/cxx0x.html}. To select this
>>+standard in GCC, use the option @option{-std=c++11}.
>>+
>>+Another revised ISO C++ standard was published in 2014 as ISO/IEC
>>+14882:2014, and is referred to as C++14; before its publication it was
>>+sometimes referred to as C++1y.  C++14 contains several further
>>+changes to the C++ language, all of which have been implemented in GCC@.
>>+For information
>>+regarding the C++14 features available in the experimental C++14 mode,
>
>Ditto here.

Good idea. It was overly verbose when it appeared once, even more so
now I've duplicated that text.

>>+see @uref{https://gcc.gnu.org/projects/@/cxx1y.html}. To select this
>>+standard in GCC, use the option @option{-std=c++14}.
>>+
>>+GCC also supports the C++ Concepts Technical Specification,
>>+ISO/IEC TS 19217:2015, which allows constraints to be defined for templates,
>>+allowing template arguments to be checked and for templates to be
>>+overloaded or specialized based on the constraints. Support for C++ Concepts
>>+is included in an experimental C++1z mode that corresponds to the next
>>+revision of the ISO C++ standard, expected to be published in 2017. To enable
>>+C++1z support in GCC, use the option @option{-std=c++17} or
>>+@option{-std=c++1z}.
>>
>> More information about the C++ standards is available on the ISO C++
>> committee's web site at @uref{http://www.open-std.org/@/jtc1/@/sc22/@/wg21/}.
>>
>>-By default, GCC provides some extensions to the C++ language; @xref{C++
>>+To obtain all the diagnostics required by any of the standard versions
>>+described above you should specify @option{-pedantic}
>>+or @option{-pedantic-errors}, otherwise GCC will allow some non-ISO C++
>>+features as extensions. @xref{Warning Options}.
>>+
>>+By default, GCC also provides some additional extensions to the C++ language
>>+that on rare occasions conflict with the C++ standard.  @xref{C++
>> Dialect Options,Options Controlling C++ Dialect}.  Use of the
>>-@option{-std} option listed above will disable these extensions.  You
>>-may also select an extended version of the C++ language explicitly with
>>-@option{-std=gnu++98} (for C++98 with GNU extensions) or
>>-@option{-std=gnu++11} (for C++11 with GNU extensions).  The default, if
>>-no C++ language dialect options are given, is @option{-std=gnu++98}.
>>+@option{-std} options listed above will disable these extensions where they
>
>s/will disable/disables/
>(assuming this is an already-implemented feature and not something 
>that will be added at some future date....)

Agreed. That was copied from existing text in the previous section,
should I make the same change there?

On 01/13/2016 12:25 PM, Jonathan Wakely wrote:
> On 13/01/16 09:53 -0700, Sandra Loosemore wrote:
>> [snip]
>> Thanks for doing this.  I have a one big question not addressed by
>> your patch, and few nit-picky tech-writerish comments.
>>
>> The big question is: the existing text in standards.texi says that
>> "GCC implements the majority of C++98 (@code{export} is a notable
>> exception) and most of the changes in C++03."  Is it still the case
>> that there are unimplemented language features from these older
>> versions of the standard?  If so, is there a detailed list anywhere of
>> what features are not supported, as there is for the C++11 feature
>> status?
>
> The 'export' feature is definitely still not implemented, and never
> will be.
>
> The only other missing C++03 feature I can think of is
> https://gcc.gnu.org/bugzilla/show_bug.cgi?id=2316
>
> Jason?

Hmmm, it seems like we ought to have a complete list of known 
unimplemented features, but if there's nothing to link to here at the 
present time, then don't hold up the rest of the patch for that reason.

> How about:
>
> Some options for compiling C programs, such as @option{-std}, are also
> relevant for C++ programs.
> @xref{C Dialect Options,,Options Controlling C Dialect}.
>
> ?

Yes, that's fine.

>> s/will disable/disables/
>> (assuming this is an already-implemented feature and not something
>> that will be added at some future date....)
>
> Agreed. That was copied from existing text in the previous section,
> should I make the same change there?

Please.  Eventually I will try to get around to making a copy-editing 
pass through this chapter myself, but meanwhile I think fixing docs to 
use the present tense to describe the current behavior of GCC falls 
under the "obvious fix" rule.

The patch is OK with those changes.

-Sandra

On 13/01/16 12:54 -0700, Sandra Loosemore wrote:
>On 01/13/2016 12:25 PM, Jonathan Wakely wrote:
>>On 13/01/16 09:53 -0700, Sandra Loosemore wrote:
>>>[snip]
>>>Thanks for doing this.  I have a one big question not addressed by
>>>your patch, and few nit-picky tech-writerish comments.
>>>
>>>The big question is: the existing text in standards.texi says that
>>>"GCC implements the majority of C++98 (@code{export} is a notable
>>>exception) and most of the changes in C++03."  Is it still the case
>>>that there are unimplemented language features from these older
>>>versions of the standard?  If so, is there a detailed list anywhere of
>>>what features are not supported, as there is for the C++11 feature
>>>status?
>>
>>The 'export' feature is definitely still not implemented, and never
>>will be.
>>
>>The only other missing C++03 feature I can think of is
>>https://gcc.gnu.org/bugzilla/show_bug.cgi?id=2316
>>
>>Jason?
>
>Hmmm, it seems like we ought to have a complete list of known 
>unimplemented features, but if there's nothing to link to here at the 
>present time, then don't hold up the rest of the patch for that 
>reason.

The 'export' feature was removed from the standard and only one
compiler ever supported it. PR2316 is also something that very few
compilers support, and "fixing" the bug would break vast quantities of
code that rely on the bug. Most people don't even realise that the C++
standard requires language linkage to affect function types (I keep
meaning to propose that we drop that from the standard, or make it
implementation defined, to make the standard reflect reality).

If those are the only missing features then the wording quoted above
could be made more precise.

>The patch is OK with those changes.

Committed, thanks.