From rmb1@cise.npl.co.uk

  % perldoc perlvar
gives
  ** Unterminated C<...> at .../pod/perlvar.pod line 188
  ** Unterminated C<...> at .../pod/perlvar.pod line 188
  ** Unterminated C<...> at .../pod/perlvar.pod line 424

This is due to C<@​-> and the like.

Patch below

Robin

--- pod/perlvar.pod 2000/01/24 14​:28​:49 1.1
+++ pod/perlvar.pod 2000/01/24 14​:33​:31 1.2
@​@​ -185,7 +185,7 @​@​
$+[&gt;I&lt;n&gt;C&lt;] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#+> to find the number
of subgroups in the last successful match. Contrast with
-C<$#->, the last I<matched> subgroup. Compare with C<@​->.
+C<$#-Z<>>, the last I<matched> subgroup. Compare with C<@​-Z<>>.

=item $MULTILINE_MATCHING

@​@​ -421,7 +421,7 @​@​
Thus after a match against $_, $&amp; coincides with C<substr $_, $-[0],
$+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
$+[&gt;I&lt;n&gt;C&lt;] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-> to find the last
+C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-Z<>> to find the last
matched subgroup in the last successful match. Contrast with
C<$#+>, the number of subgroups in the regular expression. Compare
with C<@​+>.

Site configuration information for perl 5.00563:

Configured by rmb1 at Mon Jan 10 17:12:56 GMT 2000.

Summary of my perl5 (revision 5.0 version 5 subversion 63) configuration:
  Platform:
    osname=solaris, osvers=2.7, archname=sun4-solaris
    uname='sunos tempest 5.7 generic_106541-04 sun4u sparc sunw,ultra-5_10 '
    config_args=''
    hint=recommended, useposix=true, d_sigaction=define
    usethreads=undef useperlio=define d_sfio=undef
    use64bits=define usemultiplicity=undef
  Compiler:
    cc='cc', optimize='-O -g', gccversion=2.95.1 19990816 (release)
    cppflags='-DDEBUGGING -fno-strict-aliasing -I/usr/local/include -I/opt/gnu/include'
    ccflags ='-DDEBUGGING -fno-strict-aliasing -I/usr/local/include -I/opt/gnu/include -DUSE_LONG_LONG -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'
    stdchar='char', d_stdstdio=define, usevfork=false
    intsize=4, longsize=4, ptrsize=4, doublesize=8
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
    alignbytes=8, usemymalloc=y, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -L/usr/local/lib -L/opt/gnu/lib '
    libpth=/usr/local/lib /opt/gnu/lib /lib /usr/lib /usr/ccs/lib
    libs=-lsocket -lnsl -ldl -lm -lc -lcrypt -lsec
    libc=/lib/libc.so, so=so, useshrplib=false, libperl=libperl.a
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags=' '
    cccdlflags='-fPIC', lddlflags='-G -L/usr/local/lib -L/opt/gnu/lib'

Locally applied patches:
    


@INC for perl 5.00563:
    /home/rmb1/appl/lib/perl5/site_perl/5.005/sun4-solaris
    /home/rmb1/appl/lib/perl5/site_perl/5.005
    /home/rmb1/appl/lib/perl5/5.00563/sun4-solaris
    /home/rmb1/appl/lib/perl5/5.00563
    /home/rmb1/appl/lib/site_perl/5.00563/sun4-solaris
    /home/rmb1/appl/lib/site_perl
    .


Environment for perl 5.00563:
    HOME=/home/rmb1
    LANG=C
    LANGUAGE (unset)
    LD_LIBRARY_PATH=/usr/lib
    LOGDIR (unset)
    PATH=/home/rmb1/appl/script:/usr/tempest/bin:/usr/local/bin:/usr/local/Admigration/exec:/usr/local/hotjava/bin:/usr/openwin/bin:/usr/dt/bin:/usr/ccs/bin:/usr/bin
    PERL5LIB=/home/rmb1/appl/lib/perl5/site_perl/5.005
    PERL_BADLANG (unset)
    SHELL=/bin/csh

From @tamias

On Mon, Jan 24, 2000 at 02​:41​:44PM +0000, Robin Barker wrote​:

% perldoc perlvar

gives
** Unterminated C<...> at .../pod/perlvar.pod line 188
** Unterminated C<...> at .../pod/perlvar.pod line 188
** Unterminated C<...> at .../pod/perlvar.pod line 424

This is due to C<@​-> and the like.

Patch below

-C<$#->, the last I<matched> subgroup. Compare with C<@​->.
+C<$#-Z<>>, the last I<matched> subgroup. Compare with C<@​-Z<>>.

-C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-> to find the last
+C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-Z<>> to find the last

Why can't the POD parser be fixed, rather than hacking the POD? POD is
supposed to be readable; C<@​-Z<>> and C<$#-Z<>> are not readable.

Ronald

From [Unknown Contact. See original ticket]

Ronald J Kimball writes​:

\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 188
\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 188
\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 424

This is due to C<@​-> and the like.

Patch below

Why can't the POD parser be fixed, rather than hacking the POD? POD is
supposed to be readable; C<@​-Z<>> and C<$#-Z<>> are not readable.

This is another indication that the idea of allowing -> and => inside
a group is a broken idea.

Ilya

From @tamias

[CC'ed to pod-people -- doc patch changed C<@​-> to C<@​-Z<>> to avoid
Unterminated C<...> errors.]

On Mon, Jan 24, 2000 at 03​:04​:16PM -0500, Ilya Zakharevich wrote​:

Ronald J Kimball writes​:

\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 188
\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 188
\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 424

This is due to C<@​-> and the like.

Patch below

Why can't the POD parser be fixed, rather than hacking the POD? POD is
supposed to be readable; C<@​-Z<>> and C<$#-Z<>> are not readable.

This is another indication that the idea of allowing -> and => inside
a group is a broken idea.

Ah, so the problem is a choice between C<@​-Z<>> and C<$a-E<gt>[0]>, neither
of which is particularly readable.

I propose a third solution, which I think preserves the simplicity and
readability of POD.

Code sections (and others, if desired) may begin with one or more
consecutive left angle brackets, and are terminated by the same number of
consecutive right angle brackets. Within the code section, any lesser
number of consecutive angle brackets is ignored (unless, of course, they're
part of a nested section). Other than at the beginning and end of a
section, angles would _not_ nest.

The above two examples would become​:

C<@​->
C<<$a->[0]>>

And other examples​:

C<<{ key => 'value' }>>
C<<<$b >> 4>>>

However, this would be a problem for a code section such as C<<>. In that
situation C<E<lt>> would then be necessary. (Also, C<E<gt>> would still be
necessary, as before.) So this solution is not perfect either. But I'll
put it out for consideration.

Ronald

From [Unknown Contact. See original ticket]

Ilya Zakharevich wrote​:

Ronald J Kimball writes​:

\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 188
\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 188
\*\* Unterminated C\<\.\.\.> at \.\.\./pod/perlvar\.pod line 424

This is due to C<@​-> and the like.

Patch below

Why can't the POD parser be fixed, rather than hacking the POD? POD is
supposed to be readable; C<@​-Z<>> and C<$#-Z<>> are not readable.

This is another indication that the idea of allowing -> and => inside
a group is a broken idea.

Could pod learn a little from perl? Make C<...> work like m<...> by
accepting any delimiters? C[@​-] and C[->] don't look so bad. And it's
gotta be easier than handling C<->> properly.

Hm. On second thought​:

% fgrep 'C|' *.pod | less
perlfaq5.pod​: sysopen(FH, $path, O_WRONLY|O_TRUNC|O_CREAT) ||
die $!;
perlfaq5.pod​: sysopen(FH, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666) ||
die $!;

Ok, how about just C(...) in addition? Or something. Or use Q<C[...]>,
where [] are arbitrary (Quoted C<>).

Um. Q<C[->]>. Looks like I may have won the battle and lost the war.
Hey, it still looks better than C<$#-Z<>>!

From [Unknown Contact. See original ticket]

On Mon, Jan 24, 2000 at 11​:28​:52PM -0500, Ronald J Kimball wrote​:

Ah, so the problem is a choice between C<@​-Z<>> and C<$a-E<gt>[0]>, neither
of which is particularly readable.

So why not come up with a patch to the regular expression in Pod​::Parser
so that neither one is required?

I'm the first one to say how much I dislike having that code inside
Pod​::Parser to hack things up to allow -> and => in certain cases. I'm
also the first one to admit the overwhelmingly vast majority of p5p
was pretty insistent upon it at the time - which is why I coded it up
anyway, even though my own preference and instincts went against it.

Code sections (and others, if desired) may begin with one or more
consecutive left angle brackets, and are terminated by the same number of
consecutive right angle brackets. Within the code section, any lesser
number of consecutive angle brackets is ignored (unless, of course, they're
part of a nested section). Other than at the beginning and end of a
section, angles would _not_ nest.

Zoinks - I don't care for that at all. I think it is far more limiting and
restrictive than is necessary. Why not just try to be more precise about
the circumstances under which '>' does NOT terminate a C<...>. Maybe
its not enough to simply be '->' or '=>', perhaps we only want to allow
certain classes of characters to be to the left of '->' and '=>' and
maybe only a select few punctuation characters are in that set.

Thats a heckuva lot more accommodating and less restrictive than
forbidding most forms of nesting (something which I'm not willing to do
because Pod​::Parser gets used for lots more stuff than just translation
and removing the nesting will break lots of code that I personally have
a stake in).

--
Brad Appleton <bradapp@​enteract.com> http​://www.enteract.com/~bradapp/
  "And miles to go before I sleep." -- Robert Frost

From @tamias

On Mon, Jan 24, 2000 at 10​:51​:28PM -0600, Brad Appleton wrote​:

On Mon, Jan 24, 2000 at 11​:28​:52PM -0500, Ronald J Kimball wrote​:

Ah, so the problem is a choice between C<@​-Z<>> and C<$a-E<gt>[0]>, neither
of which is particularly readable.

So why not come up with a patch to the regular expression in Pod​::Parser
so that neither one is required?

I'm concerned that someone may find another exception, and then another,
and then another, and soon POD parsing becomes extremely complicated.

I'm the first one to say how much I dislike having that code inside
Pod​::Parser to hack things up to allow -> and => in certain cases. I'm
also the first one to admit the overwhelmingly vast majority of p5p
was pretty insistent upon it at the time - which is why I coded it up
anyway, even though my own preference and instincts went against it.

I can understand the desire, perhaps even the need, for it.
C<$ref-E<gt>[0]> is hard to read.

Code sections (and others, if desired) may begin with one or more
consecutive left angle brackets, and are terminated by the same number of
consecutive right angle brackets. Within the code section, any lesser
number of consecutive angle brackets is ignored (unless, of course, they're
part of a nested section). Other than at the beginning and end of a
section, angles would _not_ nest.

Zoinks - I don't care for that at all. I think it is far more limiting and
restrictive than is necessary. Why not just try to be more precise about
the circumstances under which '>' does NOT terminate a C<...>. Maybe
its not enough to simply be '->' or '=>', perhaps we only want to allow
certain classes of characters to be to the left of '->' and '=>' and
maybe only a select few punctuation characters are in that set.

This has the drawback of trading simplicity for readibility. I think it
would create too many special cases to remember. As a start, the
characters that would have to be allowed before -> and => would include
[\w '\]}]. Of course, -> can follow any variable name, so these would both
be legal code -- $x-&gt;[0] , $@​->[0] -- but only one could put in a C<>
block as is. (Note that the second case may be quite common with exception
objects.)

Thats a heckuva lot more accommodating and less restrictive than
forbidding most forms of nesting (something which I'm not willing to do
because Pod​::Parser gets used for lots more stuff than just translation
and removing the nesting will break lots of code that I personally have
a stake in).

I'm not sure what you mean by "removing the nesting"... Is C<a<b>c> an
entire code section, including c>? If that's the case, there's no reason
to change it. I was under the impression that bare angle brackets did not
nest, which is why I stated it that way. My mistake.

In that case, under my proposal, C<<a<b>> would be an unterminated code
block.

Actually, I think the subtlest problem to my proposal is that someone might
try to represent the comparison operator as C<<=>>, which would actually be
the assignment operator. Hmm.

Ronald

From [Unknown Contact. See original ticket]

Brad Appleton <bradapp@​enteract.com> writes​:

On Mon, Jan 24, 2000 at 11​:28​:52PM -0500, Ronald J Kimball wrote​:

Ah, so the problem is a choice between C<@​-Z<>> and C<$a-E<gt>[0]>, neither
of which is particularly readable.

So why not come up with a patch to the regular expression in Pod​::Parser
so that neither one is required?

I'm the first one to say how much I dislike having that code inside
Pod​::Parser to hack things up to allow -> and => in certain cases. I'm
also the first one to admit the overwhelmingly vast majority of p5p
was pretty insistent upon it at the time - which is why I coded it up
anyway, even though my own preference and instincts went against it.

Seems like "we" have changed our minds on that one ;-)

Code sections (and others, if desired) may begin with one or more
consecutive left angle brackets, and are terminated by the same number of
consecutive right angle brackets. Within the code section, any lesser
number of consecutive angle brackets is ignored (unless, of course, they're
part of a nested section). Other than at the beginning and end of a
section, angles would _not_ nest.

Zoinks - I don't care for that at all. I think it is far more limiting and
restrictive than is necessary. Why not just try to be more precise about
the circumstances under which '>' does NOT terminate a C<...>. Maybe
its not enough to simply be '->' or '=>', perhaps we only want to allow
certain classes of characters to be to the left of '->' and '=>' and
maybe only a select few punctuation characters are in that set.

Thats a heckuva lot more accommodating and less restrictive than
forbidding most forms of nesting (something which I'm not willing to do
because Pod​::Parser gets used for lots more stuff than just translation
and removing the nesting will break lots of code that I personally have
a stake in).

Nesting is good. It is particularly natural for HTML/XML back ends.

--
Nick Ing-Simmons

From @TimToady

Ronald J Kimball writes​:
: I can understand the desire, perhaps even the need, for it.
: C<$ref-E<gt>[0]> is hard to read.

Seems like we need a better delimiter, like C<>$ref->[0]<> or something.

: Actually, I think the subtlest problem to my proposal is that someone might
: try to represent the comparison operator as C<<=>>, which would actually be
: the assignment operator. Hmm.

In this approach, that'd be

  C<><=><>

vs

  C<=>

The only thing you wouldn't be able to represent is <>, which unfortunately
can't be represented as C<><Z<>><> either. Hmm.

Alternately, there are actually very few places in all the standard pods
that match /\b[A-Z]\[/, and most of those are in verbatim paragraphs.
So maybe we just need to ordain C[<=>] as an alternative way to quote.
But then the first example above doesn't work.

Here's a wacky idea. If you say C<>, then the next character after that
is the quote character. Or how 'bout something that says the next thing
gets to choose its own quote​: Q<>C{$ref->[1]}

Actually, here's another interesting idea. Make a rule that if the
first thing in C< is a space, then the last thing in it has to be a
space too. So you get C< -> > and C< <> > and C< $ref->[1] >. That's
pretty darn close to optimal on readability. Now the only thing you
have problems with is > itself, which would still be C<>> or some
such. So far there are only about six occurrences of "C< " in the
standard docs, and they'd be easy to patch.

Unfortunately, this doesn't generalize well to the other letter escapes.

But strippable spaces might generalize better if you pick some other
character that is unlikely to follow <. We could have

  C<​: $ref->[0] :>
  C<​: <=> :>
  B<​: -w :>
  I<​: not :>

etc. There are no occurrences of /\b[a-z]<​: / in the standard docs
as far as I can tell.

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 >>

This is POD. This is your brain on POD. Any questions?

Larry

From [Unknown Contact. See original ticket]

On Wed, Jan 26, 2000 at 05​:01​:17PM -0800, Larry Wall wrote​:

But strippable spaces might generalize better if you pick some other
character that is unlikely to follow <. We could have

C\<&#8203;: $ref\->\[0\] :>
C\<&#8203;: \<=> :>
B\<&#8203;: \-w :>
I\<&#8203;: not :>

etc. There are no occurrences of /\b[a-z]<​: / in the standard docs
as far as I can tell.

So is this saying that any whitespace after /[A-Z]<​:/ and before the
corresponding /​:>/ are not only stripped (by the parser) but are
required? Or is the whitespace optional here? Is C<​: <=> :> the
same as C<​:<=>​:>?

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 >>

This is in addition to the above? (and here the whitespace is
definitely required.)

This is POD. This is your brain on POD. Any questions?

I definitely like both of these *LOTS* better then the existing
setup that special cases '->' and '=>' inside C<...>. So instead
of looking for /\b[A-Z]</ to start a sequence I instead look for​:

  /\b[A-Z]<([<​:]\s+)?/

I think I can do that. And it looks SO MUCH NICER than the other
stuff thats been both implemented and tossed about. Why - it almost
looks as plain as POD is supposed to look ;-)

If someone makes the appropriate changes to perlpod.pod, I will
do my best to modify Pod​::Parser to accommodate the new spec
just as soon as possible.

--
Brad Appleton <bradapp@​enteract.com> http​://www.enteract.com/~bradapp/
  "And miles to go before I sleep." -- Robert Frost

From [Unknown Contact. See original ticket]

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 <bradapp@​enteract.com> 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