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:
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
