Re: Pod::Html's cross referencing of C<> links

On 05/20/2011 07:06 PM, Marc Green wrote:
>     My guess is that it's just plain wrong, so no wonder it's confusing.
>     Perhaps it's reflecting an early design, or perhaps it's just a
>     typo, and L was meant instead of C.  L<> can link to =items provided
>     they are of a type that permits that.  Currently, the only ones that
>     are are ones that are in what html calls definition lists, at least
>     in Pod::Html.
>
>
> I do not think it would be a typo for it is repeated in several cases
> (unless it was a typo in a find/replace all, I suppose). Whatever the
> reason, could you rephrase your last sentence? I feel that it will shed
> some light on something I am not grasping, but currently it is rather
> difficult to understand.

I'm sorry.

C<> doesn't have anything to do with links currently.  L<> does.  To use 
html terminology, =head pod constructs create ANCHORS that can be linked 
to.  Most =item's do not.  However, in html, there are various types of 
lists: there is an ordered (numbered) list, an unordered (bullet) list, 
and a 'definition' list, IIRC (maybe more).  The code I've seen, and I 
don't remember which module, looks at the first =item and uses that to 
decide what type of list to create.  For example, if the first =item is 
like "=item *", it assumes that a bullet list is wanted.  But if the 
first =item is of the form

	=item This is some text

it assumes that a definition list is desired, and for just these lists, 
it creates anchors for the =items in them.  In the example, L</This is 
some text> would be a link to that =item.

If this is still not clear, let me know.

Perhaps what is meant in the comments is that you can't use L<> to link 
to most =item's.  If you need to refer to one, perhaps you should use 
C<> markup to distinguish it from regular text.  But the C<> would be a 
verbal reference and not a clickable link.

Pod::Checker keeps both lists, and as a result I have to worry about 
this in podcheck.t, where I check that link targets actually exist.  It 
would be more convenient for me if I was passed one list for all the 
linkable targets; I'm not sure that a list is even needed for the 
non-linkable ones.  I don't know what the backwards compatibility issues 
are; I'm just saying that the current scheme makes the wrong 
distinctions for my purposes, and I can't imagine where the information 
is actually useful.