where should C++ options be documented?

[Martin Sebor]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: gcc-page-64.pdf.gz
Type: application/gzip
Size: 59992 bytes
Desc: not available
URL: <https://gcc.gnu.org/pipermail/gcc/attachments/20180404/7dffb3b3/attachment.gz>