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

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.

  • Comment on Re: [literate programming] How to mix POD with code? And how to fold this?

Replies are listed 'Best First'.
Re^2: [literate programming] How to mix POD with code? And how to fold this?
by LanX (Saint) on May 04, 2010 at 13:43 UTC
    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
}

    [download]

    or 

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

    [download]

    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 :)

    Cheers Rolf

[reply]
[d/l]
[select]

In Section Seekers of Perl Wisdom