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

[p5pRT]

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

Searchable as RT127687$

[p5pRT]

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​:\STRAWB1\c\lib C​:\STRAWB1\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]

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​://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​:\STRAWB1\c\lib C​:\STRAWB1\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]

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

[p5pRT]

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]

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]

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