Documentation Channel for #raku | This channel is logged | Roadmap:
Set by [Coke] on 23 May 2022.
[Coke] doing a site publish to publish these changes 00:49
cfa [Coke]++ 00:50
[Coke] ugh 00:53
something in that has broken css for the site.
I tested it in dev first, to no avail
(it worked fine there)
cfa i just encountered that but it's working after another refresh 00:54
(or at least, a force refresh)
[Coke] i tried redploying the previous version as part of this. deploying latest again... 00:55
oh. looks like I just deployed the latest 3 times? apparently redeploy on an old version just pushes the latest
the colors on the main page are wrong, syntax highlighting is missing... 00:56
cfa working for me 00:59
Geth ¦ doc-website: coke assigned to finanalyst Issue css broken 01:00
¦ doc-website: coke assigned to dontlaugh Issue css broken
[Coke] 01:01
I've cleared cache, no help.
cfa it's not working for me in edge -- i'm getting a green template with no highlighting
but force refresh/reload worked in firefox and vivaldi
caching? 01:02
[Coke] not here, as I cleared cache?
cfa oh, working in edge now
in an incognito/private window
[Coke] probably need cache buster on new css when deploying. 01:03
cfa does it work in a private chrome window for you? 01:04
[Coke] e.g. foo.css?id=1 # increase with each change
private chrome, yes. but reloading in the main window, clearing cache, all does nothing. wtf 01:06
ok, well, if it's just me, that's fine. 01:11
seems fine in ff, incognito.. ah. safari has the same issue 01:12
cfa it's not just you -- same issue for me in non-private edge window 01:13
(which is basically chrome under the hood, i think)
02:12 rf left 05:48 cfa left
Voldenet `green mode` is probably related to my patch somehow, it means that `light` and `dark` themes are switched off 06:13
light or dark mode css files are supposed to have _disabled_ attribute set 06:19
if you attach debugger, see if things are building properly here 06:21
(I can't reproduce the issue anywhere, so it could be some caching problem, initial themes resolving ignore values from localStorage) 06:22
tested on edge, chrome and firefox
s/ignore values/ignore invalid values/ 06:23
08:42 sena_kun joined
Geth doc: 2colours++ created pull request #4219:
Rewrite the "make your own operator" example
doc: tbrowder++ created pull request #4220:
Ensure the 'Brackets' table generator always uses the data source file
[Coke] Voldenet: if both themes are switched off, how do I turn them back on? toggle theme no longer works for me. 13:27
also, something has impacted the highlighting; for those who aren't in green mode, can you still see the code highlighting? 13:28
I have $dayjob today, but please let me know if there's something I can be checking in the console, etc. 13:29
Voldenet [Coke] every theme has lists of links to enable or disable, so you can set breakpoint here: and see what elements are going to be disabled/enabled 14:14
afterwards run change_theme("dark") or change_theme("light")
If css files are not loading properly, then you'll see elements as being disabled/enabled just fine, but nothing will work 14:15
if change_theme returns false it means that the link[rel="stylesheet"] elements were not indexed properly during initialization at all 14:25
[Coke] Voldenet: I just got 5m to go check the site; it's fine today. 14:28
did your PR make the themes better integrated with ff? 14:39
Voldenet yes, did check that page switching works 14:42
s/page/page style/ 14:43
[Coke] how to trigger in ff? 14:44
Voldenet 14:46
[Coke] I went to themes, preferred dark, no change (maybe I already clicked on a theme choice in the site, though) 14:47
Voldenet I didn't change the behaviour that was there before – the initially loaded theme name is persisted in localStorage
[Coke] ok. can we also get it working with picking dark in the themes settings?
Or should that also be working? (let me kill my cookies) 14:48
killing cookies and reloading, didn't respect my "prefer dark theme" choice, fyi. Menu integration works fine. 14:49
Voldenet cookies =/= localStorage
14:50 rf joined
Voldenet Maybe persisting the theme change on click only makes more sense 14:50
[Coke] ah, thanks, yes. checked the "data" boxes on clear as well, and it's all good. Nifty, thanks!
Voldenet >
it could be changed easily to not persist the theme from prefers-color-scheme 14:51
[Coke] I'd definitely consider a PR for that.
Voldenet (in that case click would have to be changed to use state variable for this, because it uses the localStorage to keep the `currently chosen theme`) 14:52
14:53 CIAvash left
Geth doc/main: d66241c3da | Coke++ | doc/Language/intro.pod6
Update perl6->raku section

  * move to end of file, reduce importance
  * Remove old NYI tag
  * Add .rakutest
doc/main: 26dd5e260e | (Márton Polgár)++ (committed using GitHub Web editor) | doc/Language/js-nutshell.pod6
Rewrite the "make your own operator" example

The previous one was a mis-implementation of an actually existent operator `||=`.
doc/main: f5c80f6c60 | cfa++ (committed using GitHub Web editor) | doc/Language/js-nutshell.pod6
Merge pull request #4219 from 2colours/patch-3

Rewrite the "make your own operator" example
15:27 cfa joined
Geth doc/main: 68ee7c5e85 | cfa++ (committed using GitHub Web editor) | doc/Language/js-nutshell.pod6
Fix: Add comment character to wrapped example line
15:57 CIAvash joined 16:27 lizmat_ joined
Geth doc/main: 0144e20110 | Coke++ | doc/Language/5to6-perlvar.pod6
Change emphasis to historical from not-updated
doc/main: 7214aae18c | Coke++ | 2 files
Remove intro table from intro entirely

Most of it was already duplicated in filename extensions; also update that table to reflect preferred first, and remove cro extension - not part of core, didn't change anyway.
16:32 lizmat_ left
doc/main: 199348e514 | Coke++ | 3 files
Update from .t to .rakutest

Avoid duplicating list of preferred AND historic extensions here, refer to existing list instead.
16:33 lizmat_ joined 16:36 rf left, lizmat left, sjn left 16:37 rf joined, sjn joined 16:46 lizmat_ left, lizmat joined
Geth doc/main: fe0dd7736c | Coke++ | doc/Language/5to6-nutshell.pod6
reduce prominence of name change note, text.
cfa [Coke]: re: .rakutest, should we rename the actual tests in the doc tree? 17:10
and do most editors already map .rakutest to a raku mode/filetype? 17:11
Geth doc/main: b117a7e79a | Coke++ | .gitignore
Clean up

remove a few old unused entries
[Coke] cfa: renaming the test files is on my list.
I need to make sure 'make test' still works when I do that.
if you want to do that, please let me know! 17:18
cfa oh, please go ahead (unless you need a hand) 17:19
i'm looking at tweaking a few examples today
[Coke] sounds good. Thanks.
coleman [Coke] would you mind doing an experiment for me 17:24
Can you log into Hetzner and try to issue yourself an API token?
My cursory reading of the permissions in Hetzner is that you can't. But always better to test. 17:32
No need to try anything with the token, just poke around the UI
[Coke] api tokens under security is grayed out 17:33
so, can't even.
coleman Thanks for testing! That is what they're docs said would be the case.
I think only admins can issue them. Hetzner's permissions aren't super granular. 17:34
[Coke] the change to rakutest requires a few more change than just file renames, but should be fine. Running a full maketest right now.
coleman: no idea why I got "green mode" after the last push, and for less than a day.
coleman I have seen it before. The next time it happens, I'll use the browser tools. Perhaps there is some boolean-type logic that is being affected by browser caching. 17:36
Caching feels related, but there may be something more subtle.
[Coke] clearing cache didn't seem to help, but maybe i missed local storage 17:37
coleman I'm inclined to live with this for a bit. I am a bit worried about complicating our build process. 17:40
My next action for the build is to make it public
And for that I need to get it off my personal server and into the collective Hetzner :) 17:41
Just to make absolutely sure we don't leak any secrets
It'll be easier for everyone to grok the container build once they can see. 17:42
Voldenet all files are served with `cache-control: max-age=14400` header 17:45
coleman Is that always the web server? Or can html tags do that 17:48
Geth doc/main: 098dae258f | Coke++ | 56 files
Rename our own test files from .t to .rakutest

