search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.85k stars 523 forks source link

[PATCH pod/perlop.pod 5.5.64] There is no qr// man page #1134

Closed p5pRT closed 20 years ago

p5pRT commented 24 years ago

Migrated from rt.perl.org#2094 (status was 'resolved')

Searchable as RT2094$

p5pRT commented 24 years ago

From @schwern

perlop mistakenly had a link to 'the qr// man page'. This changes it to 'the section on qr//'

--- pod/perlop.pod 2000/02/04 03​:34​:46 +++ pod/perlop.pod 2000/02/04 03​:35​:17 @​@​ -789\,7 +789\,7 @​@​ and is useful when the value you are interpolating won't change over the life of the script. However\, mentioning C\ constitutes a promise that you won't change the variables in the pattern. If you change them\, -Perl won't even notice. See also L\<qr//>. +Perl won't even notice. See also L\<"qr//">.

If the PATTERN evaluates to the empty string\, the last I\ matched regular expression is used instead.

-- Summary of my perl5 (revision 5.0 version 5 subversion 640) configuration​:   Platform​:   osname=linux\, osvers=2.2.10\, archname=i686-linux   uname='linux athens 2.2.10 #3 smp mon aug 2 16​:48​:09 edt 1999 i686 unknown '   config_args=''   hint=recommended\, useposix=true\, d_sigaction=define   usethreads=undef use5005threads=undef useithreads=undef   usesocks=undef useperlio=undef d_sfio=undef   use64bits=undef uselargefiles=undef usemultiplicity=undef   Compiler​:   cc='cc'\, optimize='-g'\, gccversion=2.95.2 20000116 (Debian GNU/Linux)   cppflags='-Dbool=char -DHAS_BOOL -DDEBUGGING -fno-strict-aliasing -I/usr/local/include -DDEBUGGING_OPS -DDEBUGGING_MSTATS'   ccflags ='-Dbool=char -DHAS_BOOL -DDEBUGGING -fno-strict-aliasing -I/usr/local/include -DDEBUGGING_OPS -DDEBUGGING_MSTATS'   stdchar='char'\, d_stdstdio=define\, usevfork=false   intsize=4\, longsize=4\, ptrsize=4\, doublesize=8   d_longlong=define\, longlongsize=8\, d_longdbl=define\, longdblsize=12   alignbytes=4\, usemymalloc=y\, prototype=define   Linker and Libraries​:   ld='cc'\, ldflags =' -L/usr/local/lib'   libpth=/usr/local/lib /lib /usr/lib   libs=-lnsl -lndbm -lgdbm -ldbm -ldb -ldl -lm -lc -lposix -lcrypt   libc=/lib/libc-2.1.2.so\, so=so\, useshrplib=false\, libperl=libperl.a   Dynamic Linking​:   dlsrc=dl_dlopen.xs\, dlext=so\, d_dlsymun=undef\, ccdlflags='-rdynamic'   cccdlflags='-fpic'\, lddlflags='-shared -L/usr/local/lib'

Characteristics of this binary (from libperl)​:   Compile-time options​: DEBUGGING USE_LONG_DOUBLE USE_LARGE_FILES   Built under linux   Compiled at Feb 3 2000 22​:10​:17   @​INC​:   /usr/local/perl5.5.64/lib/i686-linux   /usr/local/perl5.5.64/lib   /usr/local/perl5.5.64/lib/site_perl/i686-linux   /usr/local/perl5.5.64/lib/site_perl   .

--

Michael G Schwern schwern@​pobox.com   http​://www.pobox.com/~schwern   /(?​:(?​:(1)[.-]?)?\(?(\d{3})\)?[.-]?)?(\d{3})[.-]?(\d{4})(x\d+)?/i

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

Michael G Schwern writes​:

perlop mistakenly had a link to 'the qr// man page'. This changes it to 'the section on qr//'

--- pod/perlop.pod 2000/02/04 03​:34​:46 +++ pod/perlop.pod 2000/02/04 03​:35​:17 @​@​ -789\,7 +789\,7 @​@​ and is useful when the value you are interpolating won't change over the life of the script. However\, mentioning C\ constitutes a promise that you won't change the variables in the pattern. If you change them\, -Perl won't even notice. See also L\<qr//>. +Perl won't even notice. See also L\<"qr//">.

I do not think this is a correct fix. These two constructs should be equivalent *if there is such a section*. Is there?

Ilya

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

Ilya Zakharevich \ilya@&#8203;math\.ohio\-state\.edu writes​:

Michael G Schwern writes​:

perlop mistakenly had a link to 'the qr// man page'. This changes it to 'the section on qr//'

--- pod/perlop.pod 2000/02/04 03​:34​:46 +++ pod/perlop.pod 2000/02/04 03​:35​:17 @​@​ -789\,7 +789\,7 @​@​ and is useful when the value you are interpolating won't change over the life of the script. However\, mentioning C\ constitutes a promise that you won't change the variables in the pattern. If you change them\, -Perl won't even notice. See also L\<qr//>. +Perl won't even notice. See also L\<"qr//">.

