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

Reply via email to