#ifdef pod
    =head2 title
    blah, blah, blah
    =cut
    #endif /* pod */
[download]

And I don't want everything to have to start in column 0.

Yeah, and I don't want POD to start with ^=. But no such luck. POD derivatives are defined to start at column 0. Period. Unless you write a preprocessor, and only after preprocessing your source you give it to a POD parser, there's no way around it. Surely, you don't want:

      .... some deeply indented, long line ending in:  variable
      =function;  /* Unlucky wrap */
[download]

to be interpreted as POD, do you?

John M. Dlugosz said

I think you are asking for trouble, unless you come up with a more comprehensive approach.

If nobody has such a thing already, I suppose you will be designing it. I look forward to that thread!

I can't be much less comprehensive than I have been up to now. This seems as good a place as any to start the thread. Yes, I expect to use a preprocessor (of my own, nothing to do with C's) to extract the pod. Suppose we assume input of the form

    #ifdef pod
    (plain old pod here)
    #endif /* pod */
[download]

or

    /* pod first line of pod
    (plain old pod here)
    pod */
[download]

The latter has the advantage over #ifdef of allowing the first line of pod to share the line with the "pod opener", but I'm less pleased with the way it terminates the block. I'd like to hear opinions. In either case, we can easily identify the start and end of the pod. Suppose we take everything in between and eliminate all leading white space. This leaves something the pod processors will like. This leaves the problem of preserving leading white space when a verbatim paragraph is desired. We could accommodate that by adding a bit of "faux pod" (a term I should copyright) like

    =v  leave
    =v  this stuff
    =v  alone
[download]

where we could preprocess out the =v (and a single space, so we don't run afoul of some real pod directive?), and leave everything that follows untouched. No need for a final =cut, we could supply it automatically when we hit the pod terminator, or just omit it altogether, since the preprocessor is only gathering pod, so there's no need to drop "in and out".

Thread begun. Comments?

A followup to my own followup (but not as a reply, which could drive the depth of the replies below the default level of visibility).

The preprocessor could take, as arguments, two patterns to identify the start and the end of the pod block. This would make it more general than something dependent on C conventions.

Update: and maybe another pattern to determine what should be deleted from the start of each line in the pod block, so we don't have to rely on white space.

Update #2: First approximation (missing way to set patterns):

#!/usr/bin/perl -w

use strict;

my $start = qr{^.*#\s*ifdef\s+pod};
my $stop  = qr{^.*#\s*endif\s*/\*\s*pod\s*\*/};
my $trim  = qr{^\s*};
my $verb  = qr{^\s*=v\s};
my $show  = 0;

while ( my $line = <DATA> ) {
    if ( $line =~ $start ) {
        $show = 1;
        next;
    }
    if ( $line =~ $stop ) {
        $show = 0;
        next;
    }
    if ($show) {
        chomp($line);
        $line =~ s/$trim//;
        $line =~ s/$verb//;
        print $line, "\n";
    }
}

__DATA__
    This could be anything
    #ifdef pod
    =head2 title
    blah, blah,blah

    =v  indent 1
    #endif /* pod */
    This could be anything, too
[download]