raku / doc-website Goto Github PK

Please pin the dependency versions in META6.json to specific known-to-work versions.

The div containing the Category information at the very bottom of the first column is being moved to the top of the right-hand column.

The CSS needs changing to fix this.

A REPL bar plugin (raku-repl) is included but not used because the CSS currently associated with it does not match the UX of the rest of the site.

A better rendering of the REPL bar is needed, and then the plugin can be enabled

We already document the issue with automatically installing Cro, we should still declare it as a dependency in meta6.json

Problem or new feature

This is simply a file that specifies the pages in the site. Good for SEO.

Suggestions

Modify Documentable so that it generates a source map at the same time as the documentation files.

Create the template / plugin for the Extended search

site says "Welcome to the alternative[1] official documentation of the Raku programming language!"

Before go live, this should remove the alternative.

The categories are repeating. Eliminate the duplicates

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.

Url: https://docs.raku.org//type/IO::Socket::Async

Code highlighting seems to add an extra space? See screenshot:

Right now, if one clicks on the "toggle theme" caption, it does work - however, a site reload or navigating to another page will reset to the light theme.

The themes are backed up by cookies. Perhaps it would be possible to fix them with some setting for the server - however, I think it's worth considering to switch to localStorage which is a simple and stable API and won't send any data to the server.

it's mentioned in the README and a few other places, but it's unclear what the name is supposed to mean.

Altai-man/docs.raku.org#81

@CIAvash changed the search and this fixed a couple of problems with the fundamentals of it.

Perhaps this site should also adopt that search.

"chat with us" takes the user to freenode, not libera.

Aleks-Daniel Jakimenko-Aleksejev - adapted web design for Raku documentation and implemented it with Documentable.

The URL should lead to github profile yet it's rendered... weirdly. The same happens with other URLs on that page.

The problem

The highlights node library is used to highlight code. However, the line installing it declares its version should be lower than 2.0

That's causing some problems with the Docker build Raku/doc#2525, namely, there's some library (oniguruma) that needs to be recompiled for some reason. Adding npm rebuild to the Makefile seems to fix the problem, but still.

There are also some warnings about possible security problems.

Suggestions

Check with the author, @samcv , if there's a reason for that and upgrade or just use the latest if possible.

The index (home) page will be changed completely. Altai-man has a different UX see. I'm working on it.

Please add Artistic 2.0 for our license file.

The dark theme of the Routine page could do with some TLC. I'm not in love with the rendering of the TableManager inserted divs.

The relevant SCSS can be found at Website/plugins/tablemanager/tm-dark.scss and ...tm-styling.scss

Problem

Pages on the Raku Documentation site don't have “Raku” anywhere in their HTML <title>s. That makes it less obvious what the page is about from just its title:

• A user could have tabs open for similar topics in different programming languages, and the title doesn't help know which one this is for.
• I knew I'd visited the Classes page earlier today and was trying to find it in my browser's history. Typing “raku class” didn't match, because “raku” isn't anywhere in the page's title.

Suggestions

In the site generator, append “| Raku Documentation” to the end of each page's title. That puts the information in there, while avoiding every page on the site having titles that start the same (which is the bit often showing when truncated in browser tab bars).

Problem or new feature

Type relations for 404 on https://docs.raku.org/type/X::Control

If I search for a term on docs.perl.org by typing in the search box and hitting return (so, not selecting something from the menu that pops up), I get the first thing in that menu. For instance, typing out "encoding" has a popup menu that only lists "study", so I get "study" if I hit return without selecting from the menu.

A "search this site with Google" option would be nice. Or even a different search box for that function.

