I was just thinking of the standard pod2man and pod2html tools. Both create a
standalone documentation file in a particular format; input can be a pure POD
file or a code module with inline POD. Those two tools should address the first
two formats in your third recommendation below. A very quick search didn't
reveal any pod2pdf or pod2xml tools; these may become todo items.
Would an XML DTD be a decent way to express our documentation convention, as far
as what things should always be documented? If it's not *the* way the
convention gets expressed, it should probably be at least *a* way to express it.
--Wesley
Stephen Adkins <[EMAIL PROTECTED]> on
11/12/2001 11:16:05 AM
To: "Wesley_Sheldahl/Lex/Lexmark.LEXMARK"@sweeper.lex.lexmark.com
cc: [EMAIL PROTECTED] (bcc: Wesley Sheldahl/Lex/Lexmark)
Subject: Re: Inline POD vs. External POD
I have the following add-on questions.
1. Wesley - How do we configure the Makefile.PL so that the documentation
gets
separated from (stripped from?) the code at "make; make install" ?
(or did I misunderstand you?)
I have the following recommendations.
1. Use inline POD where possible and separate POD files where reasonable
2. We need to come up with a commenting/POD convention to allow for
specification
of at least all of the things that Javadoc allows you to specify
3. Standard "make; make install" for a P5EE module should produce man
pages (perldoc),
html pages, PDF, and XML (for further flexible conversion/rendering)
4. Our standard doc generation should produce output at least as nice as
Javadoc
(see an example at
http://java.sun.com/j2ee/sdk_1.3/techdocs/api/index.html)
