[cfe-dev] scan-build man page

[James K. Lowden]

On Thu, 10 May 2012 12:10:24 -0700
Ted Kremenek <kremenek at apple.com> wrote:

> If the list of checkers can be easily verified with sed or perl, why
> can't this section of the man page (if we want to include it) be
> auto-generated?  It's just the reverse process.  

Because you don't want markup in Options.td.  

It's easy to use regex to find the markup and extract the data.  It's
impossible to devise an algorithm that can generate the markup
spontaneously except insofar as the markup is derivable from something
about the data (say, its structure).  

Here's an example from the page:  

.It osx.cocoa.ClassRelease
Check for sending 'retain', 'release', or 'autorelease' directly to a
Class 
.Bq off

That's a little broken, a first-draft cheat.  Those single quotes
shouldn't be there because groff can't style them as open-close
quotes.  In fact, IIUC they're literals, which in PDF format won't have
quotes at all!  (Question for the audience: would the programmer adding
this to Options.td know that?)  

What you want is 

.It osx.cocoa.ClassRelease
Check for sending 
.Li retain , 
.Li release , 
or 
.Li autorelease
directly to a Class 
.Bq off

producing http://www.schemamania.org/clang/scan-build.pdf.  

That's not the only such example.  

Do you want to keep text just like that -- verbatim, no whitespace
before the line ending -- in Options.td?  Clearly not.  Do you want to
invent/use some other markup that can stand in for it, and write a
translator to produce the appropriate mdoc markup?   When the mdoc
output is wrong, how much debugging do you want to do?  When the
invented markup is insufficient, how much more time do you want to pour
into it?  

If you care about the documentation enough to write it, how much time
do you want to invest learn the clang NIH markup toolchain?  

Remember, these questions exist in the service of only one question:
how to generate documentation programmatically?  If the question is
shortened to "how to generate documentation", the answer is easy:
Typing!  And the problem of verification is reduced to a tiny shell
script.  

Regards, 

--jkl