Code blocks now can have an explicit :lang<> set; if this lang is not Raku, then we should not run the Raku syntax highlighter on those snippets of code. (See, for example, https://docs.perl6.org/language/rb-nutshell, which has many sections that are marked as :lang, and therefore should not get Raku highlighting)

The problem

In the operators page a lot of anchors to individual operator section are visible, non-narrative and slightly offset from the section's title.

See as examples:

• https://docs.raku.org/language/operators#index-entry-Negated_boolean_context_operator
• https://docs.raku.org/language/operators#index-entry-Negated_boolean_context_operator
• https://docs.raku.org/language/operators#index-entry-Addition_operator
• ...

This should probably be fixed, see Raku/doc@bc233e2#commitcomment-37190047

Suggestions

• Should the anchors be made invisible and stuck to the sections' title, as in https://docs.raku.org/language/operators#index-entry-prefix_decrement_operator ?

• Should the non-narrative description of the operators be kept, as in https://docs.raku.org/language/operators#index-entry-Division_operator ?

After cloning the repository, zef installing the dependencies and running bin_files/build-site, the following output is generated:

Already up to date.
<git -C local_raku_docs/ pull> was successful
local_raku_docs/doc: Caching files
████████████████████████████████████████████████████████████████████████100.00%
Completed in 0m:28s
Website/structure-sources: Caching files
████████████████████████████████████████████████████████████████████████100.00%
Completed in 0m:0s
Rendering Collection on 2023-01-22 at 22:53:46
Expecting, but did not get, a directory with ｢asset_base｣ and part ｢images｣
  in method asset-slurp at /home/pm1540/.rakubrew/versions/moar-2022.12/install/share/perl6/site/sources/F92650F2CEB9118638B7566E195B3CA15F04EBB9 (Collection) line 138
  in method asset-slurp at /home/pm1540/.rakubrew/versions/moar-2022.12/install/share/perl6/site/sources/F92650F2CEB9118638B7566E195B3CA15F04EBB9 (Collection) line 158
  in block  at /home/pm1540/.rakubrew/versions/moar-2022.12/install/share/perl6/site/sources/F92650F2CEB9118638B7566E195B3CA15F04EBB9 (Collection) line 353
  in sub collect at /home/pm1540/.rakubrew/versions/moar-2022.12/install/share/perl6/site/sources/F92650F2CEB9118638B7566E195B3CA15F04EBB9 (Collection) line 254
  in sub collect at /home/pm1540/.rakubrew/versions/moar-2022.12/install/share/perl6/site/sources/F92650F2CEB9118638B7566E195B3CA15F04EBB9 (Collection) line 20
  in sub collect at /home/pm1540/.rakubrew/versions/moar-2022.12/install/share/perl6/site/sources/F92650F2CEB9118638B7566E195B3CA15F04EBB9 (Collection) line 210
  in sub collect at /home/pm1540/.rakubrew/versions/moar-2022.12/install/share/perl6/site/sources/F92650F2CEB9118638B7566E195B3CA15F04EBB9 (Collection) line 20
  in sub MAIN at bin_files/build-site line 5
  in block <unit> at bin_files/build-site line 3

Consequently, the rendered_html folder stays completely empty.

a) there is an Errors page in the 'more' drop down on the navigation bar

• the intention is to encourage community members to find the errors and eliminate them
• errors can occur when links (eg. external web pages) are no longer active
• they also exist because links to internal targets are misspelt in some way

This is an addition of mine to the work I did when developing Collection. I thought it would be useful in general.

Should I leave it in?

b) Other test results could be added to the errors page.
Any suggestions?

c) There is a problem with the test as some valid links seem - I think - to be triggered. This may be due to the work to add extra functionality, so I need to look at it.

Raku compiler developers may also be interested in The RakuSpecification.

missing a space.

The problem

Searching for "slurp":

1. Turns up results for "sleep".
2. Doesn't include /language/io which is more like what I was looking for.

Suggestions

The problem

Language page is too long and is growing.

Suggestions

Split groups into separate pages with links from the Language page.

The change should be done after issue Raku/doc#2185 is closed.

The routines tab is not populated (like Extended Search). This needs populating.

The problem

In working on a test to find bad links in the html files, I have discovered this one:
L</routine/…> in Language/math.pod6. It generates the anchor <a href="/routine/...">.

