[cfe-dev] scan-build man page

[James K. Lowden]

On Thu, 10 May 2012 11:54:04 -0700
Ted Kremenek <kremenek at apple.com> wrote:

> I meant no offense to your efforts.  If your main concern is lack of
> a man page, I'm fine with adding one.  My questions more focused on
> what went into the man page, how it got there, etc.  These are
> important questions.  

No offense taken, and none intended.  I think the discussion is
healthy.  Sure, it might have helped had you said, "I'll commit this for
now pending a larger discussion about what to do"; maybe I'd have felt
a little more like I'd done something useful.  But I don't feel
denigrated or rejected.  Your response was polite and matter of fact.  

I think you might have been the been on the receiving end of some
frustration for things you didn't say.  I'm sorry for that.  

To me, documentation *systems* have been done and done again.  We have
DocBook, TexInfo and mdoc.  And, heaven knows, doxygen.  The world does
not need another, and clang is ill-suited to invent another.  It might
seem like a good idea because we're leveraging something we've already
got.  But the experience of thousands of projects over decades is that
documentation is a significant and *separate* effort.  It's never
rooted in the help system (unless it *is* the help system, viz
Microsoft). It's not table-driven and it's not mechanically generated.
That fact alone should tell anyone that clang should be, in this case,
a technology adopter, not a technology inventor.  

> > Should the man page serve as the comprehensive
> > documentation for all things related to scan-build?  There have been
> > different opinions on this thread.

All documentation is of two kinds: User Guide and Reference Manual.

A UG walks you through how do things in some learnable order.  It is
read linearly.  It starts with simple concepts and dismissable claims,
and works through the process the creator's of the software supposed a
user might take.  It's indexed, and the user might have to backtrack.
But it's fundamentally an exposition of why and how things are done.
To some extent, it may explain the problem domain too.  

The RM is never read linearly except by dweebs and authors (possibly
the same set).  It is organized by feature and accessed by its
index.  It says what's true in as few words as possible. It's a "what"
document.  There's no place for why and how.  The user is assumed to
have read the UG, or at least to have the sense to follow the "read the
UG" advice when the RM points him that way.  

The linear/lookup dichotomy influences technology choices.  No one (if
you ask me) wants reference manual in HTML, at least not *only*  in
HTML.  Nothing is faster than 'man foo', especially when the immediate
next step is / to start searching.  (My favorite is "man foo
<enter> /^FILE" to find the FILES section of the page.)  But HTML is
soft and portable, not a bad format for linear access.  PDF has many of
the same properties, but online viewing isn't as convenient.  

So, no, I would never propose a man page as the be-all and end-all of
scan-build documentation.  I don't yet know enough about it to write
the UG.  I started with a man page because I knew how.  

I have seen too much documentation that confuses guide and reference.
I'm planting this stake in the ground because, if I'm to be involved in
clang's documentation, I would aim to make the guide expansive and the
reference terse.  

(None of the above is intended as criticism of the existing
documentation.)  

--jkl