AW: pod checker that finds missing internal links?

The main reason why I dislike an additional A<> is that since
the existence of POD nobody really needed it - since anchors 
for L<> are created by =head and =item. And as Perl stands for
simplicity and efficiency, you certainly don't want to
force people to rewrite all their POD to add A<> markup
WITH THE SAME CONTENT as the =head/=item near it.

Back to the issue with the "short" anchor for e.g.
    =item open FILEHANDLE
I checked Perl 5.10.x's pod directory (the one with all the
perlfunc.pod, perlrun.pod etc.) - and found >30 *.pod files
which use L<perlfunc/name> links, where "name" is e.g.
open, pack, binmode etc. - the "short" name. Who is going to
rewrite these (let alone all the others) if short anchors are
not created/allowed by Pod::Parser/::Checker/::Simple?

The (perhaps) good news is that perlfunc.pod contains for
(as far as I saw) all functions the following content, e.g.:

=item vec EXPR,OFFSET,BITS
X<vec> X<bit> X<bit vector>

that is, there is always X<name> there... so if we accepted
to treat X<> as an anchor, the short names could be IMHO 
deprecated (at the slight risk that perlfunc and perlvar,
and may be a few others may need to be reviewed for 
completeness regarding this).

Honestly, I do not see much difference in arguing whether an
index entry should be an anchor or an anchor should be an
index entry. I am trying to think practical, and that is:
we have X<> and L<>, and all the PODs using these around.
And we can add value by specifying that X<> creates _also_
an anchor for potential L<>s to link against it. Then we 
would not break any existing POD and give guidance to existing 
or new renderers.

And I think we heard enough voices saying that we need index
entries, and I understand that as "don't change the semantics
of X<> being an index entry" - which IMHO does not prevent
us from _extending_ its meaning.

-Marek

-----Ursprüngliche Nachricht-----
Von: 'Patrice Dumas' [mailto:[email protected]] 
Gesendet: Sonntag, 29. Januar 2012 18:46
An: [email protected]
Betreff: Re: pod checker that finds missing internal links?

On Sun, Jan 29, 2012 at 04:29:32PM +0100, Marek Rouchal wrote:
> It is nice that you are sharing your thoughts with us - but frankly 
> speaking I do not see any concrete point.
> L<> and =head/=item may not be the perfect solution, but it is all 
> that's been there for years, and changing this (by introducing a new 
> anchor syntax) would require basically to rewrite all POD. Or to 
> provide a semi-perfect

Certainly not.  The new anchor would be an addition.  In case it was not
clear, the rant about =head/=item possible inconsitencies was a side note,
maybe trying to convey my ideas on a suboptimal design of the language that
I think should not be carried on in further changes in the language.

And I think that the L<> semantics is powerful enough to do any kind of
link.

> and the same way you dislike X<> being an anchor, others may actually 
> like the idea; and hey - you are not forced to link against them from 
> elsewhere, are you?

I do not disagree on X being rendered as an anchor, but it should be an
index entry anchor, not a label anchor.

> So perhaps the concepts of POD are not perfect, but they have been 
> practical for a long time.

But maybe there is room for improvement?

> So show a patch that corrects things along the lines that you wrote, 
> which might be more convincing.

I am ready to do some patches, but that's not the point here.
There are design issues too, on the language itself.

--
Pat