[cfe-dev] scan-build man page

[Paul Robinson]

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
> [1] for a nice tabular overview of his "documentation is fractal"
> philosophy. [2] is his video presentation, and [3] the webpages.
>
> IMO worth at least glancing at for ideas of "What" your documentation
> set should contain. I also like his use of Sphinx [4] (and therefore
> ReST [5]) but that's a separate issue :)
>
> [1] http://www.slideshare.net/jacobian/writing-great-documentation-codeconf-2011
>
> [2] http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042
>
> [3] http://jacobian.org/writing/great-documentation/
>
> [4] http://sphinx.pocoo.org/
>
> [5] http://docutils.sourceforge.net/rst.html
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev

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.

Pogo
who really should know better than to jump into a thread like this