When writing Perl documentation using POD, I sometimes need to use the same text in places that can be referenced. As an example, I might have foo
and bar
options that can be set in a constructor, which I would document like this:
=head2 B<< new >>
my $instance = Foo::Bar->new(%args);
Constructor, supports the following keys:
=over
=item C<bar>
set some I<bar>s
=item C<foo>
set the initial value for I<foo>
=back
Then, I might also have documentation for methods that share the same name:
=head2 B<< bar >>
my $bars = $instance->bar;
Accessor for getting the I<bar>s. Read-only.
=head2 B<< foo >>
$instance->foo;
Invoke the I<foo> functionality.
In POD, this would lead to a warning (https://perldoc.perl.org/Pod::Checker#Warnings) about the duplication:
multiple occurrences (N) of link target name
This also means that in general only the first occurrence is used when inserting links with L<...>
. This can lead to… problems, as sometimes I’d like to put a link to the second instance (most frequently, I’d like to link to the =head2
instead of the list item).
Command pod2html
assigns different identifiers for anchoring, like foo
to the first and foo1
for the second:
...
<dt id="foo"><code>foo</code></dt>
...
<h2 id="foo1"><b>foo</b></h2>
...
This can be exploited to link to the right place:
Link to the first L</foo>.
Then, link to the second L<foo|/foo1>.
The above generates:
<p>Link to the first <a href="#foo">"foo"</a>.</p>
<p>Then, link to the second <a href="#foo1">foo</a>.</p>
Alas, this is not considered valid by podchecker
:
*** ERROR: unresolved internal link 'foo1' at line ...
For this reason, this approach is a bit too hackish for my taste.
How can I reliably make it possible to distinguish different same-labeled places in POD to be able to link to all of them?