From @rcaputo

Attached.

From @rcaputo

From 3e13bf4c73db4e3e0ff1748be3b060ae5f7f3df0 Mon Sep 17 00:00:00 2001
From: Rocco Caputo <rcaputo@cpan.org>
Date: Wed, 27 Jul 2011 01:32:11 -0400
Subject: [PATCH] Let X<> within anchorifiable paragraphs be additional anchors.

X<> is already used within =headN and =item paragraphs throughout
Perl's own documentation.  Map the semantics to HTML, and make them
available to the public.
---
 ext/Pod-Html/Html.pm      |   15 ++++++++++++---
 ext/Pod-Html/t/htmllink.t |    6 +++---
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/ext/Pod-Html/Html.pm b/ext/Pod-Html/Html.pm
index 2c5c441..b8bdccf 100644
--- a/ext/Pod-Html/Html.pm
+++ b/ext/Pod-Html/Html.pm
@@ -3,7 +3,7 @@ use strict;
 require Exporter;
 
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
-$VERSION = 1.11;
+$VERSION = 1.12;
 @ISA = qw(Exporter);
 @EXPORT = qw(pod2html htmlify);
 @EXPORT_OK = qw(anchorify);
@@ -1121,9 +1121,13 @@ sub process_head {
       print $fh "</p>\n";
     }
 
+    # Each X<> inside the heading tag is an additional anchor.
+    # It's up to the POD author to avoid duplicates.
+    my @aliases = map { "<a name=\"" . anchorify( depod( $_ ) ) . "\" />" } ($heading =~ /X<([^>]+)>/g);
+
     my $name = anchorify( depod( $heading ) );
     my $convert = process_text( \$heading );
-    print $fh "<h$level><a name=\"$name\">$convert</a></h$level>\n";
+    print $fh "<h$level>", @aliases, "<a name=\"$name\">$convert</a></h$level>\n";
 }
 
 
@@ -1146,8 +1150,13 @@ sub emit_item_tag {
 	print $fh process_text( \$otext );
     } else {
         my $name = $item;
+
+        # Each X<> inside the item tag is an additional anchor.
+        # It's up to the POD author to avoid duplicates.
+        my @aliases = map { "<a name=\"" . anchorify( depod( $_ ) ) . "\" />" } ($otext =~ /X<([^>]+)>/g);
+
         $name = anchorify($name);
-	print $fh qq{<a name="$name" class="item">}, process_text( \$otext ), '</a>';
+	print $fh @aliases, qq{<a name="$name" class="item">}, process_text( \$otext ), '</a>';
     }
     print $fh "</strong>";
     undef( $EmittedItem );
diff --git a/ext/Pod-Html/t/htmllink.t b/ext/Pod-Html/t/htmllink.t
index 592fef3..71f85f8 100644
--- a/ext/Pod-Html/t/htmllink.t
+++ b/ext/Pod-Html/t/htmllink.t
@@ -105,17 +105,17 @@ __DATA__
 <h2><a name="section_three">section three</a></h2>
 <p>This is section three.</p>
 <dl>
-<dt><strong><a name="item1" class="item">item1</a></strong></dt>
+<dt><strong><a name="item" /><a name="one" /><a name="item1" class="item">item1</a></strong></dt>
 
 <dd>
 <p>This is item one.</p>
 </dd>
-<dt><strong><a name="item_2" class="item">item 2</a></strong></dt>
+<dt><strong><a name="item" /><a name="two" /><a name="item_2" class="item">item 2</a></strong></dt>
 
 <dd>
 <p>This is item two.</p>
 </dd>
-<dt><strong><a name="item_three" class="item">item three</a></strong></dt>
+<dt><strong><a name="item" /><a name="three" /><a name="item_three" class="item">item three</a></strong></dt>
 
 <dd>
 <p>This is item three.</p>
-- 
1.7.4.1

From @rcaputo

--
Rocco Caputo <rcaputo@​pobox.com>

From @rjbs

The GSOC Pod work has greatly rewritten Pod​::Html. I don't know whether this
patch will cleanly apply, but there is a good chance it will not.

I'll try to see what we can do once the GSOC-POD branches are landed.

--
rjbs

The RT System itself - Status changed from 'new' to 'open'

From @khwilliamson

On 07/28/2011 10​:52 PM, Ricardo Signes wrote​:

The GSOC Pod work has greatly rewritten Pod​::Html. I don't know whether this
patch will cleanly apply, but there is a good chance it will not.

I'll try to see what we can do once the GSOC-POD branches are landed.

I have some concerns about this whole idea. These concerns would go away
if the X<> were to create an anchor only if that anchor doesn't already
exist in the page.

