A better place might have been another top-level thread. But it's here now, so fine. Maybe start a new top-level thread once you have a design, asking for serious review, to attract fresh blood.

A utility to strip a certain amount of whitespace from each line is a completely generic thing and could be written as a pipe.

If each block might be indented differently, the preprocessor needs to identify them first and decide on the settings. So it might as well strip the leading space while extracting.

I'm worried about distinguishing verbatim blocks based on a different indent. It might be too easy to get things wrong, and get a bunch of stuff treated as verbatim when it should not be, or truncate or refuse to recognize stuff that's not indented enough.

So, for everything other than verbatim paragraphs, you should ignore whatever whitespace exists, whatever it may be. Once you indicate a POD region, shift everything left as far as it can go.

But then you need another way to indicate verbatim, other than a different indent! Do you expect much verbatim stuff within the file? Your synopsis and examples can be in other files, and only documentation for these specific functions go with those functions in the same file. So maybe it is rare enough that you don't mind a little more decoration.

To throw something out there, I'd suggest using =code, and then noting the position of that tag on the line, and removing the same amount of space from the start of subsequent lines. A line indented less than that amount, for any purpose, indicates that the verbatim section has ended. Allow blank lines within the verbatim, without worrying about matching the whitespace on such an "empty" line.

Your example of putting a decoration at the start of every line, I think would get tiring to do.

I like the idea of combining a flag with the #ifdef, so you don't need a separate =pod line, and you can check just the flagged blocks and not the whole file or all conditioned-out code.

     #ifdef POD
     Plain flowing paragraph assumed if no directive found within this
+ block.
             Indent doesn't
    matter at all
      since the paragraph flows anyway!
     #endif  // no =cut needed
[download]

Basically, the implicit plain paragraph and the implicit cut are both automatic fallout from the idea of copying the special blocks. Whatever was copied is treated normally, and that means a plain paragraph. You don't need =end to go back to code, since the preprocessor has its own rules to decide what to take.

Just be sure to add a blank line between each copied block in the output, and it will all work out.

Write your code as a module. Write the simple .pl that uses the module to take input and output file parameters OR easily act as a filter, OR take file names as command arguments and writing to standard output: that will allow you to use a pipe-file notation as the file name with existing tools to process POD files!

You said you worried about a false #endif in the middle of the POD. In a plain paragraph, just don't do that! Wrap it so # is not at the start of a line, and I.A.C. it would probably have C<…> wrapped around it anyway.

To handle a verbatim paragraph, allow a leading ~# to be transformed into # on output.

That's all I can think of. Best of luck!

–John