On Sun, Aug 16, 2009 at 1:26 PM, Damian Conway<dam...@conway.org> 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.

Reply via email to