Internal links from one function to another STILL broken

[greg-kennedy]

Same issue occurred in the previous iteration of the site.

Click on, e.g. the function reference for pack:
https://perldoc.perl.org/5.30.0/functions/pack.html

Scroll down to a link to unpack. Click it.

Rather than going to the unpack page, you are taken to a (non-existent) anchor on the current pack page.

This issue persists across multiple pages in the perldoc.

[JohnMica]

seems that code links work for the unpack

regular links do point to something nonexistent on the same page

will take a look at this for the next iteration

[cwagnello]

Looking through the project that contains the export, the links get broken going from v5.22.4 to v5.24.0

https://github.com/OpusVL/perldoc.perl.org-export/blob/master/5.22.4/functions/ord.html
https://github.com/OpusVL/perldoc.perl.org-export/blob/master/5.24.0/functions/ord.html

[nachanon]

Still reproducible on the current 5.30.0 rollout.

Please note that this problem affects many other pages; including, but not limited to...

• https://perldoc.perl.org/functions/hex.html

  Incorrectly linking to...

  • https://perldoc.perl.org/functions/hex.html#oct-EXPR
  • https://perldoc.perl.org/functions/hex.html#printf-FILEHANDLE-FORMAT%2c-LIST ^{(also see footnotes)}
  • https://perldoc.perl.org/functions/hex.html#sprintf-FORMAT%2c-LIST
  • https://perldoc.perl.org/functions/hex.html#unpack-TEMPLATE%2cEXPR

• https://perldoc.perl.org/functions/unpack.html

  Incorrectly linking to...

  • https://perldoc.perl.org/functions/unpack.html#unpack-TEMPLATE%2cEXPR ^{(actually, see footnotes)}
  • https://perldoc.perl.org/functions/unpack.html#pack-TEMPLATE%2cLIST
  • https://perldoc.perl.org/functions/unpack.html#pack-TEMPLATE%2cLIST

• https://perldoc.perl.org/functions/localtime.html

  Incorrectly linking to...

  • https://perldoc.perl.org/functions/localtime.html#gmtime-EXPR

• https://perldoc.perl.org/functions/gmtime.html

  Incorrectly linking to...

  • https://perldoc.perl.org/functions/gmtime.html#localtime-EXPR

• https://perldoc.perl.org/functions/time.html

  Incorrectly linking to...

  • https://perldoc.perl.org/functions/time.html#gmtime-EXPR
  • https://perldoc.perl.org/functions/time.html#localtime-EXPR
  • https://perldoc.perl.org/functions/time.html#localtime-EXPR

• https://perldoc.perl.org/functions/exit.html

  Incorrectly linking to...

  • https://perldoc.perl.org/functions/exit.html#die-LIST
  • https://perldoc.perl.org/functions/exit.html#eval-EXPR
  • https://perldoc.perl.org/perlvar.html#%24%3f ^{(actually, see footnotes)}

(And many, many, more)

---

Interesting that...

• https://perldoc.perl.org/perlpacktut.html does not seem to be affected.
  • ^ Every inline perlfunc links in this document are formatted as code; whereas those incorrect perlfunc links (in other pages) are all not.
• Links to function within modules does not seem to be affected.
• All syntax-highlighed perlfunc links in code samples does not seem to be affected.

There are multiple issues in the converter that resulted in these incorrect linkage.^{(see footnotes for other issues)} The principal issue reported in this ticket is what I would call "missing-pagename issue".

I was able to hunt down the lines in source POD each rendering error originated from. (I wish really I could link to each of them; but due to GitHub's limitations, I can't) From skimming through several affected pages and corresponding POD source, I could see following patterns...

• These kinds of links are affected by the missing-pagename issue:

    L<C<oct>|/oct EXPR>
    L<C<gmtime>|/gmtime EXPR>
    L<C<printf>|/printf FILEHANDLE FORMAT, LIST>
    L<C<sprintf>|/sprintf FORMAT, LIST>
  

• But these kinds of links are NOT affected by the missing-pagename issue:

    C<END>
    C<pack>
    L</kill()>
    L<DateTime>
    L<Time::gmtime>
    L<perlport/gmtime>
    L<C<$?>|perlvar/$?>
    L<C<POSIX::_exit($status)>|POSIX/C<_exit>>
  

From these patterns, I'd conclude that the converter did correctly consider these as links; but it failed to take account for POD -> HTML page splitting (perlfunc is a one big POD file; while in HTML version, each function goes to separate file) This directly resulted in converter's omission of page name in the link, thus "missing-pagename" problem.

For this reason, links to and within perlvar are not affected by this missing-pagename issue^{(but see footnotes)}; as its HTML version is a one big document like its original POD file.

---

Footnotes

Other than the missing-pagename issue, the converter also have problem with special characters in section name: not when generating link, but when generating the target anchor <a id="...">. I will distinguish that by calling it "improper-anchor-escape" problem.

Note that HTML anchor name itself is not a URI (even that it can be referred from a URI): URI encoding does not apply here; it only applies to the incoming link.

Nevertheless, the converter appeared to violate this, notably on HTML version of perlvar documentation at https://perldoc.perl.org/perlvar.html . For example:

• https://perldoc.perl.org/perlvar.html#%24%3f

  This URL should have linked to $CHILD_ERROR / $? item on the page. But it doesn't, because the perlvar page's code is improperly generated as:

    <li><a class='view-title' id="%24%3f"></a><strong>$?
     </strong>
  

  Rather than an expected one:

    <li><a class='view-title' id="$?"></a><strong>$?
     </strong>
  

Note that since Perl do have $", HTML entity escape should be used as needed. (Note that in HTML 4.01, id attribute does allow support HTML entity escaping, while name does; not sure for HTML5. But despite that, even old-generation HTML5 browsers seemed to happily accept entities in id field)