It seems likely to me that someone would want to say

  =head2 foo
  X<foo>

  Description of foo

and this patch, if I understand it correctly, would forbid this.

From @tamias

On Fri, Jul 29, 2011 at 09​:05​:32AM -0600, Karl Williamson wrote​:

I have some concerns about this whole idea. These concerns would go away
if the X<> were to create an anchor only if that anchor doesn't already
exist in the page.

It seems likely to me that someone would want to say

=head2 foo
X<foo>

Description of foo

and this patch, if I understand it correctly, would forbid this.

I have concerns too. This patch overloads the meaning of the X<> tag.

I think it's likely someone would want to say​:

=head2 foo

Description of foo

=head2 bar
X<foo>

Description of bar

where bar is related to foo, and so would be listed under foo in the index,
but should not be a target for a link to foo.

This functionality should be implemented with a new tag, not by adding
a meaning to the X<> tag that conflicts with the existing meaning.

Ronald

From @cpansprout

On Fri Jul 29 08​:55​:58 2011, rjk@​tamias.net wrote​:

On Fri, Jul 29, 2011 at 09​:05​:32AM -0600, Karl Williamson wrote​:

I have some concerns about this whole idea. These concerns would go
away
if the X<> were to create an anchor only if that anchor doesn't already
exist in the page.

It seems likely to me that someone would want to say

=head2 foo
X<foo>

Description of foo

and this patch, if I understand it correctly, would forbid this.

I have concerns too. This patch overloads the meaning of the X<> tag.

I think it's likely someone would want to say​:

=head2 foo

Description of foo

=head2 bar
X<foo>

Description of bar

where bar is related to foo, and so would be listed under foo in the
index,
but should not be a target for a link to foo.

This functionality should be implemented with a new tag, not by adding
a meaning to the X<> tag that conflicts with the existing meaning.

I’m with Ronald here. This adds a really nice feature, but does it the
wrong way. Also, there’s currently nothing wrong with having multiple
identical X<> tags in the same document.

I don’t know in which forum pod syntax is decided, but I think it’s
pod-people@​perl.org.

@cpansprout - Status changed from 'open' to 'rejected'

From @khwilliamson

On 07/31/2011 12​:04 PM, Father Chrysostomos via RT wrote​:

On Fri Jul 29 08​:55​:58 2011, rjk@​tamias.net wrote​:

On Fri, Jul 29, 2011 at 09​:05​:32AM -0600, Karl Williamson wrote​:

I have some concerns about this whole idea. These concerns would go
away
if the X<> were to create an anchor only if that anchor doesn't already
exist in the page.

It seems likely to me that someone would want to say

=head2 foo
X<foo>

Description of foo

and this patch, if I understand it correctly, would forbid this.

I have concerns too. This patch overloads the meaning of the X<> tag.

I think it's likely someone would want to say​:

=head2 foo

Description of foo

=head2 bar
X<foo>

Description of bar

where bar is related to foo, and so would be listed under foo in the
index,
but should not be a target for a link to foo.

This functionality should be implemented with a new tag, not by adding
a meaning to the X<> tag that conflicts with the existing meaning.

I’m with Ronald here. This adds a really nice feature, but does it the
wrong way. Also, there’s currently nothing wrong with having multiple
identical X<> tags in the same document.

I don’t know in which forum pod syntax is decided, but I think it’s
pod-people@​perl.org.

I believe that is the correct forum.

But I do think the original idea has merit, as long as no duplicate
anchor gets created. In Ronald's example, the "=head2 foo" would have
precedence over the X<foo>, so no harm would be done. But if there is
no other "foo" anchor in the pod, this would create one, thus allowing
some other tool to jump to this place, where it has been indexed.
Suddenly, without any source changes, it becomes possible to create an
index page with hyperlinks, making it much more useful.

I do not understand how there could be objections to the proposal as
long as no duplicate anchors are created. But if I'm wrong, another
alternative would be to create anchors of a particular style that would
be extremely unlikely to occur currently, such as "__X_foo", and the
index page would know about this convention.

From @cpansprout

On Sun Jul 31 11​:58​:07 2011, public@​khwilliamson.com wrote​:

On 07/31/2011 12​:04 PM, Father Chrysostomos via RT wrote​:

On Fri Jul 29 08​:55​:58 2011, rjk@​tamias.net wrote​:

On Fri, Jul 29, 2011 at 09​:05​:32AM -0600, Karl Williamson wrote​:

I have some concerns about this whole idea. These concerns would go
away
if the X<> were to create an anchor only if that anchor doesn't
already
exist in the page.

It seems likely to me that someone would want to say

=head2 foo
X<foo>

Description of foo

and this patch, if I understand it correctly, would forbid this.

