[literate programming] How to mix POD with code? And how to fold this?

[LanX]

Hi

I had a discussion with Ilya Zakharevich about how cperl-mode in emacs should fold perl-code in respect to embedded POD.

I'm a big fan of literal programming, DRY and encapsulation but holding the documentation in close vicinity to the code doesn't seem to be that easy in perl...

Do I get right that the only "straighforward" way to achieve this with CPAN-like POD-structure is by splitting POD into two surrounding parts and preceding every sub by

=head2

... 

=cut

parts?

=head1 NAME

=head1 VERSION

=head1 SYNOPSIS

=head1 DESCRIPTION

=cut


# some nonsub perlcode

#========================================

=head1 METHODS

intro about methods ...

=cut  

#----------------------------------------

=head2 load ($source, -opt1 => $val1, ...)

text describing load()

=cut

sub load {
  #body
  #body
  #body
}

#----------------------------------------

=head2 parse ($string, -opt1 => $val1, ...) 

text describing parse()

=cut

sub parse {
  #body
  #body
  #body
}

#========================================

=head1 SEE ALSO

=head1 AUTHOR

=head1 BUGS

=head1 ACKNOWLEDGEMENTS

=head1 COPYRIGHT & LICENSE 

=cut

UPDATE: thats how the resulting man page looks like:

NAME
VERSION
SYNOPSIS
DESCRIPTION
METHODS
       intro about methods ...

       load ($source, -opt1 => $val1, ...)

       text describing load()

       parse ($string, -opt1 => $val1, ...)

       text describing parse()

SEE ALSO
AUTHOR
BUGS
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE

[jethro]

What is it that you find not easy with this approach? pod source doesn't look very readable IMHO. But other literate programming tools like Knuth's weave seemed to have had similar problems, the solution seemed to be a folding editor

I don't see any possible variations here. Either you put the pod where the method is or you don't.

A small improvement might be to put all Pod before METHODS and after SEE ALSO in a separate file and only add these parts when 'make install' or something like 'make distribution' is called. This would make editing a bit easier without a folding editor.

[LanX]

1. It's difficult to fold...outline-minor-mode assigns outline-levels and "=head1" and "sub {" are toplevel, "=head2" second level and so on. Ilya wants to know the "common sense" befor changing this.

2. It's not DRY, e.g. I still have to repeat the method name

3. all these necessary empty lines makes it voluminous

4. (personal side note) it doesn't support introspection a la "docstring"

> A small improvement might be to put all Pod before METHODS and after SEE ALSO in a separate file

yeah I already had this idea to extract documentation in comments and to generate the POD.

e.g. something like

sub func {
  my $DOC="yadda yadda"
  ...code
}

or

sub func :DOC(yadda yadda) {
  ...code
}

would fold nicely in every editor, allow introspection and could be parsed to generate the POD.

(but it's always smarter to ask before risking to reinvent the wheel :)

[JavaFan]

"Perl code + POD" != "Literate programming". It's a misconception common enough to gets its own mentioning in the Wikipedia page about literate programming.

POD just allows you to put documentation close to code - but normal comments allow you to do that as well. Literate programming is when documentation replaces (parts of) code, and defines the control flow; a preprocessor assembles bit and pieces of code found in documentation into a program. POD doesn't do that.

[LanX]

sure, I read MJDs article on perl.com ... more than once.

But ATM I don't need to go the full way, as I said POD more DRY and encapsulated.

[ssandv]

Don't. It makes the code hard to read. Perl has a perfectly good # character for putting comments in code.

[LanX]

> Perl has a perfectly good # character for putting comments in code.

And how do you create POD compatible documentation from these #-comments?

[ssandv]

You don't. You put the pod at the beginning or the end, where it belongs. Code comments should make sense when you have the code in front of you. If you can make pod from them, they're overwritten, and all they're doing is reducing your ability to see the code by shoving it out of the way. Pod is for a level of documentation that makes sense when you're not staring at the code. It's not dual-sourcing because it's not the same information.

[unixtechie]

I wrote a utility for Literate Programming called Molly. It can act as a traditional LP tool, i.e. do it from command line, or work under your personal web server, producing folding HTML on the fly

The pre-weaved documentation in folding HTML format is here:
http://literate-molly.sourceforge.net/
You have to have JAvascript enabled in your browser (and use Opera, Firefox, or Safari, the script has not been verified with IE in particular) The script itself and the LP source file can be got from Github:
http://github.com/unixtechie/Literate-Molly

Take Molly, and use it.

If however you will still wish to do the same thing with POD rather than HTML, add a most primitive regex POD formatter to Molly, modelling it on the "dotHTML" sample formatter, included in the source. Just copy it and change "dots" to POD marks in your regular expressions, eliminating the unnecessary lines.

With POD you lose one of the MAIN ADVANTAGES of Literate Programming, though: ability to write code IN THE ORDER OF YOUR OWN LOGIC, rather than the one imposed by the machine.