Re: where should C++ options be documented?

[Martin Sebor <msebor at gmail dot com>]

Let me try gzipping the attachment to see if it gets past
SpamAssassin.

On 04/04/2018 11:08 AM, Martin Sebor wrote:
> On 04/04/2018 05:49 AM, Nathan Sidwell wrote:
> > On 04/03/2018 07:05 PM, Martin Sebor wrote:
> > @@ -3914,6 +3916,7 @@ Options} and @ref{Objective-C and Objective-C++ Di
> >  -Wc++11-compat  -Wc++14-compat  @gol
> >  -Wcatch-value @r{(C++ and Objective-C++ only)}  @gol
> >  -Wchar-subscripts  @gol
> > +-Wclass-memaccess @r{(C++ and Objective-C++ only)}  @gol
> >  -Wcomment  @gol
> >  -Wduplicate-decl-specifier @r{(C and Objective-C only)} @gol
> >  -Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol
> >
> > The verbose '(C++ and Objective-C++ only)' and similar repeated
> > annotations are annoying.  Even in the diff snippet there's no
> > consistency -- Why is -Wc++11-compat not annotated, why does
> > enum-compare contain what looks like documentation; 'on by default ...'.
> >
> > Either don't note at this point, or use some contraction such as simply
> > '(C)' or '(C++)' with the understanding that unless otherwise specified
> > that includes the objective dialect.
>
> I agree.  How about using a @multitable:
>
>   @option{-Wall} turns on the following warning flags:
>
>   @multitable @columnfractions .3 .7
>   @headitem Option @tab Notes
>   @item @option{-Waddress}
>   @item @option{-Warray-bounds=1}
>   @tab Only with @option{-O2}.
>   @item @option{-Wbool-compare}
>   ...
>   @end multitable
>
> The PDF output of markup is attached.  The HTML looks similar
> (the column headings are centered and don't line up with the
> column text).
>
> With this approach we could avoid having subsequent entries
> for the C++ options in the section.  (Unfortunately, I don't
> see a way to point directly at the detailed C++ description
> of the option from the table.)
>
> > Is it possible to use two different footnote markers such as
> > <super>{C,C++}</super> and explain in the so-noted footnote?
>
> I don't think that's possible with @footnote.  Texinfo seems
> to like to number each seperately and I don't see a way to
> change the numbering into something else.  It might be possible
> to achieve a similar effect with cross-references if the table
> idea doesn't fly.
>
> Martin

Attachment: gcc-page-64.pdf.gz
Description: application/gzip