remove or fix perl6.html from docs.perl6.org

[finanalyst]

The problem

perl6.html is a file generated by Pod::To::BigPage whenever make html is triggered, which is whenever the documentation system is updated.

Problems with perl6.html:

1. Internal links do not work, eg. within the first, Intro, section, there is a link with text Useful Resources and the target reference https://docs.perl6.org/perl6.html#_routine_https:__perl6.org_resources.pod6. It does not link to anything. More typically, when there is a link in one pod source to an internal target in another pod source, the link does not work.
2. perl6.html is huge for a single html page at over 4GB of html text.
3. perl6.html takes a significant amount of time to compile each time.
4. perl6.html is not explicitly linked to from any of the docs.per6.org pages. It is mentioned somewhere.

Pod::To::BigPage is better than Pod::To::HTML in many ways. The single page html is useful. But it seems to me that because of its size, lack of inward links, and bad internal links, it is not suited to the docs.perl6.org system.

Suggestions

Remove the reference of the bigpage target from the recipe of make html

[JJ]

I don't think we're removing this. It would be better to fix internal links. It's 4MBs only. I don't know the reason why this ws included; I just changed it from .xhtml to .html. But I need better reasons, and a good consensus, to remove it altogether.

[gfldex]

Having the docs in one file allows for full text search and easy offline access to (most) of the docs. It can be used to print the docs without much hassle. It needs to be replaces for sure -- with something better. If you got the time to build a module that outputs a sane PDF-file of the docs, please do so.

EDIT: I designed the output to be strict xhtml because a browser will complain about malformed xhtml. Finding a bug in a 4MB file requires any help one can get.

[JJ]

For the time being, you can just print the HTML to PDF. We can release it too, if needed.

[finanalyst]

The bad links arise from a bug in writing links, but also because targets are not correctly specified for html.

It would seem, eg, that when an anchor element is a target for a ref, say 'perlref', it should be <a name="perlref"> not <a href="perlref">.

Who is going to create a pdf of all the perl6 documentation with now > 360 pod files? Is this such a massive use case to justify keeping and regenerating 'perl6.html' in docs.perl6.org for each change in indentation?

[coke]

My current plan is to remove the broken bigpage and instead focus on generating an epub file independently from the raku.docs.org site generation.

[coke]

https://github.com/Raku/doc-website/issues/75