[cfe-dev] scan-build man page

[Ted Kremenek]

This entire email is a bit for me to digest.  :)  It will take me some time, but I see a lot of valid points there.  Thanks so much for taking the time to write it.

My plan is to re-examining scan-build from core implementation to CLI staring this summer.  The would be a potentially great opportunity to consider how a good CLI maps to good documentation, what form that documentation takes, and so on.  On the documentation front, I'm fine with experimenting with the man page, adding or removing material, and see how it works out.

On May 10, 2012, at 7:52 PM, James K. Lowden <jklowden at schemamania.org> wrote:

> 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