[cfe-dev] scan-build man page

[Ted Kremenek]

Great comments.  Comments inline.

On May 10, 2012, at 5:46 AM, Joerg Sonnenberger <joerg at britannica.bec.de> wrote:

> On Mon, May 07, 2012 at 04:20:54PM -0700, Ted Kremenek wrote:
>> 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)?
> 
> Because a man page is more than just list of command line options. There
> are basically two kinds of tools: those that have a few trivial options,
> where this automation would just be overkill, and those that have a lot
> of options, where a proper man page requires a lot of good structuring,
> making any automation a pain to deal with.
> 
> This is the same problem as the discussion for the clang documentation. 
> The same arguments given to that email apply here as well.
> 
>> 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.
> 
> One of the things I hate about git is that the user interface is
> inconsistent enough that they have to create a hundred man pages
> documenting the different option sets.

That's fair, but would you agree that the idea is good in principle, and that this is problem with the execution, or do you think the fundamental design of that help system is flawed?

> 
> I really, really hope scan-build won't end up with that mistake.

Just to be clear, which mistake are you referring to?  The inconsistency of the interface?

> 
> Take a look at flex(1) and yacc(1) for a moment. I think they are quite
> good at illustrating completely different levels of verbosity.
> 
> http://netbsd.gw.com/cgi-bin/man-cgi?yacc++NetBSD-current
> http://netbsd.gw.com/cgi-bin/man-cgi?lex++NetBSD-current
> 
> yacc(1) is nice because it starts by answering the most important
> questions first: what is this and how do I run this. Disadvantage is
> that it doesn't even cross-reference the input format. Would I like in a
> man page for the grammar specification? Not really, I know the
> complexity of the beast.
> 
> lex(1) is a lot more messy. Even if I just want to know how to run it, I
> have to skip past all this introductional use etc. It's overloaded.
> Look at the AUTHOR section -- it's just missing a completely ChangeLog.

Excellent points.

scan-build's documentation, which can be found by running it with no options, consists of a short list of options, a list of checkers, and a short example (at the very end).  The man page that James provided is essentially this output reformatted as man page.  Other documentation can be found on the clang-analyzer.llvm.org website, that has a bunch of information such as tips for using it with projects the use configure, etc.  All of that is missing from the help emitted from the tool.

>From my perspective, right now the man page provided by James adds incremental value, as it doesn't solve any of the concerns you mention, and it creates a potential maintenance burden to maintain.  If the goal of the man page is to essentially to replicate the output of scan-build's auto-generated help text, then I think the majority of the man page could be auto-generated by formatting that output into something than 'man' likes.  Having a man page is useful for users that expect man to be the source of help.

Given your feedback, would you think a scan-build be to have a very focused man page that omitted the checker descriptions?  That would essentially be NAME, SYNOPSIS, OPTIONS, and EXAMPLE.  I could then see 'scan-build help' just loading up the man page, and providing other means to get the list of checkers.

> 
>> 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.
> 
> *That* part can and should be automated easily.
> 
> Now the real question in all of this is how much of the options are
> really scan-build specific and not shared e.g. with clang. For complex
> build systems it can be a lot easier to integrated clang --analyze
> directly and the checker specification and many other things are
> logically more a part of the clang CLI.

It was never my intention to make 'clang --analyze' a public part of the interface to the analyzer, but more a low-level implementation detail.  The problem with people adopting clang --analyze directly is that it encumbers us with how we (one day) will design global analysis.  My hope was to have a simple command for "analyzing my project or source file", and that was meant to be scan-build, or have proper integration within an IDE that understands that 'clang --analyze' is just one implementation detail part of probably others that need to be considered when integrating the analyzer into an IDE.

> I'm generally not sure manual
> pages are the best format to describe the checkers, especially it is
> often very useful (if not necessary) to show test cases using HTML
> output mode to clarify the behavior. For that reason alone I think a
> well structured hyper text document is a more appropiate format. This
> doesn't remove the need for a manual page, but restricts what it has to
> do. Provide a description of the command line and reference the online
> manual for further details.

Makes sense.