[cfe-dev] scan-build man page
pogo.work at gmail.com
Thu May 10 18:32:45 PDT 2012
On Thu, May 10, 2012 at 6:02 PM, TP <wingusr at gmail.com> wrote:
> On Thu, May 10, 2012 at 1:02 PM, James K. Lowden
> <jklowden at schemamania.org> wrote:
>> 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
>> user guide.
>> 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
>> those issues.
> Jacob Kaplan-Moss in "Writing great documentation" talks about four
> types (Tutorials, Topic Guides, Reference, Troubleshooting) and levels
> (Project, Document, Section, Element) of documentation. See page 42 of
>  for a nice tabular overview of his "documentation is fractal"
> philosophy.  is his video presentation, and  the webpages.
> IMO worth at least glancing at for ideas of "What" your documentation
> set should contain. I also like his use of Sphinx  (and therefore
> ReST ) but that's a separate issue :)
>  http://www.slideshare.net/jacobian/writing-great-documentation-codeconf-2011
>  http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042
>  http://jacobian.org/writing/great-documentation/
>  http://sphinx.pocoo.org/
>  http://docutils.sourceforge.net/rst.html
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
Let's not forget contextual command-line help. If I'm using the 'foo' utility,
I want 'foo --help' to tell me how to spell the subcommands, and I want
'foo bar --help' to tell me how to spell the options to the 'bar' subcommand.
I don't want a man page or a reference manual at that point, I'm trying to
use the stupid command and know what I want to do and just can't recall
what cryptic abbreviation the overly clever devos decided to use.
who really should know better than to jump into a thread like this
More information about the cfe-dev