Misuse of "quote" in place of "escape" in documentation #15221

p5pRT · 2016-03-10T15:53:50Z

Migrated from rt.perl.org#127687 (status was 'open')

Searchable as RT127687$

p5pRT · 2016-03-10T15:53:50Z

From the.rob.dixon@gmail.com

This is a bug report for perl from the.rob.dixon@gmail.com,
generated with the help of perlbug 1.40 running under perl 5.22.1.

This issue came to light with regard to this Stack Overflow solution

http://stackoverflow.com/a/35918358/622310

The specific context id the perlre POD, but there may well be other
examples elsewhere in the documentation

I submit that using "quoting" when you mean "escaping" is a useless
synonym, and ultimately confusing when talking about character strings. If
I am asked to ôquote '['ö do I mean ô"["ö or ô\[ö?

The OP who wrote the item referenced above claimed that the two are
interchangeable and referred to `perlre` in his defence. Unfortunately he
is right, and we also have the \Q construction ù presumably short for
"quote" ù and the `quotemeta` function as legacies to deal with

But the narrative in `perlre` could be much improved, especially because it
talks a lot about things like ôquote-like operatorsö and ôdouble-quoted
stringsö

All of the following references refer to v5.22.1 of perlre.pod, and I think
`metaquoting` ù as in this example on line 1036 of perlre.pod ù is
acceptable although VERY unusual

Line 553
\ Quote the next metacharacter
should be
\ Escape the next metacharacter

Line 686
\Q quote (disable) pattern metacharacters until \E
should be
\Q escape (disable) pattern metacharacters until \E

Line 687
\E end either case modification or quoted section, think vi
should be
\E end either case modification or escaped section, think vi

Line 1021
=head2 Quoting metacharacters
should be
=head2 Escaping metacharacters

Lines 1027 .. 1030
interpreted as a literal character, not a metacharacter. This was
once used in a common idiom to disable or quote the special meanings
of regular expression metacharacters in a string that you want to
use for a pattern. Simply quote all non-"word" characters:
should be
interpreted as a literal character, not a metacharacter. This was
once used in a common idiom to disable or escape the special meanings
of regular expression metacharacters in a string that you want to
use for a pattern. Simply escape all non-"word" characters:

Line 1039
/$unquoted\Q$quoted\E$unquoted/
should be
/$unescaped\Q$escaped\E$unescaped/

Flags:
category=docs
severity=low

Site configuration information for perl 5.22.1:

Configured by strawberry-perl at Mon Dec 14 22:59:01 2015.

Summary of my perl5 (revision 5 version 22 subversion 1) configuration:

Platform:
osname=MSWin32, osvers=6.3, archname=MSWin32-x64-multi-thread
uname='Win32 strawberry-perl 5.22.1.1 #1 Mon Dec 14 22:56:01 2015 x64'
config_args='undef'
hint=recommended, useposix=true, d_sigaction=undef
useithreads=define, usemultiplicity=define
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
-fwrapv -fno-strict-aliasing -mms-bitfields',
optimize='-s -O2',
cppflags='-DWIN32'
ccversion='', gccversion='4.9.2', gccosandvers=''
intsize=4, longsize=4, ptrsize=8, doublesize=8, byteorder=12345678,
doublekind=3
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16,
longdblkind=3
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:\STRAWB1\perl\lib\CORE"
-L"C:\STRAWB1\c\lib"'
libpth=C:\STRAWB~~1\c\lib C:\STRAWB~~1\c\x86_64-w64-mingw32\lib
C:\STRAWB1\c\lib\gcc\x86_64-w64-mingw32\4.9.2
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=libperl522.a
gnulibc_version=''
Dynamic Linking:
dlsrc=dl_win32.xs, dlext=xs.dll, d_dlsymun=undef, ccdlflags=' '
cccdlflags=' ', lddlflags='-mdll -s -L"C:\STRAWB1\perl\lib\CORE"
-L"C:\STRAWB~1\c\lib"'

@INC for perl 5.22.1:
C:/Strawberry/perl/site/lib/MSWin32-x64-multi-thread
C:/Strawberry/perl/site/lib
C:/Strawberry/perl/vendor/lib
C:/Strawberry/perl/lib
.

Environment for perl 5.22.1:
HOME (unset)
LANG (unset)
LANGUAGE (unset)
LD_LIBRARY_PATH (unset)
LOGDIR (unset)

PATH=C:\ProgramData\Oracle\Java\javapath;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Program
Files (x86)\NVIDIA
Corporation\PhysX\Common;C:\Strawberry\c\bin;C:\Strawberry\perl\site\bin;C:\Strawberry\perl\bin;C:\Program
Files (x86)\Calibre2\;C:\Program Files (x86)\EaseUS\Todo
Backup\bin;C:\Git\cmd;C:\SQLite;C:\Tcl\bin;C:\Python27;C:\ffmpeg\bin;C:\rtmpdump\bin;C:\get_iplayer;C:\UnxUtils\usr\local\wbin;C:\GnuWin32\bin;E:\Perl\source\public
PERL_BADLANG (unset)
SHELL (unset)

p5pRT · 2016-03-10T15:59:34Z

From @demerphq

FWIW, ++ on this bug.

On 10 March 2016 at 16:53, Rob Dixon <perlbug-followup@perl.org> wrote:

# New Ticket Created by Rob Dixon
# Please include the string: [perl #127687]
# in the subject line of all future correspondence about this issue.
# <URL: https://rt-archive.perl.org/perl5/Ticket/Display.html?id=127687 >

This is a bug report for perl from the.rob.dixon@gmail.com,
generated with the help of perlbug 1.40 running under perl 5.22.1.

-----------------------------------------------------------------

This issue came to light with regard to this Stack Overflow solution
http&#8203;://stackoverflow\.com/a/35918358/622310
The specific context id the perlre POD, but there may well be other
examples elsewhere in the documentation

I submit that using "quoting" when you mean "escaping" is a useless
synonym, and ultimately confusing when talking about character strings. If
I am asked to ôquote '['ö do I mean ô"["ö or ô\[ö?

The OP who wrote the item referenced above claimed that the two are
interchangeable and referred to `perlre` in his defence. Unfortunately he
is right, and we also have the \Q construction ù presumably short for
"quote" ù and the `quotemeta` function as legacies to deal with

But the narrative in `perlre` could be much improved, especially because it
talks a lot about things like ôquote-like operatorsö and ôdouble-quoted
stringsö

All of the following references refer to v5.22.1 of perlre.pod, and I think
`metaquoting` ù as in this example on line 1036 of perlre.pod ù is
acceptable although VERY unusual

Line 553
\ Quote the next metacharacter
should be
\ Escape the next metacharacter

Line 686
\Q quote (disable) pattern metacharacters until \E
should be
\Q escape (disable) pattern metacharacters until \E

Line 687
\E end either case modification or quoted section, think vi
should be
\E end either case modification or escaped section, think vi

Line 1021
=head2 Quoting metacharacters
should be
=head2 Escaping metacharacters

Lines 1027 .. 1030
interpreted as a literal character, not a metacharacter. This was
once used in a common idiom to disable or quote the special meanings
of regular expression metacharacters in a string that you want to
use for a pattern. Simply quote all non-"word" characters:
should be
interpreted as a literal character, not a metacharacter. This was
once used in a common idiom to disable or escape the special meanings
of regular expression metacharacters in a string that you want to
use for a pattern. Simply escape all non-"word" characters:

Line 1039
/$unquoted\Q$quoted\E$unquoted/
should be
/$unescaped\Q$escaped\E$unescaped/

-----------------------------------------------------------------
---
Flags:
category=docs
severity=low
---
Site configuration information for perl 5.22.1:

Configured by strawberry-perl at Mon Dec 14 22:59:01 2015.

Summary of my perl5 (revision 5 version 22 subversion 1) configuration:

Platform:
osname=MSWin32, osvers=6.3, archname=MSWin32-x64-multi-thread
uname='Win32 strawberry-perl 5.22.1.1 #1 Mon Dec 14 22:56:01 2015 x64'
config_args='undef'
hint=recommended, useposix=true, d_sigaction=undef
useithreads=define, usemultiplicity=define
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
-fwrapv -fno-strict-aliasing -mms-bitfields',
optimize='-s -O2',
cppflags='-DWIN32'
ccversion='', gccversion='4.9.2', gccosandvers=''
intsize=4, longsize=4, ptrsize=8, doublesize=8, byteorder=12345678,
doublekind=3
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16,
longdblkind=3
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:\STRAWB1\perl\lib\CORE"
-L"C:\STRAWB1\c\lib"'
libpth=C:\STRAWB~~1\c\lib C:\STRAWB~~1\c\x86_64-w64-mingw32\lib
C:\STRAWB1\c\lib\gcc\x86_64-w64-mingw32\4.9.2
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=libperl522.a
gnulibc_version=''
Dynamic Linking:
dlsrc=dl_win32.xs, dlext=xs.dll, d_dlsymun=undef, ccdlflags=' '
cccdlflags=' ', lddlflags='-mdll -s -L"C:\STRAWB1\perl\lib\CORE"
-L"C:\STRAWB~1\c\lib"'

---
@INC for perl 5.22.1:
C:/Strawberry/perl/site/lib/MSWin32-x64-multi-thread
C:/Strawberry/perl/site/lib
C:/Strawberry/perl/vendor/lib
C:/Strawberry/perl/lib
.

---
Environment for perl 5.22.1:
HOME (unset)
LANG (unset)
LANGUAGE (unset)
LD_LIBRARY_PATH (unset)
LOGDIR (unset)

PATH=C:\ProgramData\Oracle\Java\javapath;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Program
Files (x86)\NVIDIA
Corporation\PhysX\Common;C:\Strawberry\c\bin;C:\Strawberry\perl\site\bin;C:\Strawberry\perl\bin;C:\Program
Files (x86)\Calibre2\;C:\Program Files (x86)\EaseUS\Todo
Backup\bin;C:\Git\cmd;C:\SQLite;C:\Tcl\bin;C:\Python27;C:\ffmpeg\bin;C:\rtmpdump\bin;C:\get_iplayer;C:\UnxUtils\usr\local\wbin;C:\GnuWin32\bin;E:\Perl\source\public
PERL_BADLANG (unset)
SHELL (unset)

--
perl -Mre=debug -e "/just|another|perl|hacker/"

p5pRT · 2016-03-10T15:59:35Z

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

p5pRT · 2016-03-16T00:24:58Z

From @tonycoz

http://stackoverflow.com/a/35918358/622310

The specific context id the perlre POD, but there may well be other
examples elsewhere in the documentation

I submit that using "quoting" when you mean "escaping" is a useless
synonym, and ultimately confusing when talking about character
strings. If
I am asked to ôquote '['ö do I mean ô"["ö or ô\[ö?

The OP who wrote the item referenced above claimed that the two are
interchangeable and referred to `perlre` in his defence. Unfortunately
he
is right, and we also have the \Q construction ù presumably short for
"quote" ù and the `quotemeta` function as legacies to deal with

"quote" semms to me to be the correct terminology.

We quote text to avoid any special meaning for that text, eg:

$x = exit;

vs

$x = "exit"

Emacs uses the quote-next operator to insert the next character typed literally.

Tony

p5pRT · 2016-04-21T01:42:07Z

From @jkeenan

On Tue Mar 15 17:24:58 2016, tonyc wrote:

http://stackoverflow.com/a/35918358/622310

The specific context id the perlre POD, but there may well be other
examples elsewhere in the documentation

I submit that using "quoting" when you mean "escaping" is a useless
synonym, and ultimately confusing when talking about character
strings. If
I am asked to ôquote '['ö do I mean ô"["ö or ô\[ö?

The OP who wrote the item referenced above claimed that the two are
interchangeable and referred to `perlre` in his defence.
Unfortunately
he
is right, and we also have the \Q construction ù presumably short for
"quote" ù and the `quotemeta` function as legacies to deal with

"quote" semms to me to be the correct terminology.

Tony, that suggests to me that you do not favor any documentation changes here.

If so, can we close this ticket?

We quote text to avoid any special meaning for that text, eg:

$x = exit;

vs

$x = "exit"

Emacs uses the quote-next operator to insert the next character typed
literally.

Tony

Thank you very much.

--
James E Keenan (jkeenan@cpan.org)

p5pRT · 2016-04-21T07:15:28Z

From @demerphq

On 21 April 2016 at 03:42, James E Keenan via RT
<perlbug-followup@perl.org> wrote:

On Tue Mar 15 17:24:58 2016, tonyc wrote:

http://stackoverflow.com/a/35918358/622310

The specific context id the perlre POD, but there may well be other
examples elsewhere in the documentation

I submit that using "quoting" when you mean "escaping" is a useless
synonym, and ultimately confusing when talking about character
strings. If
I am asked to ôquote '['ö do I mean ô"["ö or ô\[ö?

The OP who wrote the item referenced above claimed that the two are
interchangeable and referred to `perlre` in his defence.
Unfortunately
he
is right, and we also have the \Q construction ù presumably short for
"quote" ù and the `quotemeta` function as legacies to deal with

"quote" semms to me to be the correct terminology.

Tony, that suggests to me that you do not favor any documentation changes here.

If so, can we close this ticket?

I am not Tony, but I do not think we should close this.

We quote text to avoid any special meaning for that text, eg:

$x = exit;

vs

$x = "exit"

Emacs uses the quote-next operator to insert the next character typed
literally.

I think the use of quote like this is archaic and confusing.

In modern computing (and perl) terms IMO...

"to quote something" means "to place some marker around arbitrary
text", with the implication that the arbitrary text is going to be
treated as a string, and not some other possibly valid interpretation.

"to escape something" normally means "to prefix something such that it
is treated differently from its normal interpretation".

The key point here is that quoting normally involves a balanced
construct, wheras escaping involves an unbalanced prefix.

Further supporting the view that escaping and quoting something are
distinct is the fact that in perl you can only use an escape inside of
a quote-like construct. That alone says to me that quoting and
escaping should not be used interchangable, regardless of the name of
quotemeta, and the way that emacs uses the term "quote". The
alternative interpretation means that sometimes you have to quote
stuff that is inside of quotes, which is IMO much less helpful than to
say that sometimes you have to escape stuff that is inside of quotes.

So I am rather firmly in favour of the changes the OP requested.

Yves

Fixes Perl#15221 The documentation and comments was misleading about conflating quoting a metacharacter and escaping it. Since \Q stands for quote, we have to continue to use that terminology. This commit clarifies that the two terms are often equivalent.

Fixes Perl#15221 The documentation and comments were misleading about conflating quoting a metacharacter and escaping it. Since \Q stands for quote, we have to continue to use that terminology. This commit clarifies that the two terms are often equivalent. This also adds a note that quotemeta isn't affected by locale.

p5pRT added the Severity Low label Oct 19, 2019

xenu removed the Severity Low label Dec 29, 2021

khwilliamson linked a pull request May 6, 2025 that will close this issue

pod and comments: Note escape vs quote #23264

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Misuse of "quote" in place of "escape" in documentation #15221

Misuse of "quote" in place of "escape" in documentation #15221

p5pRT commented Mar 10, 2016

p5pRT commented Mar 10, 2016

p5pRT commented Mar 10, 2016

p5pRT commented Mar 10, 2016

p5pRT commented Mar 16, 2016

p5pRT commented Apr 21, 2016

p5pRT commented Apr 21, 2016

Misuse of "quote" in place of "escape" in documentation #15221

Misuse of "quote" in place of "escape" in documentation #15221

Comments

p5pRT commented Mar 10, 2016

p5pRT commented Mar 10, 2016

From the.rob.dixon@gmail.com

p5pRT commented Mar 10, 2016

From @demerphq

p5pRT commented Mar 10, 2016

p5pRT commented Mar 16, 2016

From @tonycoz

p5pRT commented Apr 21, 2016

From @jkeenan

p5pRT commented Apr 21, 2016

From @demerphq