[cfe-dev] scan-build man page

[Ted Kremenek]

Hi James,

You've made some great points.  My point was more that I wanted the documentation of the basic command line options of scan-build, wherever we post them, to be in sync.  Certainly the detailed prose information doesn't need to be verbatim everywhere, but there should be some synergy there as well.

On May 7, 2012, at 2:36 PM, "James K. Lowden" <jklowden at schemamania.org> wrote:

> Mechnical, yes, but it can't be automated.  The text from scan-build
> lacks the very markers I added: the headings, that "model" is an
> argument, that [=title] is optional, and so on.  
> 
> In principle the text could remain embedded in scan-build and extracted
> to generate a man page.  But you'd have to re-invent half of -mdoc in
> the process, without any improvement in the outcome.  Perldoc is a
> good example.  

What I want is very simple:

(1) You've written prose that could be used to generate a good man page.

(2) You had a mechanical process to generate the man page from the scan-build options.

Given (1), why can't we generate a man page by automating (2)?  I don't understand why this is so hard.  Given the right level of refactoring within scan-build, we should be able to print out the text in different flavors.  One flavor could be amendable to a "scan-build help" and another for a man page generation.  Indeed, they could be made on in the same (see comment below).

> 
>> Alternatively, since scan-build generates most of this text, maybe it
>> could generate the options part of the man page itself (as an option
>> to its output format), and have that output concatenated with some
>> common preamble.  What do you think?
> 
> I would remove the help text from scan-build.  You don't need it
> anymore.  "man scan-build" is easier to use, and everyone knows how.
> Maintaining the man page is trivial next to the effort that goes into
> the scanner.  

I disagree.  One of the things I like about git is "git help <command>".  I find that interactive help wonderful, and a degree more powerful than a static man page.  It's a powerful idiom that would translate well to scan-build, e.g.:

  scan-build help check <checker name>

which could print out information specific about that checker.  A single man page needs to make compromises about what it includes and doesn't include.  Yes, "git help" is based on "man", but given that some of the information for scan-build can be dynamically queried from clang (e.g., the list of available checkers), it would be really powerful to have scan-build be able to dynamically generate man pages as necessary.  The last thing I want to do is every time I roll a new checker build that I need to manually check if the list of checkers in the man page is up-to-date.

Cheers,
Ted
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120507/9fa0d7f6/attachment.html>