I do not think this is a correct fix. These two constructs should be equivalent *if there is such a section*. Is there?

That requires pre-scanning the entire file. Neither Pod​::Text nor Pod​::Man currently do that. It may be nice if they did\, but in the meantime it's considerably more reliable to force interpretation of a link as a section heading if that's what you mean.

-- Russ Allbery (rra@​stanford.edu) \<URL​:http​://www.eyrie.org/~eagle/>

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

On Fri\, Feb 04\, 2000 at 05​:16​:05AM -0800\, Russ Allbery wrote​:

That requires pre-scanning the entire file. Neither Pod​::Text nor Pod​::Man currently do that.

These are bugs.

It may be nice if they did\, but in the meantime it's considerably more reliable to force interpretation of a link as a section heading if that's what you mean.

No\, frankly speaking my meaning was "Did you *check* that this section exists\, and matches the reference in all the gory details"? ;-)

Ilya

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

Ilya Zakharevich \ilya@&#8203;math\.ohio\-state\.edu writes​:

On Fri\, Feb 04\, 2000 at 05​:16​:05AM -0800\, Russ Allbery wrote​:

That requires pre-scanning the entire file. Neither Pod​::Text nor Pod​::Man currently do that.

These are bugs.

They're missing features. Neither pod2text nor pod2man have ever done this to my knowledge. (I really dislike this corner of POD semantics\, BTW. Interpretation of an L\<> directive should not depend on knowledge of all of the headings in the document.)

-- Russ Allbery (rra@​stanford.edu) \<URL​:http​://www.eyrie.org/~eagle/>

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

On Fri\, Feb 04\, 2000 at 10​:14​:44AM -0800\, Russ Allbery wrote​:

They're missing features. Neither pod2text nor pod2man have ever done this to my knowledge. (I really dislike this corner of POD semantics\, BTW. Interpretation of an L\<> directive should not depend on knowledge of all of the headings in the document.)

Well\, I would substitute "should not" by "should"\, and everything becomes OK. ;-)

You optimize for a writer of pod2xxx. POD is optimized for writers of POD.

Ilya

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

Ilya Zakharevich \ilya@&#8203;math\.ohio\-state\.edu writes​:

On Fri\, Feb 04\, 2000 at 10​:14​:44AM -0800\, Russ Allbery wrote​:

They're missing features. Neither pod2text nor pod2man have ever done this to my knowledge. (I really dislike this corner of POD semantics\, BTW. Interpretation of an L\<> directive should not depend on knowledge of all of the headings in the document.)

Well\, I would substitute "should not" by "should"\, and everything becomes OK. ;-)

You optimize for a writer of pod2xxx. POD is optimized for writers of POD.

Precisely\, which is why this behavior is broken. If I say something is a pointer to a section heading\, I expect the translator to deal with that\, even if the section heading doesn't (yet) exist. I may be doing this for a reason. A lint checker should pick up the fact that the section header doesn't exist\, but the meaning of what I write should *not* change as I add more sections. That's just wrong\, IMO. I don't know of any other markup language that does this.

It doesn't help that the current L\<> semantics are fragile in the extreme\, and that it's not clear what the available different types of links are.

What we have currently is a clear-cut ambiguity with no hint at all in perlpod as to how the ambiguity is resolved​:

  L\ manual page   L\<"sec"> section in this manual page   (the quotes are optional)

So if I say L\\, is it a link to the man page about the POSIX module or is it a link to the section in the current document about POSIX compliance in whatever I'm writing about? How do I tell the POD translator unambiguously that it is a link to the POSIX manual page\, *not* to any section in the current document?

-- Russ Allbery (rra@​stanford.edu) \<URL​:http​://www.eyrie.org/~eagle/>

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

They're missing features. Neither pod2text nor pod2man have ever done this to my knowledge. (I really dislike this corner of POD semantics\, BTW. Interpretation of an L\<> directive should not depend on knowledge of all of the headings in the document.)

It's much worse than that. It in practice depends on global knowledge of all possible documents. Look at the caching database that Chris Hall did for installhtml. I couldn't think of any other way to do it. I think I'd change the spec first\, next time.

--tom

p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

On Fri\, Feb 04\, 2000 at 10​:28​:14AM -0800\, Russ Allbery wrote​:

Precisely\, which is why this behavior is broken. If I say something is a pointer to a section heading\, I expect the translator to deal with that\, even if the section heading doesn't (yet) exist.

If you like this semantic\, it is not that somebody prohibits you to use L\<"name">. But I prefer the other semantic​: link to "name"\, which is expressed as L\ (no matter how "name" is implemented\, either section or a separate document).

Ilya