[cfe-dev] scan-build man page
wingusr at gmail.com
Thu May 10 18:02:40 PDT 2012
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 :)
More information about the cfe-dev