Hi, this is my first posting to this list.

My posting below attempts to address all the points made so far on 
this subject, and supports Bill's proposal for use of perldoc for 
documentation.

I propose perldoc be used in the following way:
  * the documentation is _authored_ in perldoc.
  * a Makefile exists to get existing perldoc tools to
    convert the perldoc file(s) to html, man page, plain text,
    etc.  These are all generated directly from the source
    perldoc(s).  A certain subset of possible output formats
    should be chosen as the 'supported' formats (say, man,
    HTML, and ascii)and docs output in those formats should
    be tested (by authors/editors) to read correctly.
  * a Windows-ish distribution would come with the perldocs
    pregenerated into the various file formats.  Perldoc is
    still the authoring format.
  * a Unix- and Source-ish distribution would only include
    the perldoc source and the Makefile to generate the
    other formats, which would be created as part of the
    normal build process.

I presume we all agree that it'd be nice to settle on one authoring 
platform that could smoothly output versions to HTML, PDF, ascii, 
etc.  There may be better alternatives than perldoc for this 
authoring format, but perldoc is sure to be ubiquitously supported 
and widely understood.

Thoughts?
joshr

Bill Mosely wrote:
>If I ever have more than a few minutes free I plan on updating some of the
>swish documentation that's included in the distribution... -- would 
>anyone have any objections to using Perl's POD (Plain Old 
>Documentation) format?  ... POD is a rather simple document format, 
>and there exists modules to convert POD to man, HTML, plain text, 
>PDF, and Postscript.  So it's a nice base format.
>See any problems? Bill Moseley mailto:moseley@hank.org

-- 
----------------------------------------------------------------------
-- Josh Rabinowitz                           joshr-swishe@joshr.com --
-- SkateboardDirectory.com(tm)      http://SkateboardDirectory.com/ --
-- SkateTalk Chat Systems(tm)             http://www.skatetalk.com/ --