[cfe-dev] scan-build man page

[James K. Lowden]

On Thu, 10 May 2012 14:46:40 +0200
Joerg Sonnenberger <joerg at britannica.bec.de> wrote:
> On Mon, May 07, 2012 at 04:20:54PM -0700, Ted Kremenek wrote:
>
> > 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.

The complexity of the documentation is a function of the complexity of
the interface.  git is hard to learn because of the size of its
interface, not because of the form of its documentation.  

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

You want the man page to list all the checkers.  Consider: 

$ man scan-build | grep debug
     debug.DumpCFG
     debug.DumpCallGraph
     debug.DumpDominators
     debug.DumpLiveVars
     debug.Stats
     debug.TaintTest
     debug.ViewCFG
     debug.ViewCallGraph

That's a great way to grab a reminder or build a command line with all
the debug checkers.  

If test cases and examples are many, I would say you're describing
a user guide more than a reference manual.  As long as you have two
documents, the man page can be terse because "how" is explicated in the
user guide.  

I could make a case for a user guide in -mdoc format.  It would
be easy to view in a terminal, and PDF is very pleasant for linear
narratives (not to mention printing).  

But DocBook gets the job done, too.  It has more verbose input and a
bigger toolchain, but you get very nice HTML.  A single DocBook document
*can* be rendered as HTML and Postscript/PDF, but it takes some skill
and willingness to particularize parts of the source with escapes for
intended targets.  A project the size of clang can probably cope with
those issues.  

--jkl