[cfe-dev] scan-build man page
James K. Lowden
jklowden at schemamania.org
Thu May 10 13:02:46 PDT 2012
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
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
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
More information about the cfe-dev