Re: [perl #95784] [PATCH] Let X within anchorifiable paragraphs be additional anchors.
On Sun, Jul 31, 2011 at 05:34:22PM -0400, Rocco Caputo wrote: Cc: pod-people@perl.org ... trying to segue the discussion into that list. To that same end, I've removed p5p from this reply. It's legal and encouraged for the same index term to reference multiple points in the broader text. Indexes have always done this. This example from _TeXbook_ links indexes to four anchors in the book: indexes, 261-263, 392-394, 423-425, 481 Unfortunately hypertext doesn't support ambiguous link targets. New syntax for anchors doesn't solve this problem. It only pushes renderer-specific concerns into POD where they don't belong. Xfoo can and should become an anchor wherever it's present. Lfoo can and should link to ALL of them. The anchors' actual names are unimportant implementation details, as long as X and L do the right things. When we read books, we resolve ambiguous references by visiting the index and branching. We often take multiple branches until our curiosities are satisfied. And we benefit from incidental, serendipitous context while we're there. The obvious solution to ambiguous Lfoo is to emulate books. If we know Lfoo 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? Ronald
Re: [perl #95784] [PATCH] Let X within anchorifiable paragraphs be additional anchors.
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 Lfoo is to emulate books. If we know Lfoo 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 Lselect_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
Re: [perl #95784] [PATCH] Let X within anchorifiable paragraphs be additional anchors.
On 11-08-04 09:55 PM, Rocco Caputo wrote: 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] ] I thought the Z code was being use for named anchors: =head3 select_read FILE_HANDLE [, EVENT_NAME [, ADDITIONAL_PARAMETERS] ] Zselect_read_main and later: Lselect read|select_read_main I think the Pod::Simple https://metacpan.org/module/Pod::Simple does this. -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS. Make something worthwhile. -- Dear Hunter
Re: [perl #95784] [PATCH] Let X within anchorifiable paragraphs be additional anchors.
I thought the Z code was being use for named anchors: =head3 select_read FILE_HANDLE [, EVENT_NAME [, ADDITIONAL_PARAMETERS] ] Zselect_read_main and later: Lselect read|select_read_main I think the Pod::Simple https://metacpan.org/module/Pod::Simple does this. I believe Z is the null formatting code; it is supposed to be empty.
