develooper Front page | perl.perl5.porters | Postings from February 2000

Re: [p5p] proposed perlpod.pod patch

Thread Next
Brad Appleton
February 4, 2000 10:34
Re: [p5p] proposed perlpod.pod patch
Message ID:
On Thu, Feb 03, 2000 at 06:37:05PM -0600, Brad Appleton wrote:
> Okay - here is my attempt at writing up what the changes would be to
> perlpod.pod. This is simply a stab at the docs for what Larry proposed
> above. I want to nail down how the spec will read before I spend too
> much time implementing it.

Wolfgang Laun noted that even C<< ... >> will potentially break some
existing pods. He was think of a sequence he's seen some use to indicate
a return value of less-than-zero: C<< 0>. This is currently valid POD.
Adding C<< ... >> would mean it has to be rewritten as C<< < 0 >> (or
use the ugly E<lt>). Otherwise it will probably look like an unterminated
sequence. (we could always go back to Larry's earlier proposal of 
C<: ... :> if folks want).

However, I still like C<< ... >> quite a bit better than all the other
proposals (with C<: ... :> a close second). If p5p strongly feels I should
not implement the change described below, please speak up. Otherwise I'll
be adding it to Pod::Parser very shortly since it already has Larry's
approval (which of course Larry is free to rescind ;-)

Brad Appleton <bradapp@enteract.com
  "And miles to go before I sleep." -- Robert Frost

*** perlpod.pod.orig	Thu Feb  3 16:10:32 2000
--- perlpod.pod	Thu Feb  3 17:05:37 2000
*** 188,193 ****
--- 188,220 ----
      	    	    E<html>		Some non-numeric HTML entity, such
  					as E<Agrave>
+ Most of the time, you will only need a single set of angle brackets to
+ delimit the beginning and end of interior sequences. However, sometimes
+ you will want to put a right angle bracket (or greater-than sign '>')
+ inside of a sequence. This is particularly common when using a sequence
+ to provide a different font-type for a snippet of code. As with all
+ things in Perl, there is more than one way to do it. One way is to
+ simply escape the closing bracket using an C<E> sequence:
+     C<$a E<lt>=E<gt> $b>
+ This will produce: "C<$a E<lt>=E<gt> $b>"
+ A more readable, and perhaps more "plain" way is to use an alternate set of
+ delimiters that doesn't require a ">" to be escaped. As of perl5.5.641,
+ doubled angle brackets ("<<" and ">>") may be used I<if and only if there
+ is whitespace immediately following the opening delimiter and immediately
+ preceding the closing delimiter!> (And the whitespace must be something
+ other than a newline.) For example, the following will do the trick:
+     C<< $a <=> $b >>
+ This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
+ and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser
+ 1.093 or later.
  =head2 The Intent
  That's it.  The intent is simplicity, not power.  I wanted paragraphs

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About