Subject: | pod2wiki --style mediawiki can silently create broken links |
Date: | Wed, 10 Oct 2012 15:57:58 -0400 |
To: | bug-Pod-Simple-Wiki [...] rt.cpan.org |
From: | JP Vossen <jp [...] jpsdomain.org> |
pod2wiki --style mediawiki fails to warn that it cannot create some
links due to wikitext limitations.
POD allows links to both headers and "items" but Mediawiki only
internally links to "sections" (headers). 'pod2wiki --style mediawiki'
can therefore create links that point to non-existent HTML anchors.
This can create confusion for users since there are now "broken links."
'pod2wiki --style mediawiki' should probably warn if that happens,
and/or refuse to create the broken links, and/or link instead to the
header that contains the referenced item (best for the user but probably
really ugly to code).
===== cut here =====
=head1 NAME
Test case for 'pod2wiki --style mediawiki' item links
=head2 My Heading 2
=over 4
=item Foo
Foo is great
=item bar
Bar is better
=back
So this link to heading L</"My Heading 2"> will work,
but this link to item L</"Foo"> will fail.
The generated wikitext is syntactically correct, but Mediawiki wikitext
only supports links to headers, so it does not generate anchors for list
items, so the generated link is broken.
Both types work in the HTML created by pod2html, because that can create
all the anchors needed.
===== cut here =====
That said, I can't tell you how happy I was to find 'pod2wiki --style
mediawiki' when I went looking last week! $WORK has lots of stuff in
Mediawiki, and this makes searchable hard-to-lose docs for my scripts
trivial.
Thanks!
JP