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.