[Doc-SIG] A couple documentation questions

[Fred L. Drake]

skip@mojam.com writes:
 >     1. Are there any standards or conventions for module documentation?
 >        I thought there used to be a template doc file named libxxmodule.tex

  See the file Doc/templates/module.tex; there are extensive comments
in the file.  Where there are gaps, send a note to me or the SIG.
Where the comments can be improved, I'll be glad to do so.

 >     2. How do people test what they've written?  It takes forever to format
 >        the entire manual.  I quickly tried creating a libsmall.tex file
 >        that's lib.tex with just my modules, but "make libsmall.ps" fails in
 >        both the paper-letter and lib directories.  I guess that route will
 >        require some Makefile fiddling.  It would be nice if there were
 >        already default targets for the common chain .tex -> .dvi -> .ps.

  Probably the easiest way, if the speed is a problem for you, is to
create a short "howto" style document.  Use Doc/mac/mac.tex as a
template.  The point Doc/tool/mkhowto (or Doc/tools/mkhowto.sh if
you're not using the CVS repo) at the top-level .tex file.  Use the
--help option for usage information.
  If even that proves too painful or if you encounter difficulties, do 
what you can by inspection and then send it to me; I'll be reviewing
the markup anyway.  It'll also help me develop better tools for
dealing with all this stuff.  (The mkhowto script should pretty well
take care of everything, though.)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives