From ronw.mrmx@gmail.com

I notice an inconsistency in perlpod.pod that is also present in the
Perl 5.18.2 documentation on perldoc.perl.org

In the section describing =encoding, there is the sentence​:

  And don't forget, when using any other command, that the command
  lasts up until the end of its paragraph, not its line.

There is no heading separating this from the description of =encoding
above it. So, this could be taken to mean that =encoding by itself,
between lines of Perl code, does not require a =cut

I ran a simple test program to confirm the behaviour of Perl. Lines
of code after =encoding, bit before =cut were ignored by Perl.

Perhaps a heading before that sentence could be added.

Flags:
    category=docs
    severity=low

Site configuration information for perl 5.16.3:

Configured by strawberry-perl at Tue Mar 12 12:12:58 2013.

Summary of my perl5 (revision 5 version 16 subversion 3) configuration:

  Platform:
    osname=MSWin32, osvers=4.0, archname=MSWin32-x64-multi-thread
    uname='Win32 strawberry-perl 5.16.3.1 #1 Tue Mar 12 12:12:07 2013 x64'
    config_args='undef'
    hint=recommended, useposix=true, d_sigaction=undef
    useithreads=define, usemultiplicity=define
    useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
    use64bitint=define, use64bitall=undef, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='gcc', ccflags =' -s -O2 -DWIN32 -DWIN64 -DCONSERVATIVE
-DPERL_TEXTMODE_SCRIPTS -DPERL_IMPLICIT_CONTEXT -DPERL_IMPLICIT_SYS
-fno-strict-aliasing -mms-bitfields',
    optimize='-s -O2',
    cppflags='-DWIN32'
    ccversion='', gccversion='4.6.3', gccosandvers=''
    intsize=4, longsize=4, ptrsize=8, doublesize=8, byteorder=12345678
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
    ivtype='long long', ivsize=8, nvtype='double', nvsize=8, Off_t='long
long', lseeksize=8
    alignbytes=8, prototype=define
  Linker and Libraries:
    ld='g++', ldflags ='-s -L"C:\Perl\perl\lib\CORE" -L"C:\Perl\c\lib"'
    libpth=C:\Perl\c\lib C:\Perl\c\x86_64-w64-mingw32\lib
    libs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32
-ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr
-lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32
    perllibs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32
-ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr
-lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32
    libc=, so=dll, useshrplib=true, libperl=libperl516.a
    gnulibc_version=''
  Dynamic Linking:
    dlsrc=dl_win32.xs, dlext=dll, d_dlsymun=undef, ccdlflags=' '
    cccdlflags=' ', lddlflags='-mdll -s -L"C:\Perl\perl\lib\CORE"
-L"C:\Perl\c\lib"'

Locally applied patches:



@INC for perl 5.16.3:
    c:/Perl/perl/site/lib
    c:/Perl/perl/vendor/lib
    c:/Perl/perl/lib
    .


Environment for perl 5.16.3:
    HOME (unset)
    LANG (unset)
    LANGUAGE (unset)
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=c:\perl\perl\bin;c:\perl\c\bin;C:\Program Files\SlickEditV18.0.1
x64\win\;%SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0\;C:\Program
Files\doxygen\bin
    PERL_BADLANG (unset)
    SHELL (unset)

From @khwilliamson

How about the attached patch?
--
Karl Williamson

From @khwilliamson

From 0cd922e8ae56bdf29e8cf21481b4185589dc7beb Mon Sep 17 00:00:00 2001
From: Karl Williamson <khw@cpan.org>
Date: Mon, 28 Apr 2014 14:10:37 -0600
Subject: [PATCH 20/20] PATCH: [perl #121630]: perlpod clarification

---
 pod/perlpod.pod | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 7333fcc..0a55ffd 100644
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -296,14 +296,16 @@ module.  Examples:
 
   =encoding big5
 
-=back
-
 C<=encoding> affects the whole document, and must occur only once.
 
-And don't forget, when using any other command, that the command lasts up
+=back
+
+And don't forget, all commands but C<=encoding> last up
 until the end of its I<paragraph>, not its line.  So in the
 examples below, you can see that every command needs the blank
-line after it, to end its paragraph.
+line after it, to end its paragraph.  (And some older
+Pod translators may require the C<=encoding> line to be similarly
+separated.)
 
 Some examples of lists include:
 
-- 
1.8.3.2

The RT System itself - Status changed from 'new' to 'open'

From ronw.mrmx@gmail.com

Looks good. Thanks for replying.

On Mon, Apr 28, 2014 at 4​:13 PM, Karl Williamson via RT <
perlbug-followup@​perl.org> wrote​:

How about the attached patch?
--
Karl Williamson

From 0cd922e8ae56bdf29e8cf21481b4185589dc7beb Mon Sep 17 00​:00​:00 2001
From​: Karl Williamson <khw@​cpan.org>
Date​: Mon, 28 Apr 2014 14​:10​:37 -0600
Subject​: [PATCH 20/20] PATCH​: [perl #121630]​: perlpod clarification

---
pod/perlpod.pod | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 7333fcc..0a55ffd 100644
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@​@​ -296,14 +296,16 @​@​ module. Examples​:

=encoding big5

-=back
-
C<=encoding> affects the whole document, and must occur only once.

-And don't forget, when using any other command, that the command lasts up
+=back
+
+And don't forget, all commands but C<=encoding> last up
until the end of its I<paragraph>, not its line. So in the
examples below, you can see that every command needs the blank
-line after it, to end its paragraph.
+line after it, to end its paragraph. (And some older
+Pod translators may require the C<=encoding> line to be similarly
+separated.)

Some examples of lists include​:

--
1.8.3.2

From @jkeenan

On Thu Apr 10 09​:46​:52 2014, ronw.mrmx@​gmail.com wrote​:

I notice an inconsistency in perlpod.pod that is also present in the
Perl 5.18.2 documentation on perldoc.perl.org

In the section describing =encoding, there is the sentence​:

And don't forget, when using any other command, that the command
lasts up until the end of its paragraph, not its line.

There is no heading separating this from the description of =encoding
above it. So, this could be taken to mean that =encoding by itself,
between lines of Perl code, does not require a =cut

I ran a simple test program to confirm the behaviour of Perl. Lines
of code after =encoding, bit before =cut were ignored by Perl.

Would it be possible for you to post that simple test program as an attachment?

Perhaps a heading before that sentence could be added.

Thank you very much.
Jim Keenan

From @jkeenan

On Sat May 17 09​:40​:39 2014, jkeenan wrote​:

On Thu Apr 10 09​:46​:52 2014, ronw.mrmx@​gmail.com wrote​:

I notice an inconsistency in perlpod.pod that is also present in the
Perl 5.18.2 documentation on perldoc.perl.org

In the section describing =encoding, there is the sentence​:

And don't forget, when using any other command, that the command
lasts up until the end of its paragraph, not its line.

There is no heading separating this from the description of =encoding
above it. So, this could be taken to mean that =encoding by itself,
between lines of Perl code, does not require a =cut

I ran a simple test program to confirm the behaviour of Perl. Lines
of code after =encoding, bit before =cut were ignored by Perl.

Would it be possible for you to post that simple test program as an
attachment?

Ignore the above. I didn't see that khw had supplied a patch.

Thank you very much.
Jim Keenan

From @khwilliamson

On Sat May 17 09​:42​:28 2014, jkeenan wrote​:

On Sat May 17 09​:40​:39 2014, jkeenan wrote​:

On Thu Apr 10 09​:46​:52 2014, ronw.mrmx@​gmail.com wrote​:

Ignore the above. I didn't see that khw had supplied a patch.

Thank you very much.
Jim Keenan

But I didn't either see ron's favorable response, or just plumb forgot to apply that patch. So thanks for the reminder. Now applied as commit
e023b52
--
Karl Williamson

From @jkeenan

On Sat May 17 11​:35​:00 2014, khw wrote​:

On Sat May 17 09​:42​:28 2014, jkeenan wrote​:

On Sat May 17 09​:40​:39 2014, jkeenan wrote​:

On Thu Apr 10 09​:46​:52 2014, ronw.mrmx@​gmail.com wrote​:

Ignore the above. I didn't see that khw had supplied a patch.

Thank you very much.
Jim Keenan

But I didn't either see ron's favorable response, or just plumb forgot
to apply that patch. So thanks for the reminder. Now applied as
commit
e023b52

Karl, is this ticket now closable?

Thank you very much.
jimk

From @khwilliamson

Thanks for the reminder; now closing
--
Karl Williamson

@khwilliamson - Status changed from 'open' to 'resolved'