On 04/04/2018 07:05 AM, Jason Merrill wrote:
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:


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?


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.


Reply via email to