On Sun, Aug 16, 2009 at 1:26 PM, Damian Conway<[email protected]> wrote:
> * This means Pod can be indented; the = is no longer tied to the
> first column. The indentation preceding the opening = (using the
> ($?TABSTOP // 8) rule, as for heredocs) now specifies the zeroth
> column of the Pod block.
Will ther be any ambiguity between Pod and wraparound operators that
begin with =? e.g.,
my Dog $spot
= new Dog; # Pod, or Perl assignment?
if really_long_expression
== value { ... } # Pod, or equality operator?
> * In addition to delimited, paragraphed, and abbreviated Pod blocks,
> documentation can now be specified in a fourth form:
>
> my $declared_thing; #= Pod here until end of line
>
> sub declared_thing () { #=[ Pod here
> until matching
> closing bracket
> ]
> ...
> }
Note the recent revisions to how Perl comments work - in particular,
an embedded comment is now spelled "#`[ ... ]". Should "embedded
attached Pod" be spelled as "#=`[ ... ]"? My preference would be to
simply say that if the very first character within a comment is an =,
then it becomes a Pod attachment. That is, we're not dealing with a
variation of the Pod Comment syntax (i.e., s/#/#=/); rather, we're
dealing with a special use of a normal comment. Thus, an embedded Pod
attachment would be written as "#`[=...]". The main benefit of this
would be that if any further refinements occur to Perl's comment
syntax, Pod will adapt to those changes seamlessly[1]. As well, this
would help with any effort that might be made to integrate the use of
Pod into other languages: e.g., Javascript-with-Pod would handle a Pod
attachment as "/*=...*/" or "//=..." (for embedded and end-of-line
comments, respectively).
--
Jonathan "Dataweaver" Lang
[1] Not to derail the conversation, but I would consider this to be
another argument in favor of the proposed '(#...)' syntax for embedded
comments: with this syntax, an embedded Pod attachment would be
spelled '(#=...)'. Much more aesthetically pleasing.
