DJ Delorie wrote:
I really, really hope to write an actual manual from scratch some day
Have you considered using Doxygen http://www.doxygen.org/ to embedded the documentation right in the software? Makes keeping both up to date easier.
For the type of manual we're talking about, source comments are absolutely useless as the basis for it. They do not have the proper structure to correspond to a user's guide.
At best, source comments can generate useful API manuals, and references for the elements of the software.
It's still a valid suggestion.
Doxygen only uses structured comments for its HTML/LaTeX/whatever output files, and there are plenty of ways to segregate API information from user information.
I think Bob's point is (correct me if I'm wrong) that Doxygen lets you put the pseudo-HTML in the same source file, as opposed to off in another file.
Take a look at the documentation for WinPcap:
http://winpcap.polito.it/docs/man/html/modules.html
or Doxygen itself.
-- Charles Lepple [EMAIL PROTECTED]
