On Mar 15, 2005, at 10:58 AM, Patrick R. Michaud wrote:
Without commenting on the merits of any of the proposals, I'll note that discussions about changing POD are probably design-level discussions that belong on p6l instead of p6c (which are implementation decisions).
You are absolutely correct. I will repost over on p6l later today.
Thanks,
- Steve
I don't mind if it's discussed here, but p6c is really the forum for "how do we implement XYZ" and not "what should XYZ be"?
Pm
On Tue, Mar 15, 2005 at 09:23:45AM -0600, Nigel Hamilton wrote:All that said I think a per-module perldoc documentation reader is still very important too ... maybe your design could allow for traversable HTML conversion in the future?
Well my idea is to not dictate the eventual output. But to create a system
which allows the most meta-data/contextual-information to be captured with
the greatest of ease, and let the specific formatter decide how much
information it wants and how to display and/or manipulate it.
Thanks for your response and comments.
Sounds likes a plan! :-)
I see documentation generation as another type of compiler.
Instead of the computer being the target audience it's human beings.
Writing a compiler for targeting humans has much of the same problems. A
human has limited memory, it should be able to link in a new module
quickly, and we want the transfer of ideas to be as quick as possible.
+===> ByteCode Perl6 Source => Compiler => | +===> HumanCode
Maybe your documentation compiler can take source, distill all the
good bits for human consumption and then this intermediate 'bytecode' is
translated into different target presentation formats - which is pretty
much what you're suggesting.
Perl 6 Source => Documentation Compiler => Good Bits => HTML (code browsing / CPAN) => txt (perldoc) => PDF (management)
But I think a compilation step may be needed to gather as much intelligence about the code as possible.
NIge
