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