I have concerns too. This patch overloads the meaning of the X<> tag.

I think it's likely someone would want to say​:

=head2 foo

Description of foo

=head2 bar
X<foo>

Description of bar

where bar is related to foo, and so would be listed under foo in the
index,
but should not be a target for a link to foo.

This functionality should be implemented with a new tag, not by adding
a meaning to the X<> tag that conflicts with the existing meaning.

I’m with Ronald here. This adds a really nice feature, but does it the
wrong way. Also, there’s currently nothing wrong with having multiple
identical X<> tags in the same document.

I don’t know in which forum pod syntax is decided, but I think it’s
pod-people@​perl.org.

I believe that is the correct forum.

But I do think the original idea has merit, as long as no duplicate
anchor gets created. In Ronald's example, the "=head2 foo" would have
precedence over the X<foo>, so no harm would be done. But if there is
no other "foo" anchor in the pod, this would create one, thus allowing
some other tool to jump to this place, where it has been indexed.
Suddenly, without any source changes, it becomes possible to create an
index page with hyperlinks, making it much more useful.

I do not understand how there could be objections to the proposal as
long as no duplicate anchors are created.

Thinking about this more, I have no problem with it if Pod​::Html
actually checks for duplicates and ensures that it does not create
duplicate anchors. Then it would ‘just work’ for a lot of existing
documentation.

But if I'm wrong, another
alternative would be to create anchors of a particular style that would
be extremely unlikely to occur currently, such as "__X_foo", and the
index page would know about this convention.

@cpansprout - Status changed from 'rejected' to 'open'

From @rcaputo

On Jul 31, 2011, at 16​:40, Father Chrysostomos via RT wrote​:

On Sun Jul 31 11​:58​:07 2011, public@​khwilliamson.com wrote​:

On 07/31/2011 12​:04 PM, Father Chrysostomos via RT wrote​:

On Fri Jul 29 08​:55​:58 2011, rjk@​tamias.net wrote​:

On Fri, Jul 29, 2011 at 09​:05​:32AM -0600, Karl Williamson wrote​:

I have some concerns about this whole idea. These concerns would go
away
if the X<> were to create an anchor only if that anchor doesn't
already
exist in the page.

It seems likely to me that someone would want to say

=head2 foo
X<foo>

Description of foo

and this patch, if I understand it correctly, would forbid this.

I have concerns too. This patch overloads the meaning of the X<> tag.

I think it's likely someone would want to say​:

=head2 foo

Description of foo

=head2 bar
X<foo>

Description of bar

where bar is related to foo, and so would be listed under foo in the
index,
but should not be a target for a link to foo.

This functionality should be implemented with a new tag, not by adding
a meaning to the X<> tag that conflicts with the existing meaning.

I’m with Ronald here. This adds a really nice feature, but does it the
wrong way. Also, there’s currently nothing wrong with having multiple
identical X<> tags in the same document.

I don’t know in which forum pod syntax is decided, but I think it’s
pod-people@​perl.org.

I believe that is the correct forum.

But I do think the original idea has merit, as long as no duplicate
anchor gets created. In Ronald's example, the "=head2 foo" would have
precedence over the X<foo>, so no harm would be done. But if there is
no other "foo" anchor in the pod, this would create one, thus allowing
some other tool to jump to this place, where it has been indexed.
Suddenly, without any source changes, it becomes possible to create an
index page with hyperlinks, making it much more useful.

I do not understand how there could be objections to the proposal as
long as no duplicate anchors are created.

Thinking about this more, I have no problem with it if Pod​::Html
actually checks for duplicates and ensures that it does not create
duplicate anchors. Then it would ‘just work’ for a lot of existing
documentation.

Segueing to pod-people@​perl.org via Cc. You have been warned. :)

I can see where X<foo> in conflict with "=head2 foo" will cause confusion.
Existing behavior supports duplicate X<foo>, however, so prohibiting it
would break current indexers.

New syntax may be the only recourse.

--
Rocco Caputo <rcaputo@​pobox.com>

From @rcaputo

On Jul 29, 2011, at 11​:55, Ronald J Kimball wrote​:

I have concerns too. This patch overloads the meaning of the X<> tag.

I think it's likely someone would want to say​:

=head2 foo

Description of foo

=head2 bar
X<foo>

Description of bar

where bar is related to foo, and so would be listed under foo in the index,
but should not be a target for a link to foo.

This functionality should be implemented with a new tag, not by adding
a meaning to the X<> tag that conflicts with the existing meaning.

Cc​: pod-people@​perl.org ... trying to segue the discussion into that list.

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.

X<foo> can and should become an anchor wherever it's present. L<foo> 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 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.

--
Rocco Caputo <rcaputo@​pobox.com>