[cfe-dev] scan-build man page

[James K. Lowden]

On Fri, 11 May 2012 10:29:37 -0700
Anna Zaks <ganna at apple.com> wrote:

> > Yes, they are system specific.  On Windows, for example, the unix
> > checkers aren't enabled, and the osx checkers are only enabled on
> > Apple platforms.  You can find out more details by going to
> > lib/Driver/Tools.cpp.
> 
> So scan-build dynamically generates the list of enabled checkers
> depending on the platform on which it's being run. So if the man page
> is static it should either:
>  - not print the list of checkers but refer to a scan-build command
> for the list
>  - be automatically generated (which seems to be punted for now..)  
>  - document the platforms on which each checker is enabled by default

When I first understood that the defaults differ by OS, I was tempted
to say that the on/off part of the manual would indeed need to be
dynamically generated.  That wouldn't bother me because the "on" or
"off" text wouldn't require markup.  

But on reflection I prefer one static page.  The page could include a
note similar to Ted's above, and/or each individual checker could be
flagged as on/off/osx/linux/windows/unix etc.  The cheap way out would
be for the manual to say simply "Defaults differ by OS; see scan-build
--help for the list enabled by default on your system."  

I think one page is better for three reasons:

1.  It's less confusing.  Anna and I were confused about the defaults.
Anyone else might be, too.  If the page states what defaults go with
which OS (and they don't change too often) then two programmers working
on different OSes wouldn't be surprised by the differing defaults.  

2.  The sheer number of choices augers for a configuration file.   If
we adopt, say, /etc/scan-build.conf, then there need not be any
defaults to describe.  

3.  scan-build will continue to need a way to report the engaged
checkers both with and without the effect of the configuration file (if
any).   As a user I would always be more interested in that anyway.  

Regards, 

--jkl