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.
