AW: Pod::Html's cross referencing of C links
Hi Marc, IIRC C stands for code, which means for renderers to set the included ext in a fixed-width font (courier-like). It is by no means a hyperlink. I know that some POD tools tried to apply some artificial intelligence to check whether text in B or C or I could be a reference to a manpage, a =headn section or an =item, but the results are often awkward. Therefore, if I may throw in my 2c, I suggest to stick with the perlpodspec definition: hyperlink destinations are the texts of =headn and =item (stripping all potentially included markup like C B I), and the only way to reference these is L/text or Lpage/text. Examples: Cgrep /string/ - this is just highlighting the text in typewriter font =item grep /string/ ð This is a hyperlink destination (and a list item, of course) =item Bgrep I/string ð This is basically the same hyperlink destination (same text content) L/grep /string/ - this is the hyperlink to the above item -Marek Von: Marc Green [mailto:pongu...@gmail.com] Gesendet: Samstag, 21. Mai 2011 19:55 An: Karl Williamson Cc: pod-people@perl.org; tchr...@perl.com Betreff: Re: Pod::Html's cross referencing of C links On Sat, May 21, 2011 at 10:54 AM, Karl Williamson pub...@khwilliamson.com wrote: 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. Ah, I think you are right. Thanks for clarifying. I don't know when the specification changed, but after another read of the current perlpodspec http://perldoc.perl.org/perlpodspec.html#About-L%3C...%3E-Codes , I have an answer: Previous versions of perlpod distinguished Lname/section links from Lname/item links (and their targets). These have been merged syntactically and semantically in the current specification, and section can refer either to a =headn Heading Content command or to a =item Item Content command. Well, it is not an answer to my original question, but it helps me make the executive decision to consider C links as L links. Thanks for the help, Marc
Re: Pod::Html's cross referencing of C links
* Marc Green pongu...@gmail.com [2011-05-20T16:24:21] links. More specifically, I understand how it resolves L links, but I am confused as to why you resolve C links. From reading the source, I gather that C links are resolved by searching pod documents for =item directives, and storing their text in a global hash. Marc is referring to comments like this: my %Pages = (); # associative array used to find the location # of pages referenced by L links. my %Items = (); # associative array used to find the location # of =item directives referenced by C # links ... # scan_items - scans the pod specified by $pod for =item directives. we # will use this information later on in resolving C links. c. -- rjbs
Re: Pod::Html's cross referencing of C links
On 05/20/2011 03:16 PM, Ricardo Signes wrote: * Marc Greenpongu...@gmail.com [2011-05-20T16:24:21] links. More specifically, I understand how it resolves L links, but I am confused as to why you resolve C links. From reading the source, I gather that C links are resolved by searching pod documents for =item directives, and storing their text in a global hash. Marc is referring to comments like this: my %Pages = (); # associative array used to find the location # of pages referenced by L links. my %Items = (); # associative array used to find the location # of =item directives referenced by C # links ... # scan_items - scans the pod specified by $pod for =item directives. we # will use this information later on in resolving C links. c. 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.
Re: Pod::Html's cross referencing of C links
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.
