[cfe-dev] scan-build man page

[James K. Lowden]

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

> Perhaps these are bike shed questions, but they are important.

Well, no, they can't be both, so I'm going with "important".  :-)

> Now scan-build isn't git.  The options are fairly simple, and most of
> them exist today because of stupid limitations in its current
> implementation.  

Maybe there's a method in the madness, but I'd like to settle on 1 or 2
dashes for options, and no equals sign before arguments.  We currently
have AIUI:

	--use-c++ [=compiler_path]
and
	-store [model]

for instance.  

> The only thing I see changing quickly is the list of
> checkers, which was my main point of contention in my original
> email.  Should those be included in the man page, and if so, how much
> information?  

I didn't understand at the outset that was your major concern.
I'm glad you clarified that.  

if you ask me, everything about every checker should be in the man
page.  Will it be long?  Yes.  Hard to find what you want?  Maybe, but
I'm not convinced anything else is better.  

A good point of comparison might be bash.  Its documentation can be
read with info(1), man(1), or in HTML.  It's pretty complicated.  

$ man bash | wc
    5358   40868  363520
$ man sh | wc
    1351    8832   67889

At 40,000 words it's no haiku.  Now, quick: what's the syntax for
variable expansion with a default value?  

If you remember only that it has something to do with "${parameter@@@
word} and you don't remember any of the values for @@@, you type:

	/\${

press Enter, type 'n' 15 times, and you're there:

       ${parameter:-word}
		Use  Default  Values.  If parameter is unset or null,
		the expansion of word is substituted.  Otherwise, the 
		value of parameter is substituted.

If you can remember any of the magic expansion operators, it's about 5
keystrokes to get you in the right vicinity.  

The only way I've been able to find that in info(1) or tkinfo is by
searching.  Its title node is "Shell Parameter Expansion", not to be
confused with (its parent) "Shell Expansion".  It has nothing to do
with "variables", which are something else altogether.  The term
"default" does not appear in the index.  

For many years bash had no man page worthy of the name.  That one was
added tells me many people experienced the same lack of utility in info
pages that I do.  

This is not the fault of hierarchical organization, nor of the people
who wrote the documentation.  (Well maybe some of each.)  The real
culprit is taxonomy.  Or, rather, the work in creating a meaningful
taxonomy and the work of learning one.  That's why my attempt to use
the index and toc both fail: they're thinking "parameter expansion" and
I'm thinking "variable default".  (I'm right, btw.  A parameter is
always a variable; a variable is not always a parameter.) It's one of
the challenges to documentation: how to organize it in terms meaningful
to the user?  

That is the Lesson of Google.  Searching works well if it's fast and you
have some fragment of an idea what you want. Show me the nice, well
organized, thoughtful, hierarchical list of links you use to find what
you want on the web, and I'll show you 1998.  

HTML suffers the same problem a little less painfully.  

Oh, were we talking about scan-build?  

> Where should that information go?  In the man
> page?  If so, do we enter a place where the man page gets
> ridiculously long and lacks focus?  

Well, we want man pages, PDF, and (maybe) HTML, in that order.  Our
source choices ISTM are texinfo, -mdoc, DocBook, and doxygen. I'm
eliminating doxygen because its output is inaccessible from the command
line.  I'm eliminating texinfo because I never met anyone who prefers
info(1) to man(1).   

Both mdoc and DocBook can be rendered as PDF and as man pages.  DocBook
has the edge in HTML, but producing man pages is a (surmountable)
challenge.  mdoc makes man pages directly, excellent PDF, and just OK
HTML.  I emphasize man pages for speed and direct access.  Someone
to whom HTML is important will come to different conclusions.  

Based on my experience with bash, you're *very* safe just tossing
everything into one man page.  Once that's done, you have a man page.
Hurrah!  If someone comes up with something better, or if experience
demonstrates it's unwieldy, we can break it up or do something else.  I
think we'll be able to keep it under 40,868 words, so it won't be
ridiculously long.  And I don't think focus is a function of length.  

An mdoc man page is the least work, adds nothing to the tool chain, and
meets our immediate needs.  It also leaves the door open to DocBook
later, should we so choose.  

The man page can be rendered as PDF.  To create a toc with links in the
PDF is a little tricky with groff, but definitely doable.  It takes a
wee bit of cleverness to get the toc placed at the front of the PDF.
Hyperlinks are possible, too.  (I'm not an expert.  I just play one on
TV.)  These are bells and whistles, though.  The basic PDF is
excellent.  That meets the Windows concern.  

groff will even yield HTML, cf.
http://www.schemamania.org/clang/scan-build.html.  Please keep in mind
that's the raw product.  Nothing special done in the source, no post
processing, no CSS.  It could use a little TLC.  

DocBook will do the job too.  A few years ago I would have recommended
SGML DocBook.  It renders beautiful HTML, nice toc.  DocBook will
render man pages; there's a whole set of <reference> tags.  I prefer
SGML, but XML is where all the activity is. Downsides?  XML is more
verbose (some people will consider that an advantage.  Kernighan
himself called the troff syntax "rebarbative".  He also used troff for
his latest book, recently out.)  The DocBook toolchain is is bigger and
baroque. Man pages are an output, not an input.  

I myself never got SGML DocBook to render bona fide man pages.  It
might be easier with the XML toolchain.  I decided to learn -mdoc
instead.  

Years ago I did produce PDF from DocBook, which is when I learned that
"write once, render many" is a bit of mirage.  At the time, what you
got was suitable for printing.  The toc had no links to take you to a
page, and hyperlinks were rendered as if on paper.  I do not know if
that's since changed.  

Conclusion?  I bias all choices in favor of solving the problem I know
I have.  I discount speculation about what might happen in the future
because often as not it's OBE, Overcome By Events.  Lots of things
never get done because something else is always more important.  That's
as it should be.  

That's why I say toss everything in a man page and move on.  It's easy
to edit and uses bog-standard technology.  

We don't give up anything.  We get man pages and PDF right off the bat.
With a little tweaking we get PDF with a linked toc starting on page
one.  A little more tweaking gets us passable HTML, too.  

Goodies?  Write a little verifier to make sure the checkers are all
accounted for.  Read it over once in a while.  Tell make to install the
page and render the PDF.  

Regards, 

--jkl