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
