[cfe-dev] scan-build man page

[Joerg Sonnenberger]

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.

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

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.

> 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. 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.

Joerg