Language page categories

[finanalyst]

The problems

1. The Language page (https://docs.perl6.org/language.html) contains a table of pages in an apparently random order because it depends on the name of the underlying pod6 file.

• Tom Browder did most of the work to change this, but there was no distinction between the headings and the pages, and there was a link problem because links defined in the original pod files do not correspond to the re-ordered pod file

2. A brief introduction to the Documentation is added to resolve Issue Create a HOWTO for newcomers to the repo #2266

Solution provided

• Tom's work is modified to produce a language page that is based on his Control file.
• The Headings of each section become level 2 headings on the language page, and the sub-pages are combined into tables.
• The Makefile has been modified to include a new variable USE_CATEGORIES, which is set to False by default
• Only when USE_CATEGORIES is set to True in the Makefile will the Categories be introduced. Thus merging these changes will not affect the current behaviour.
• The mechanism for keeping the section headings and distinguishing between section pods and content pods is by creating a :class in the section pods.
• The mechanism for keeping the old pod filenames is to introduce a :link<$key-fname> into the pod, and to ensure that the url attribute takes the old name.
• The Language page now (if USE_CATEGORIES is set to True) looks much better and is more easily understandable. It also has a TOC.

[JJ]

I am very wary of accepting changes in htmlify.p6, since there's no test or specs on how it behave, the only way we have to know is to put it to use and check if it breaks anything. For the time being, it looks like it has not... So waiting for @tbrowder green light (who knows better this stuff), I'd say it's OK. Thanks a lot for your work.

[AlexDaniel]

This is not aligned vertically with the rest of the lines

[AlexDaniel]

No need for the semicolon here.

[AlexDaniel]

This whole document says “Perl6” when I think we settled on “Perl 6” with no-breaking space. Maybe it is worth changing it, although with recent discussions regarding an alias it may be worth to reword some sentences so that the language name is not spelled out. @JJ what do you think?

[JJ]

That can be fixed when approved, no big deal.

[AlexDaniel]

@tbrowder pinged me on IRC. I looked at the code, seems to be OK. I left some nitpicking comments. This seems not to have blocking downsides that we previously had with @tbrowder++'s solution, so I recommend setting it to True by default.