Headers that are not returning to Top

finanalyst commented 1 year ago

All heading should be clickable and should have a hover title that says Go to Top. Some headers have this, some do not. The headers that do not have the <a> tag correct, but the tag is over-riden or does not encompass the span containing the title words.

The problem appears to be related to other formating in the title text.

finanalyst commented 1 year ago

As examples, in the page on operators, the level2 headers tr///, TR///, and 'Reduceall are clickable and have a hover text 'go to top'. The level2 headersNegated relational operatorsandReversed operators` do not.

The expected behaviour is for them all to be clickable.

The non-clickable headers seem to have their <a>..</a> tags incorrectly placed.

This behaviour seems to occur in HTML rendered by Pod::To::HTML and Pod::To::HTML2

finanalyst commented 1 year ago

The problem seems to be with the html!!!!!! Below is an html file containing a problematic header and a header that acts as expected. When I serve this using Cro or Apache or Comma, the browser (I use Firefox) re-writes the html!!!!!

I also see that the result using Comma's internal browser does the same thing.

I was not expecting the html re-write but because this happens across two browsers, I wonder whether it is specified.

So, the original html including two headers is

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Test</title>
</head>
<body>
    <h2 id="Negated_relational_operators">
        <a href="#___top" class="u" title="go to top of document">
            <a name="index-entry-Metaoperators_!_(negation_metaoperator)-Negated_relational_operators"></a>
            <span class="glossary-entry">Negated relational operators</span>
        </a>
    </h2>
    <hr>
    <h2 id="Metaoperators">
        <a href="#___top" class="u" title="go to top of document">Metaoperators</a>
    </h2>
</body>
</html>

Note that the <a> tag immediately after the <h2> opener is supposed to end immediately before the </h2> closer. However, after serving the file and looking at the html using developer tools inside Firefox, I get

<body>
    <h2 id="Negated_relational_operators">
        <a href="#___top" class="u" title="go to top of document">
            </a><a name="index-entry-Metaoperators_!_(negation_metaoperator)-Negated_relational_operators"></a>
            <span class="glossary-entry">Negated relational operators</span>

    </h2>
    <hr>
    <h2 id="Metaoperators">
        <a href="#___top" class="u" title="go to top of document">Metaoperators</a>
    </h2>
</body>

Note how the <a> tag is closed before the next <a> opener and not before the </h2> closer.

This means that Firefox has re-written the html.

The difference between the two headers is the internal <span class="glossary-item">.

finanalyst commented 1 year ago

Further to the above. How did we get the internal <span> and the extra internal <a>? The reason is that the original authors of the Raku documentation were inconsistent about headers. They wanted to ensure that some header titles were included in the glossary (that is in whatever structure is used to collect X<> markup).

When the Rakudoc (Pod6) directive X<Put this text in an index> is rendered into html, it is replaced with <a href="target-this-place"><span>Put this text in an index</span></a>.

So there are three options (I think) to get the headers to work as expected: a) find a workaround that allows for both the X<> rendition - possibly incuding another <div> b) eliminating all X<> markup during the rendering process c) removing all X<> markup from =head? blocks in the Rakudo (Pod6) sources.

Personally, I think in the near future option 3 should be used. It can be done with a Raku script. I think that the =head? X<header text> combination was only used by early authors and is not common in the Rakudoc sources.

There is absolutely NO reason for using X<> markup in a =head? block because renderers collect header information in order to compile a Table of Contents. This information is used by search utilities in any case.

However, this is a Content issue and is probably documented in Raku/docs.

In addition, I do not want to delay getting this website live.

So there are the top two options. Essentially one is to keep the X<> anchor inside the header, and the other is to eliminate it.

Since everything is done using templates, and the relevant part is the heading key inside Website/templates/01-default.raku, it is easy to implement either of these options.

Although I would personally eliminate all trace of the X<> markup, this will create index (glossary) entries without anchors. Whilst I think the Raku documentation website does not use the index (glossary) information in a consistent manner, I am not sure about some inconsistent author choices.

Consequently, I shall implement a template that keeps the index target, but places the header text inside the first <a> container.

coke commented 1 year ago

only 12% hits, but 379 is still a lot of places.

$ ack =head2 doc | wc -l
    3149
$ ack =head2 doc | grep 'X<' | wc -l
     379

finanalyst commented 1 year ago

I have fixed the issue now. I'm just building the whole website to put on new-raku.finanalyst.org to ensure the fix doesnt hit some corner case. All being well I'll then do a commit to here in a few minutes and close this particular issue. I'll raise the Content issue in due course.

finanalyst commented 1 year ago

All headings are now clickable - I think. Option (a) above was implemented.

Raku / doc-website

Headers that are not returning to Top #3