PATCH for: Lots of suggestions for the gcc manual

[Gerald Pfeifer]

On Sat, 4 Oct 2003, Stephan T. Lavavej wrote:
> Other things I've noticed:
>> You can request many specific warnings with options beginning -W, for
>> example -Wimplicit to request warnings on implicit declarations. Each of
>> these specific warning options also has a negative form beginning -Wno- to
>> turn off warnings; for example, -Wno-implicit.
> These sentences should be parallel 8 [...]

I agree.  Would you mind try and prepare a patch for this?  (Concerning
patches, it's often better to submit several, smaller ones than a jumbo
patch, for different reviewers may be needed and it's also simpler for
one reviewer to handle independent hunks.)

> Okay, here are my suggestions:

Let me pick some. ;-)

> -Wall
> Implies the following options:
> [ginormous list of options follows]

By this you mean the detailed documentation of options, not just a list
of options, I hope? Duplicate lists would constitute maintainance night-
mares.

> 6. Each option included in -Wall should say (in -Wall).
>
> 7. -Wall should be followed by the options that it turns on.  This need not
> be a contiguous block, since (1) -Wall won't say "all of the previous
> options combined" anymore, and (2) each option included in -Wall says so.
> Still, grouping them rather tightly is the clearest way to go about things.

Agreed.

> 9. -Wimplicit is another option like -Wall, even though it only has two
> things in it.
>
> 10. -Wunused is yet another option like -Wall.  (It's all this nesting and
> chains of implications that makes the current organization so unwieldy.)

Yes, and no. What should become (or remain) clear from the documentation
is that -Wall somehow is the set of warnings that we recommend, somehow,
and where no problems should exist to make code -Wall clean.

> 11. After (in -Wall) has been added to the appropriate functions, their
> descriptions should be grepped to make sure they don't mention that they're
> included in -Wall.

Yes. Perhaps you could start by hacking a patch to address the issues
related to -Wall?

> I believe that this organization would be superior to, say,
> alphabetizing the options.

In a printed manual, alphabetical ordering is quite useful, so I'd
hesitate to have much more than two sections (-Wall and non-Wall)
each of which is sorted alphabetically.  But that's just my preference,
I'd certainly be interested the others'!

Gerald
-- 
Gerald Pfeifer (Jerry)   gerald@pfeifer.com   http://www.pfeifer.com/gerald/