At 11:34 PM 2001-04-18 -0700, Russ Allbery wrot e:
>Sean M Burke <[EMAIL PROTECTED]> writes:
>
>> What I'd like to have happen is one of these three:
>
>> I) agreement that L<name/foo> and L<name/"foo"> are NOT THE SAME (even
>> tho people seem to confuse them). This should involve explaining why
>> the difference is necessary and motivated. Ambitious pod checkers
>> should possibly then go about enforcing the difference, so that one of
>> L<perlvar/$^F> and L<perlvar/"$/"> are declared wrong. [...]
>
>perlfunc.pod doesn't use them as the same. [...]
The latest copy of Perl handy is on a MSWin box, so forgive the fiddling
with blunt stone tools here, but...
C:\Perl\lib\Pod>dir perlfunc.pod
[...]
PERLFUNC POD 230,598 12-15-2000 3:34p perlfunc.pod
C:\Perl\lib\Pod>find /n "perlvar/" perlfunc.pod
---------- perlfunc.pod
[381]value of $^F. See L<perlvar/$^F>.
[1032]See L<perlvar/"$/"> and L<perlvar/"$.">.
[1082]L<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and
[1091]as the first line of the handler (see L<perlvar/$^S>). Because
[1124]C<%INC> if the file is found. See L<perlvar/Predefined Names> for these
[2790]file descriptor as determined by the value of $^F. See L<perlvar/$^F>.
[3311]See L<perlvar/$^F>.
[3481]with C<$/> or C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">.
[4096]value of $^F. See L<perlvar/$^F>.
[4107]of $^F. See L<perlvar/$^F>.
OK, so I assume that when perlpod.pod says L<name/ident> is for an "item in
manual page", and L<name/"sec"> is for a "section in other manual page", that
"item" means list item, and "section" means section heading.
So, there's a L<perlvar/Predefined Names>, item syntax; but "Predefined Names"
in perlvar isn't a list item; there's only a heading: "=head2 Predefined Names".
In fact, these are all the headings:
C:\Perl\lib\Pod>find /n "=head" perlvar.pod
---------- perlvar.pod
[1]=head1 NAME
[5]=head1 DESCRIPTION
[7]=head2 Predefined Names
[1113]=head2 Error Indicators
[1164]=head2 Technical Note on the Syntax of Variable Names
[1210]=head1 BUGS
Maybe this is about X<...>'d index points:
C:\Perl\lib\Pod>find /n "X<" perlvar.pod
---------- perlvar.pod
[[nothing]]
Nope, none of those there.
So I look at the above list of links from perlfunc to perlvar (which
is a decent chunk of the links from perlfunc to anything else with
L<foo/...> syntax, and so I assume it's grosso modo representative).
Aside from the "Predefined Names" link, I see:
item links:
L<perlvar/$^F> L<perlvar/$^S> L<perlvar/$SIG{expr}>
section links:
L<perlvar/"$/"> L<perlvar/"$.">
But, as we saw, there are no perlvar sections called "$/" or "$.".
But there are perlvar items called that.
So, what's the difference? Are the section links typos?
Is the difference between section and item not what I think?
Is any conceivable difference important anyway if it's not
even followed well in Perl's own documentation? I say declare
the distinction moot.
>If they're declared the same, how does one distinguish between a
>link to a section in documentation (ie,
>a =head1, =head2, etc.) and to an entry (ie, an =item)?
Either by seeing what in the destination file it actually is, or
by just not knowing anyway. Is the =headiness versus =itemicity
of the target an essential/useful feature of a link?
Whether-a-woman-will-answer isn't an inherent feature of a phone
number. Well, at least not most phone numbers.
I think the distinction isn't useful, and since perlpod doesn't
precisely define section versus item (as link targets) in any
way that seems to jibe with the usage I see in perlfunc, then
I say the distinction was a passing thought that never took, and
should join "each other / one another" on history's scrap heap of
distictions that we learned to live without (possibly without ever
having had them in the first place).
--
Sean M. Burke [EMAIL PROTECTED] http://www.spinn.net/~sburke/
