On Aug 4, 2011, at 20:51, Ronald J Kimball wrote: > On Sun, Jul 31, 2011 at 05:34:22PM -0400, Rocco Caputo wrote: > >> >> The obvious solution to ambiguous L<foo> is to emulate books. If we know >> L<foo> is ambiguous, then we already have a list of link targets. Send the >> reader to that list, and let them branch out from there. >> >> A sufficiently advanced renderer could pop up a menu of options on link >> click, but again, people writing POD shouldn't need new syntax to make it >> happen. > > I can definitely see the usefulness of a link that leads to all the indexed > entries for a particular term. However, I'm not convinced this should > replace the current behavior for L<>. There's a difference between > something that IS foo, and something that is RELATED TO foo. Sometimes > when using an index I want to follow the multiple branches, but other times > I just want the main entry. > > Right now, L<> links to the main entry for a term (specifically, in cases > where X<> is added to the main entry as a convenient link target, as well > as to related entries). Under your proposal, it would link to all the > entries for a term. These are both useful; I just hesitate to add the > latter at the cost of the former. > > Maybe there's a good way to allow both behaviors?
I don't care. I'm kind of frustrated that the thread has wandered this far afield of my original request. Originally I wanted a way to alias main definition targets. As it stands today, they can be unwieldy, incredibly fiddly, and umnaintainably fragile. The discourage use, and my documentation suffers. For example, this looks great in the HTML TOC outline. It's reminiscent of traditional man pages where usage summaries are listed at the top. But it's terrible to link to this section: =head3 select_read FILE_HANDLE [, EVENT_NAME [, ADDITIONAL_PARAMETERS] ] If I do manage to get the L</"select_read FILE_HANDLE [, EVENT_NAME [, ADDITIONAL_PARAMETERS] ]"> syntax correct, then I'm faced with the proposition of all those links breaking if I have to change something. Some links may be outside my modules, and beyond my control. Of course I can just call it "=head3 select_read", but this takes eliminates the usage summary at the top of the file. That's a poor, lossy work-around. I would simply like a way to make a small, stable symbolic reference to the longer, more dynamic content. For example, let me say L<select_read> somehow. Index rendering has been orthogonal to my request all along. I'm sorry I got sucked off-topic like that. If someone really wants that to be better---I don't right now---then it's a separate topic and could really use a separate ticket. As for the tyranny of duplicate link targets: aliases should piggyback over existing validation rules. Whatever Pod::Html tolerates should continue to work until new behavior is decided upon. The last time I looked at Perl's blead branch, Pod::Html simply rendered identical "=head#" commands as duplicate link targets. Sorting them out is delegated to the user agent. -- Rocco Caputo <rcap...@pobox.com>
