Hello,
I really like POD and I like the changes in the upcoming Perl 6 Pod.
Have you ever heard of literate programing? (see Wikipedia). I think it
would be neat if Pod could do literate programing. It is already very
close. For reference, please see this article:
For reference, please see this page:
http://www.perl.com/pub/a/tchrist/litprog.html
In brief, the only thing that Pod is missing is allowing you to write
code sections in whatever order is best for people to understand, and
have them be re-ordered when we run the program.
I would like to suggest a "=ref" block type (for "reference") as well as
the :ref() configuration option for =head* and =code, such that:
---- start myshell.pl -----
=begin pod
=head1 Intro
This program is an infinite loop. On each iteration we
read user input and do something with it.
=begin code
while 1 {
=ref handle_input
}
=end code
=head1 Handling user input :ref(handle_input)
To handle user input we simply give the input to
Perl's built-in eval() function.
=begin code :ref(handle_input)
print "Prompt> ";
eval(<STDIN>);
=end code
=end pod
---- end myshell.pl -----
1) When you run "perl myshell.pl", Perl would grab the second code
block, move to where "=ref" is, and run the program normally.
2) When you run (say) "pod2html myshell.pl", the code block would remain
where it is, but the "=ref" would be replaced by a hyperlink to the
second "=head1".
In this way, a relatively simple change makes Perl 6 Pod able to do
literate programing for anyone who is interested.
What do you think?