On Tue, Apr 3, 2018 at 7:05 PM, Martin Sebor <mse...@gmail.com> wrote:
> On 04/03/2018 08:08 AM, Jason Merrill wrote:
>> On Mon, Apr 2, 2018 at 9:33 PM, Martin Sebor <mse...@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.
It would indeed be nice if there were a way to xref to an index entry.
> 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.
Do we need both page numbers?
> +@item -Wno-class-memaccess @r{(C++ and Objective-C++ only)}
> +@opindex Wclass-memaccess
> +@opindex Wno-class-memaccess
> +See @ref{Wclass-memaccess,@option{-Wclass-memaccess}} in @ref{C++ Dialect
> Options,,Controlling C++ Dialect}.
I don't think we want index entries for cross references.
Jason
