develooper Front page | perl.perl5.porters | Postings from July 2011

Re: [perl #95784] [PATCH] Let X<> within anchorifiable paragraphs beadditional anchors.

Thread Previous | Thread Next
From:
Rocco Caputo
Date:
July 31, 2011 14:03
Subject:
Re: [perl #95784] [PATCH] Let X<> within anchorifiable paragraphs beadditional anchors.
Message ID:
C4266C17-534F-450B-81AD-A7806495260E@pobox.com
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>
Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About