This is the mail archive of the
mailing list for the GCC project.
RE: PATCH for: Lots of suggestions for the gcc manual
- From: Gerald Pfeifer <gerald at pfeifer dot com>
- To: "Stephan T. Lavavej" <stl at caltech dot edu>
- Cc: gcc-patches at gcc dot gnu dot org, gcc at gcc dot gnu dot org
- Date: Sun, 5 Oct 2003 23:30:20 +0200 (CEST)
- Subject: RE: PATCH for: Lots of suggestions for the gcc manual
- References: <000001c38aa6$999db680$3c9fd783@northwood>
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. ;-)
> 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-
> 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.
> 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 Pfeifer (Jerry) email@example.com http://www.pfeifer.com/gerald/