Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
p5pRT opened this issue Feb 3, 2000 · 9 comments
Closed

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

p5pRT opened this issue Feb 3, 2000 · 9 comments

Comments

@p5pRT
Copy link

p5pRT commented Feb 3, 2000

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

Searchable as RT2094$

@p5pRT
Copy link
Author

p5pRT commented Feb 3, 2000

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</o> 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<successfully> 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
Copy link
Author

p5pRT commented Feb 3, 2000

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</o> 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
Copy link
Author

p5pRT commented Feb 4, 2000

From [Unknown Contact. See original ticket]

Ilya Zakharevich <ilya@​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</o> 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
Copy link
Author

p5pRT commented Feb 4, 2000

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
Copy link
Author

p5pRT commented Feb 4, 2000

From [Unknown Contact. See original ticket]

Ilya Zakharevich <ilya@​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
Copy link
Author

p5pRT commented Feb 4, 2000

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
Copy link
Author

p5pRT commented Feb 4, 2000

From [Unknown Contact. See original ticket]

Ilya Zakharevich <ilya@​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<name> manual page
  L<"sec"> section in this manual page
  (the quotes are optional)

So if I say L<POSIX>, 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
Copy link
Author

p5pRT commented Feb 4, 2000

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
Copy link
Author

p5pRT commented Feb 4, 2000

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<name> (no matter how "name" is implemented, either
section or a separate document).

Ilya

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant