where should C++ options be documented?

[Martin Sebor]

On 04/04/2018 07:05 AM, Jason Merrill wrote:
> On Tue, Apr 3, 2018 at 7:05 PM, Martin Sebor <msebor@gmail.com> wrote:
>> 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.
>
> 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?

I don't see a way to avoid them if we keep both references.
TexInfo inserts them automatically and I can't find a directive
to suppress them.  In the multitable format I posted earlier
I only used the latter reference because it makes it clear
when an option is C++ only.  The downside is that it doesn't
take us directly to the description of the C++ option.  I could
use the former reference instead to jump directly to the option
but then it would say "Section 3.5 [whatever we put in here],
page 45 which would look funny if it said [C++ and Objective-C++
only].  Ideally, I'd like to see just "C++ and Objective-C++ only"
next to each option in the table and either have the text point
to the option description or turn the option name into a link
pointing to it, but I don't think that's possible, so we'll
probably have to come up with some compromise.  What should
it be?

>
>> +@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.

Sure, I can remove the @opindex directives here.

Martin