Update testing module, corresponding tests that depend on file extension also.
coleman You're talking to a web n00b
coleman (me)
[Coke] I don't think html attributes can impact the actual http headers, but it's been a minute
Voldenet they can't, that's the point
[Coke] s/impact/change/ - I think they can influence the cache behavior, ofc. 17:50
Voldenet to be honest, best strategy to prevent caching I know (and it's a problem I've seen 100 times) is to generate unique filenames for unique files 17:51
I mean, it wouldn't prevent caching, just it would prevent serving stale version as the new one
[Coke] Voldenet: I've historically done the dumb number ID on each prod release.
Voldenet it sort of works, but if it's manual you end up forgetting to change the id 17:52
and if it's auto you end up overserving
[Coke] so, dumb number, deployment CI updates the number, then every request for an internal js/css/etc. calls with ?id=xxx ; you only have to deal with telling so many users "please clear your cache" before you get this sorted. :)
better overserving than telling users to clear their cache. 17:53
coleman Voldenet: that's what I've seen googling this issue. So perhaps our build script can generate names based on git sha
Voldenet you end up overserving a lot of unchanged js/css then
coleman a query param works too, but I like random filenames better
anyways I gotta go right now. FWIW I'm not wild about the fact that we have to reach into Finanlyst's personal repo to make changes like this 17:54
Voldenet sha1 of the file contents is pretty good way to make sure things are unique
coleman unless i'm missing something 17:55
[Coke] which repo of his are we using directly?
coleman (which I probably am. I don't understand the plugin system)
[Coke] one of the raku deps?
coleman This is what CI invokes to build the artifact 17:56
[Coke] Collection is a module in the ecosystem - we're tied to a specific version so it shouldn't be any surprises. 17:57
Ah, no, it's that version or higher.
coleman I'm okay with depending on his modules
[Coke] But we are OK to rely on things in the ecosystem; if we need to, we can fork them into community modules or raku/ itself if it's a docs-only thing.
oh, OK. 17:58
coleman I just would like to make things a little less opaque and magical.
let's just start with more comments in the code lol
I just remember quite clearly being blocked last year on pending merges to this and that
That's another reason why I want to keep this a static site for now. Keep it as simple as possible so that we can always have live docs :) 17:59
Then document the more complex stuff :)
Geth doc: cfa++ created pull request #4221:
Prefer OUTPUT: «…» in examples
cfa okay added a few more to that PR 18:22
but i think i'm done for now
i'll squash and merge? 18:23
[Coke] (y) 18:28
rf Did we get rid of typegraphs 18:29
Geth doc/main: 80de6d52c9 | Coke++ | doc/Language/filename-extensions.pod6
Move note out of table!
[Coke] - there's a good reason to stage content changes, I borked the table.
Geth doc/main: 5265a6efde | cfa++ (committed using GitHub Web editor) | 21 files
Prefer OUTPUT: «…» in examples (#4221)
doc/main: 5e6c63d5ca | cfa++ (committed using GitHub Web editor) | doc/Type/Mu.pod6
Mu: Tidy link to "Mu (negative)" on Wikipedia
cfa [Coke]: are deployments to docs-dev manual, or is there periodic refresh there? 18:44
[Coke] coleman: regarding log access - is this something i have now since I can get into hetzner? 18:56
cfa: periodic, I think there's a 30m ish update from docs repo, 60ms update from website repo
coleman: none of the ip addresses I see in hetzner match the public ip for the doc site 19:00
coleman it's behind a load balancer
[Coke] ok, but the load balancer ip doesn't match either. 19:01
(was trying to see if I could through to a volume with logs somewhere) 19:02
GAH 19:04
so, I'm looking at the maintence alerts. click X on 2 of them. go to click the third, it's move as a result of closing the otheres, click on POWER OFF SERVER.
thankfullly it said "are you sure, idiot?" so I didn't do it. 19:05
cfa ha ha 19:12
[Coke] this on hetzner. 19:13
crap, every time I read i find another thing to fix. I am not a good editor! 19:16
cfa btw, anyone else seeing this when they build the doc site? 19:24
Website/structure-sources: Caching files
Completed in 0m:0s
fatal: cannot change to 'local_raku_docs': No such file or directory
i haven't tracked down where the attempted directory change is coming from 19:25
i see this each time i build (but haven't observed any problems, so not sure what that step is meant to achieve)
(sidenote: has apparently misordered and 19:27
[Coke] what is tghe command you run to get that error? 19:28
cfa $ ./bin_files/build-site 19:30
it occurs just before the rendering steps 19:31
here's the full output: 19:32
also the progress bars are a bit wonky 19:33
Geth doc/main: ddedcaa51b | (Will Coleda)++ | util/
util for running make test before commit
doc/main: ebe807a65e | (Will Coleda)++ | doc/Language/filename-extensions.pod6
Update entire page, not just the table.

  (the text referenced the table, had to adjust)
[Coke] says you shouldn't have to clone it manually... 19:37
but you can probably figure out the manual step req'd here - please also open a ticket showing how the default instruction isn't working here. are you sure you have access to git, etc? 19:38
maybe Collection needs to be verbose if the git command fails or something.
cfa clone what manually? 19:39
[Coke] the docs repo 19:40
cfa i didn't
it's pulled automatically
[Coke] right. the instructions say it does it for you, but since it's not doing it for you...
if it is pulled, is it where the error is saying it isn't? 19:41
cfa i'm only asking about the output marked "fatal"
everything works fine here
but the output indicates something has gone wrong
[Coke] ... YES 19:42
so, the help says it should create that folder for you. the output of the script indicates that that didn't happen.
cfa the folder exists
otherwise i wouldn't be able to build and view the documentation
[Coke] ok, so the bug is: "why is the script complaining about it"
cfa right that's all i'm asking
it seems like a false positive 19:43
[Coke] right, please open a bug.
cfa are you seeing it?
[Coke] we'll assign it to richard, he's never on IRC.
cfa sure
but my question was whether anyone else is seeing this same message
[Coke] testing now 19:45
... ah. Right. I can't run this on my m2
cfa thanks
hmm, i could try building on my other work box 19:46
cfa installs deps there 19:47
[Coke] cfa: love the github avatar, btw 19:49
is that from when he's talking to morden, I wonder.
cfa :) 19:51
and yeah, i think it is 19:55
(it's a few seconds away from the famous wave)
[Coke] NEAT 19:56
cfa this reminds me that i've yet to see the remastered series 19:58
[Coke] it's in my queue 20:02
cfa good stuff 20:03
(btw, that 'fatal' line occurs on my work box too; will file something in a few)
[Coke] Thank you! 20:07
cfa 20:12
it's a low priority issue
[Coke] coleman: can I see the schedule for the dev site? pipeline says nothing scheduled. 20:17
cfa it recently updated 20:18
fwiw 20:19
e.g. i see my change to Mu
[Coke] yup. was going to consider starting a manual one, then thought to check the schedule..
Geth doc/main: 75388e30aa | cfa++ | 21 files
Add missing ␤ characters to OUTPUTs
cfa okay, i think that's enough of that for one day 20:40
q. time consuming
[Coke] cfa++ 20:44
coleman [Coke] The dev site is automatically self-updating. It uses a cron job (technically a systemd timer) to re-pull the latest container every 30 minutes 20:45
We expose a button for prod, because we can't use a cron-style strategy 20:46
not at the moment, anyway
check Raku/infra for the configs
[Coke] ah, it's a cron job somewhere - there is also a way to schedule it from the pipeline screen, which is what I was looking at.
coleman That should be prod-only 20:47
I am planning on giving you a lever to pull for dev, as well 20:48
And perhaps even fancy stuff like pre-merge deployments (for funkier changes)
Right now this was simple and expedient, though.
[Coke] yup, that's fine. 20:50
Geth ¦ doc-website: finanalyst self-assigned Add section link to each section 21:12
¦ doc-website: coke self-assigned Create 404 page 21:18
[Coke] will do another push to prod later this evening to catch any content updates and hopefully fix the 404 issue. 21:50
getting the 404 page in place will hopefully give us feedback on any other missing items until we can see the logs., 21:51
22:09 rf left
Geth doc-website/tie_search_to_host: 2d4367afec | finanalyst++ | 2 files
tie the search Google call to the hostname of the site.
doc-website: finanalyst++ created pull request #170:
tie the search Google call to the hostname of the site.
doc-website/main: c1c465dadb | (Richard Hainsworth)++ (committed using GitHub Web editor) | 2 files
tie the search Google call to the hostname of the site. (#170)
[Coke] btw, Richard is working on something that he really needs to test on raku-dev, please don't push to prod until we hear from him that it's ok 22:31
coleman understood 22:35
[Coke] I am very happy that my doc changes will be live in <24h! 22:37
coleman: what version of Caddy are we using? 22:40
Geth doc-website/404: 3a196579be | (Will Coleda)++ | Caddyfile
Use custom 404 file
coleman I believe the container build points to latest
Geth doc-website: coke++ created pull request #171:
Use custom 404 file
doc-website/main: 4a554aeb52 | (Will Coleda)++ (committed using GitHub Web editor) | Caddyfile
Use custom 404 file (#171)
[Coke] cool. the 404 change worked locally, merged it. 22:48
Never used caddy before, but it seems fine.
coleman It's pretty great 22:49
You're living my Coleman's Infra Opinions world now 22:53
enjoy your stay
23:00 rf joined 23:03 sena_kun left
[Coke] I've stayed in worse clouds. 23:05
Geth doc/main: a13058f24c | (Will Coleda)++ | .gitignore
Remove obsolete files

These used to belong to the link checker, which is now run as part of doc-website - script is long gone.
doc/main: adca8424cc | (Will Coleda)++ | 5 files
Remove old site templates

These are now handled by doc-website
Closes #4214
[Coke] 30 tickets left in raku/doc to close in the next month. 23:13
coleman [Coke] I tagged you on a PR in Raku/infra that has some details about the deployment
no action required but it's FYI
[Coke] - some of these are straightforward, please feel free to self-assign one.
danke 23:15
Geth ¦ doc: coke assigned to dontlaugh Issue Possible usage of SparrowCI for some CI tasks 23:16
doc-website/disable_git_reflog: ece28d3777 | finanalyst++ | Website/configs/02-plugins.raku
disable git-reflog plugin
doc-website: finanalyst++ created pull request #172:
disable git-reflog plugin
doc-website/main: 327b86349d | (Richard Hainsworth)++ (committed using GitHub Web editor) | Website/configs/02-plugins.raku
disable git-reflog plugin (#172)
doc/main: 6a53615de8 | cfa++ | 8 files
Add in a few more missing ␤ chars
23:30 NemokoschKiwi joined
cfa hey NemokoschKiwi 23:30
NemokoschKiwi sssh :D 23:31
coleman hahah :)
NemokoschKiwi well, I also wanted to bring up the milestones... 23:32
first off, it's REALLY good to see that issues are being sorted out, solved, migrated to more suitable repos etc. 23:33
I don't know if the number of issues and their categories is traced anywhere but these days the progress would probably look really good 23:34
the thing with the issues assigned to the next milestone is... well, I'm afraid the same can be said for the majority of issues from now on... 23:35
they are hardly "actionable". They make perfect sense as issues but what to do about them is a whole another story. 23:36
[Coke] So what's your recommendation? 23:43
NemokoschKiwi semi-ironically: to ask the same question from the people who opened those issues 23:46
Geth doc/rakudoc: cfbb963a0c | (Will Coleda)++ | t/04-pod6.rakutest
Remove obsolete xt test preventing .pod files
doc/rakudoc: 3f548619c7 | (Will Coleda)++ | 824 files
rename files from pod6 to rakudoc
doc/rakudoc: 7eda3948e0 | (Will Coleda)++ | 18 files
track file rename from pod6 to rakudoc
doc: coke++ created pull request #4222:
[Coke] ... the ones who opened the issues don't set the priority on resolving them.
so if you're ask is "what's the priority" - it's to work on them in the order suggested by the milestones. 23:48
Once all the tickets in milestone A are complete, we can start working on the next one (whether that means moving them to an earlier milestone or just working on them in place will be decided then, and will depend in large part on whether the milestone is complete) 23:49
it sounds like you're complaining that tickets in milestone B (in this case, 2023-Quarter 2) are not actionable - they aren't intended to be worked on now. that's why they're in the later milestone.
s/is complete/'s due date has passed/ 23:50
NemokoschKiwi I'm talking about "milestone A" according to this terminology 23:51
[Coke] so, the tickets in 2023-Quarter 1 ? What's the question specifically?
that's this listing: 23:52
NemokoschKiwi Yes, this listing
[Coke] #404 now working 23:53
Will push 404 work once Richard tells me his work is safe.
cfa [Coke]++ 23:54
NemokoschKiwi looks pretty cool haha
back to the "milestoned" issues...
"What's really autothreading and is it used correctly?" "Is @*MODULES spec?" "No mention of NFG in the docs?" "Docs on exceptions do not mention failures at all." 23:55
To recite a few
I have read the content of them, mind you
and it's like... "okay, the problem is well understood - what to do about it now?" 23:56
[Coke] ... write the docs 23:57
NemokoschKiwi which is not to say that they aren't solveable but one will have to keep making decisions - loads of decisions
[Coke] If you don't see how to answer the general question, then you're probably not going to end up working on those tickets. No worries.
Yes, one will. Not you.
At least, I do not expect it to be you
NemokoschKiwi somehow I suspect that there aren't so many "ones" though; that's why we actually have an issue-issue 23:58
[Coke] If someone wants to volunteer for a specific ticket, I'm happy to suggest how to approach it. I don't plan on writing up detailed instructions for each ticket when writing the docs is probably only slightly more effort. If I had volunteers/interns/apprentices this calculus would change.