where should C++ options be documented?

[Martin Sebor]

On 04/03/2018 08:08 AM, Jason Merrill wrote:
> On Mon, Apr 2, 2018 at 9:33 PM, Martin Sebor <msebor@gmail.com> wrote:
>> Jason,
>>
>> The manual mentions some C++-only options in the language
>> independent section 3.8 Options to Request or Suppress
>> Warnings and others in 3.5 Options Controlling C++ Dialect.
>>
>> For example, -Wcatch-value, -Wconditionally-supported,
>> and -Wzero-as-null-pointer-constant are mentioned only
>> on the former page, while -Wabi-tag, -Wctor-dtor-privacy,
>> -Wliteral-suffix, and -Wclass-memaccess are mentioned only
>> on the latter.
>>
>> That makes C++ options harder to find than they should be.
>> It also makes it difficult to tell which C++ options are
>> included in -Wall or -Wextra.  I think we should converge
>> on the same approach for all C++ options that doesn't have
>> these problems.  What should it be?
>>
>> An approach that I think might work well is to continue
>> to mention even C++-only options in 3.8 but move their
>> descriptions to 3.5 (i.e., have the entry for each link
>> to the full description of the option on the C++ page).
>
> Sounds good.
>
>> Should I try to make this happen for GCC 8?
>
> Sure.

Attached is a prototype of what I have in mind.  It changes
just one option for illustration: -Wclass-memaccess.  Once
we're happy with the result I'll follow the same approach
for the rest of the C++ warning options.

To make it possible to jump directly to the detailed option
I had to add an explicit anchor.  That's an extra step that
would be nice to avoid.  The reference from -Wclass-memaccess
in 3.8 to the detailed option description in 3.5 renders like
this in HTML:

   See -Wclass-memaccess in Controlling C++ Dialect.

and like this in PDF:

   See [Wclass-memaccess], page 52 in Section 3.5 [Controlling C++ 
Dialect], page 42.

Martin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gcc-doc-cxx-options.diff
Type: text/x-patch
Size: 2187 bytes
Desc: not available
URL: <https://gcc.gnu.org/pipermail/gcc/attachments/20180403/39183d53/attachment.bin>