On Tue, Feb 01, 2000 at 12:59:28AM -0600, Brad Appleton wrote:
> On Wed, Jan 26, 2000 at 05:01:17PM -0800, Larry Wall wrote:
> > And now we come full circle back to C<< $ref->[0] >> because there are
> > no occurrences of /\b[A-Z]<< / in the docs either. So we just make
> > a rule that if you double the angle brackets, you have to add whitespace
> > around it too.
> >
> > C<< $ref->[0] >>
> > C<< <=> >>
> > B<< -w >>
> > I<< not >>
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.
Even if the doc-change is agreed upon, we still need to decide how many
pod2xxx translators need to be changed to use this before we can include
the doc-change in the perl core. Is it sufficient to have the change
implemented in all the pod2xxxx and Pod::Xxxx modules that are part of
the core (but not necessarily everywhere else?)
Here is the proposed "spec" after my signature ....
--
Brad Appleton <[EMAIL PROTECTED]> http://www.enteract.com/~bradapp/
"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
