This message deals strictly with the syntax of '#='-based POD; the semantics is a separate issue.
-- I'd like '#=' to follow similar rules to what '#' follows, with the caveat that a line beginning with '#' counts as a single-line comment no matter what the second character is. Specifically, having the second character be an = does not transform a full-line comment into a single line of documentation. This preserves the ability to comment out a series of lines by prepending a '#' to each of them without having to worry about whether or not any given line will start doing strange things. This means that '#=' can never appear at the start of the line if you want it to denote documentation; but anywhere else is fine. This should be a simple enough rule for a POD parser to handle with minimal trouble. There are additional complications that arise with '#=', such as: say '#='; In order to keep a POD parser from having to parse the code as well, we'd want to say that the #= sequence initiates a POD block that extends to the end of the line. IOW, the POD parser would end up with: CODE: say ' POD: '; But if that's the case, how would you ever actually print the character sequence '#='? Conversely, if you say that the fact that it's within a string literal means that it counts as string characters rather than the start of some POD, the POD parser will need to know how to identify string literals - which, as Perl illustrates, may not be a simple task. A possible middle ground might be to say that '#=' starts some POD, but (e.g.) '\#=' doesn't: where a POD extractor would remove '#=' and the following POD from the resulting code, it would replace '\#=' with '#='. So to actually display the '#=' character sequence, you'd say: say '\#='; With this in play, you can place '#='-based POD literally anywhere except at the beginning of a line. -- With this in mind, I'd propose two forms of '#=', based on what comes after the '='. If it is followed by one or more '['s, you have bracketed POD which is terminated by an equal number of ']'s; otherwise, you have POD which is terminated at the end of the current line. Note that I specifically said '[' rather than 'a bracketing character'; this is for the same reason that 'C<code>' is POD markup, but 'C{code}' isn't. As well, I chose '[' instead of '<' to minimize the need to double or triple up on the encapsulating brackets whenever inline POD markup is involved. Compare: #=<<This text has I<italics>!>> #=[This text has I<italics>!] #=<<<C<<$x>5>>>>> #=[C<<$x>5>>] Conversely: #=<$x[5] = 7> #=[[$x[5] = 7]] ...which isn't too bad IMHO (and is pretty close to a worst-case scenario). Finally, I'd want bracketed POD to follow indentation rules similar to what Hinrik suggested above: if the '#=' is preceded by nothing but whitespace and every line within the bracketed POD starts with at least as much whitespace, trim the shortest whitespace off of every line within the POD. -- Again, note that the above addresses only the syntax of '#='-based POD, and not the semantics. -- Jonathan "Dataweaver" Lang