There is an html file html/routine/....html which has been generated. However, putting docs.perl6.org/routine/... into a browser will generate an error. (Note that the configuration for docs.perl6.org automatically adds .html onto any route, so language/math will GET language/math.html.

The problem, it seems, is that ... is not a normal sort of route. There are also the html files ..html ...html and these cannot be reached either. However, ..html reaches / and so testing for the link target with wget will generate a 200 response, even though the target has not been correctly hit.

Add to this a target to the file syntax/?.html. As we all know ? in a URL has a special meaning in some contexts, so using ? and . as parts of the names of html file is suboptimal.

Suggestion

1. Add a rewrite to .htaccess so that . goes to ..html, etc. (I do not know if this will be possible, nor do I know whether it is a good idea to remove . and .. as pseudo routes.
2. Declare in the Documentation specifications that links to files with . be given as $DOT and ? with $QMARK. This would be in addition to $SOLIDUS that already exists for / in names.

I cannot push changes from my local repo to the github repo

Here, the 'There are no backslashes here' string is highlighted incorrectly.

Pod documentation that is: =begin code :allow<B L> highlights as Pod not Perl 6 code. It is the :allow which causes this.

htmlify.p6 passes these as Pod to the highlighter, and so it gets highlighted as such (this is to allow us to make things bold/other styles).

Proposed solution from the docs side: we need to parse this Pod and strip it of Pod tags, and insert special Unicode control codes which nobody will have in normal text. These control codes can then be removed in the htmlify.p6 side once the highlighter highlights them.

From the highlighter https://github.com/perl6/atom-language-perl6 side, we will tag these differently than normal code, so we can add that effect in the CSS.

When a node, eg. for type xxx, in a typegraph is clicked, it should open the relevant Type/xxx web page.

But the url is to type/xxx not to type/xxx.html. In general, I have always added .html to all url generators. I know that some (but not my Apache server) automagically add .html to urls without a file extension.

So the issue is whether the infrastructure will add .html or whether to ensure all urls have .html

The home page does not match the new UX.
Includes #20 #21

Html escaping problem

The header at the top of a doc page shows e.g. infix &lt;== for an explanation of <==. This should show infix <==. This goes for all operators where a < or > is involved.

Example pages are infix =>, syntax << and infix <==.

For example, if you search for is-approx, the link will lead here; hiding the title of the section.

The same problem exists with glossary, when searching for, say, reify leads to this page, again, with the title of the section hidden.

I believe this is due to the X<> bits being below the title.

There's no easy way to look at https://docs.raku.org/ and see which version of the git repository was used to build the version of the site we're looking at. We don't need to advertise it on every page, but something in the console, or hidden markup/comment, or an unlinked file displaying the git reflog of the last build would be great.

If something like this already exists, we should document it in the README.

Language - Raku appears in this overview page multiple times, inconsistently using the TM symbol.

The readme mentions

The plugin SCSS (for example) can be changed, then updated into CSS using ./update-css <plugin-name>

Does this executable live somewhere outside this repo? Or is it installed as a part of some other tool? See also #6

'_'

should be written as

'\_'

The problem

This page is supposed to be an introduction to everything. But it does not include, for instance, about.html

Suggestions

That page should probably link every other page, but if there's a good reason to avoid some, it's probably OK. Anyway, it would be interesting to know which pages are not linked and why.

from from README.md

• Searching for Int.Bool returns the documentation for the
  inherited method Numeric.Bool.

The problem

In the (temporary|new permanent) infrastructure, docs are served directly from Mojolicious, not using the .htaccess file that apparently rewrote hash fragments to reflect what's actually in there. So all links like this one (seen in Raku/doc#2211) have stopped working.

Suggestions

There are 130 internal links that work this way:

git --no-pager grep "\#index-entry"  | wc
    140     680   15121

Fixing them is a lot of work, and will still make external links fail. So some way of rewriting should be reinstated, either in the infrastructure or at the documentation level.

We need to get the latest code from @finanalyst into the main branch of this repo.

These should be created when importing from raku/doc, not rendered and stored in the repo.

Most if not all Type pages have a Typegraph at the end of the page. This is generated svg. The Typegraph looks fine with the light theme, but does not look so good with the dark theme.

It seems that svg elements can have a theme.

The Typegraphs are generated using Doc::Typegraph.