Documentation Channel for #raku | This channel is logged | Roadmap: github.com/raku/doc/wiki
Set by [Coke] on 23 May 2022.
[Coke] cfa - if I was overzealous with some conversions to raku, please feel free to fix those. 01:11
I saw the user paths, and didn't realize that was the install path. 01:12
cfa sure, i'll send a pr in a few minutes
[Coke] maybe those should go back to the original, and wherever we mention the perl6/ install path, let's include the disclaimer.
Thanks!!
I should probably also be submitting PRs and not just pushing directly. Will endeavor to do so going forward.
Geth doc: cfa++ created pull request #4242:
Partially revert changes to `Distribution::Resource`
01:20
doc/ctest-rm: 5d4da9ae61 | (Will Coleda)++ | Makefile
Remove ctest target

The minimum we should be running is 'test'
doc: coke++ created pull request #4243:
Remove ctest target
cfa heh, i'd forgotten about ctest 01:21
Geth doc/testing-notes: 449d31147a | (Will Coleda)++ | 4 files
Cleanup READMEs.

This will close #3935 but includes other cleanup as well.
01:53
doc: coke++ created pull request #4245:
Cleanup READMEs.
doc/main: ff3ce9d1c9 | cfa++ (committed by Will Coleda) | doc/Type/Distribution/Resource.pod6
Partially revert changes to Distribution::Resource

Reverts two lines changed in 4118f0c: the directory name has yet to be changed from `perl6` to `raku`.
01:54
doc/testing-notes: 4f51d99245 | (Will Coleda)++ | writing-docs/EXAMPLES.md
Note policy on incomplete snippets

Closes #4138
01:58
[Coke] ok, #4245 will clean up two meta tickets. 01:59
cfa: taking your thumbs up as an approved review on #4243. 02:00
Geth doc/main: 10a5a7f236 | (Will Coleda)++ | Makefile
Remove ctest target

The minimum we should be running is 'test'
Geth doc/main: 90cc553237 | (Will Coleda)++ (committed using GitHub Web editor) | 4 files
Cleanup READMEs. (#4245)

  * Cleanup READMEs.
This will close #3935 but includes other cleanup as well.
  * Note policy on incomplete snippets
Closes #4138
02:24
[Coke] Down to 25 open tickets in current milestone. one ticket every 1.12 days. 02:32
Geth ¦ doc: coke assigned to finanalyst Issue pod6 comments "=comment" inaccurate? github.com/Raku/doc/issues/4187 02:56
doc/main: 87747f050c | (Will Coleda)++ | writing-docs/EXAMPLES.md
whitespace
03:25
[Coke] one of my own commits failed xtest! (*shame*) 03:30
Geth doc/main: 6cfe5f1737 | (Elizabeth Mattijsen)++ | doc/Type/Any.pod6
Document Any.snitch
10:45
Geth doc/main: 454e12c47b | (Elizabeth Mattijsen)++ | doc/Language/operators.pod6
Document // as a prefix op
11:36
doc-website/add_licensepage_and_link: 5cafe90418 | finanalyst++ | 2 files
fixes #162

Adds license page to structure, and makes License in the footer a link to the page remove redundant sections from template
12:18
doc-website: finanalyst++ created pull request #194:
fixes #162
12:19
doc/main: d33d82fcaf | (Elizabeth Mattijsen)++ | doc/Type/Str.pod6
Document comb rotor capabilities in 6.e
12:39
lizmat Hmmm.... looks like generic infixes are not quite well findable: docs.raku.org/routine/infix:&l...p;gt;.html 12:51
that only mentions the Date / DateTime / Range versions
Q: given X«|Reference,CALLER (package)» 13:25
should a search for CALLER produce a link to that ?
Geth doc/main: f381a163cc | (Elizabeth Mattijsen)++ | doc/Type/IO/Path.pod6
Document IO::Path.chown
14:33
doc: cfa++ created pull request #4246:
Rename `P6_DOC_TEST_*` environment variables
14:40
Geth doc/main: 62b35eaed0 | cfa++ | xt/pws/code.pws
Add a few code words
14:47
lizmat :-) 14:48
cfa hmm 15:03
those snitch examples currently fail to compile because there's no `use v6.e.PREVIEW` preamble
but the current implementation of :preamble<> places the use statement too late 15:04
(in xt/examples-compilation.rakutest)
lizmat cfa: so what to do ?
cfa oh, one sec 15:05
will send a pr in a few 15:12
lizmat oki
Geth doc/main: b26da22334 | (Elizabeth Mattijsen)++ | doc/Type/Any.pod6
Document Any.snip
15:13
cfa we'll probably need the same change for ^ 15:14
but i can add that in
Geth doc: cfa++ created pull request #4247:
Declare `v6.e.PREVIEW` in the preamble for examples that require 6.e
15:23
cfa lizmat: ^ 15:24
lizmat ok, gotcha
cfa since i merged in main again midway through, that should probably be squashed and merged
but this passes now
except for the use of &dd
lizmat ?
Geth doc/main: 8b014ad99e | cfa++ (committed using GitHub Web editor) | doc/Type/Any.pod6
Declare `v6.e.PREVIEW` in the preamble for examples that require 6.e (#4247)

  * use v6.e.PREVIEW for snitch examples
  * use v6.e.PREVIEW for snip example
15:25
cfa xt/examples-compilation.rakutest .. # Failed test 'doc/Type/Any.pod6 chunk starting with «(my $a = 4» uses dd: try say instead'
there's an explicit check here: github.com/Raku/doc/blob/main/xt/e...kutest#L64 15:26
ah, github.com/Raku/doc/blob/main/writ...d#allow-dd 15:27
Geth doc/main: 9edc4dae12 | cfa++ | doc/Type/Any.pod6
Allow &dd in the snitch test
15:28
cfa [Coke]: as part of the general renaming, i thought we might want to do this for the test suite, github.com/Raku/doc/pull/4246 15:29
lizmat cfa++ 15:33
cfa it might be nice to replace `:solo :preamble<use v6.e.PREVIEW;>` with something like `:use<v6.e.PREVIEW>` 15:34
to make the boilerplate less clunky
lizmat I wouldn't use ":use" as that could imply more general pragma / module thingies 15:37
or is that what you would imply?
like :use<Test> ?
cfa the issue is making sure that the preamble is added in the correct place
github.com/Raku/doc/blob/main/xt/e...kutest#L77 15:38
the :solo examples are more straightforward but if we want the other branch, we can't declare a 6.e requirement 15:39
Geth doc/main: 7fec5ae946 | cfa++ (committed by Will Coleda) | 13 files
Rename P6_DOC_TEST_* environment variables

P6_DOC_TEST_VERBOSE → RAKU_DOC_TEST_VERBOSE, P6_DOC_TEST_FUDGE → RAKU_DOC_TEST_FUDGE.
cfa (straightforwardly)
cfa thanks [Coke]
lizmat: maybe something like :pragma<...> is better 15:41
cfa meanwhile attempts to install the doc toolchain deps in 2023.02 on this machine 15:42
lizmat cfa: fwiw, all tests were passing for me without your patches? 15:49
cfa they failed for me
you ran xtest? 15:50
lizmat "make test" is what I did
cfa yeah example compilation and spellcheck are both in "make xtest"
lizmat so I should run both, or just "make xtest" ?
cfa just make xtest
that'll run tests in t and xt
lizmat oki, will do in the future 15:51
Geth doc/main: b1a75f5369 | (Elizabeth Mattijsen)++ | doc/Type/X/IO/Chown.pod6
Document X::IO::Chown
16:20
cfa lizmat: btw, did the link-checker pick up that X::IO::Chown was missing? 16:25
lizmat yup that's why I added it
cfa 👍
(and thanks!)
lizmat yw 16:26
cfa hmm, is the recommended site for browsing modules modules.raku.org or raku.land/ these days? 16:38
i've been using the latter
lizmat too 16:43
see also: github.com/Raku/problem-solving/pull/331
:-)
Geth doc/main: 4d9e7f320f | (Elizabeth Mattijsen)++ | doc/Type/Any.pod6
Document sub versions of head / tail / skip
16:44
cfa lizmat: ah, thanks
i'm wondering whether we replace modules.raku.org refs in the docs with raku.land
lizmat ah, good point... I think I can take that on... 16:45
cfa thanks
one other thing i saw this morning:
lizmat doc % rak modules.raku.org --edit
:-)
cfa github.com/Raku/doc/issues/3162
do we really want to just point to Str, or should the docs for Supply briefly summarise behaviour? 16:46
lizmat yeah, I saw similar things today... will do that in another round
cfa great
lizmat I think if a method has a different behaviour in a class, we should keep it
cfa yeah
lizmat but there are only a few cases of them
cfa checked off a few things in github.com/Raku/doc/issues/3104 16:59
pseudo-packages, raku and RAKUDO_HOME entries 17:00
but i think it's largely if not completely covered already
lizmat is rakudoc still a thing ? 17:03
cfa the CLI tool? 17:04
lizmat yes, I guess
raku.land/cpan:SOFTMOTH/rakudoc more specifically
cfa it's github.com/Raku/rakudoc now 17:05
lizmat ok, raku.land doesn't seem to know about that
cfa [Coke] added a maint fix recently but no real development in at least a couple of years, i think
also fwiw, just used rak ... --edit here 17:06
Geth doc/main: 86748c5f66 | cfa++ | doc/Type/independent-routines.pod6
Fix `repl` note
17:14
cfa (fixes docs.raku.org/type/independent-rou..._compiler. ) 17:15
hmm 17:36
docs.raku.org/type/Distribution/Resource.html
%*RESOURCES doesn't exist (it's $*RESOURCES) but that's also undocumented
lizmat I guess we will find more of these :-) 17:37
cfa yeah
i'm not sure what to update this to
oh, the link is supposed to be to %?RESOURCES anyway
lizmat yeah, but that will not exist
so the link is wrong to begin with ? 17:38
cfa %?RESOURCES is documented at docs.raku.org/language/variables.h...FRESOURCES
$*RESOURCES isn't documented
there's a link to %?RESOURCES but that's broken anyway (and the text references %*RESOURCES which doesn't exist at all)
lizmat then /me is confused
cfa i'll create an issue 17:39
Geth doc/main: 0eac1937bf | (Elizabeth Mattijsen)++ | 17 files
Change all modules.raku.org refs to raku.land

And remove some outdated references
17:40
lizmat phew: 124 references updated, xtest says it's all ok
cfa great stuff 17:42
github.com/Raku/doc/issues/4248 re: the above btw
Geth doc/main: b358333e4b | (Elizabeth Mattijsen)++ | doc/Type/independent-routines.pod6
Be explicit about exitcode only being set once

In response to github.com/Raku/doc/issues/4097
17:46
doc/main: 098536fbd7 | (Elizabeth Mattijsen)++ | doc/Type/Iterable.pod6
Mention that undefined values can be used for :batch|degree
17:57
[Coke] (note that 'make xtest' is very slow and you only need to run it for modified files - can set TEST_FILES or if you haven't committed yet, util/test-modified.sh 18:01
[Coke] sees a ton of work since yesterday, wow! 18:02
Geth doc/main: 8ff4c0089c | (Elizabeth Mattijsen)++ | doc/Type/Str.pod6
Add some release info for Str.Version|Date|DateTime
18:05
[Coke] I often do "util/update-and-test" also, which pulls everything new and tests it.
Geth doc/main: d8f6e7b85e | (Will Coleda)++ | doc/Language/modules.pod6
fix typo
18:07
[Coke] (which is how I found that) 18:08
cfa 👍
lizmat [Coke]++
Geth ¦ doc: coke self-unassigned Explanation on thread issues with hashes github.com/Raku/doc/issues/4143 18:11
¦ doc: coke self-unassigned Documentation of Supply.split|comb github.com/Raku/doc/issues/3162
[Coke] I unassigned a bunch of stuff that was set to me for current milestone - was just leftover "oh I should deal with this" which is now what the milestone is for, so please feel free to keep taking tickets. :) 18:12
Geth doc/main: 02e6da7090 | (Elizabeth Mattijsen)++ | 2 files
Document that DateTime.new("YYYY-MM-DD") also works

and consequently, "YYYY-MM-DD".DateTime does as well
[Coke] left the "rename all the files" one, which I will do this weekend, probably late night Eastern tonight to be less likely to interfere with any PRs or WIP
Geth doc/main: 6135bd242c | (Elizabeth Mattijsen)++ | doc/Type/List.pod6
Mention sort() being a runtime error
18:14
[Coke] "as s of" 18:15
... and that's an error?? 18:16
cfa yeah i'm unclear what this means 18:18
is this re: the sub? 18:19
[Coke] I mean, I just did a .sort on that with no arg, and it did not error.
cfa `sort;` ==> "Must specify something to sort"
[Coke] Ah. since that chunk is for both sub & method, worth noting the error is sub only. (which does error, just checked)
cfa, can you fix the typo and add the sub caveat? 18:20
cfa sure
are we using # ERROR: as a convention for stderr? 18:22
[Coke] looks like 18:25
lizmat cfa++ [Coke]++
afk&
[Coke] inconsistently.
Geth doc: cfa++ created pull request #4249:
Clarify runtime error for the `sort` sub and fix a typo.
18:27
cfa [Coke]: ^
Geth doc/main: bbfb1b158a | cfa++ (committed by Will Coleda) | doc/Type/List.pod6
Clarify runtime error for sort sub; fix typo.
18:28
cfa these doc updates from Geth are probably quite spammy in #raku 18:30
[Coke]: also, wow, util/update-and-test is really handy
especially on this slower machine
(auto-setting TEST_FILES is v. useful) 18:31
[Coke] glad to hear it. back in the day when no one ran the tests it was super helpful 18:35
cfa :) 18:50
Geth doc-website/main: 4dea3795cf | finanalyst++ (committed by Will Coleda) | 2 files
fixes #162

Adds license page to structure, and makes License in the footer a link to the page remove redundant sections from template
18:52
cfa [Coke]: github.com/Raku/doc/blob/main/doc/...#L838-L839 18:53
might be worth adding a 'trailing whitespace inside C<>s' test 18:54
[Coke] sure, give me 10m
cfa (you can see the spacing issue on docs-dev.raku.org/type/List.html#routine_sort )
this one wraps so it's a little less trivial to pick up with a grep/ack/ag/rak 18:55
$ ag 'C<.*? >' 18:56
many false positives but a few good candidates too
again, linewise only 18:57
gist.github.com/cfa/1df0bb7df249b8...6a0b622080
Geth doc/main: f7725e1813 | (Will Coleda)++ | xt/rakudoc-c.rakutest
C<> should not have leading or trailing whitespace
19:04
[Coke] tons of failures. 19:05
lizmat oh dear
[Coke] eh. always happens with a new test. Figured I'd let cfa take first try. 19:06
[Coke] wonders if C<infix:<cmp> > is smart enough to work with C<infix:<cmp>> 19:07
lizmat [Coke]: would be nice if it could give a line number
[Coke] I'm walking the pod object, do we havel ine numbers at that point? 19:08
lizmat not sure
looks like a lot of cases of C< foo> as well 19:11
cfa i guess we should double check there're no cases of foo C<bar >baz too 19:12
lizmat interesting case: C<< <=> >>
cfa hmm
does that render correctly? 19:15
looks like trailing space added but leading isn't
docs-dev.raku.org/language/5to6-pe..._operators
that's surprising in itself 19:16
and i suppose we can replace C<< <=> >> with C«<=>» and retain readability while fixing spacing 19:20
the latter is actually more readable, i think?
[Coke] C<String>s is fine. 19:25
C<St>s is fine, I mean.
... i give up. :)
cfa entries like this are hard to read too 19:26
C<-> $line { ... } > 19:27
again C«-> $line { ... }» probably preferable?
C<+< > etc.
so part of this is whitespace, part of it is readability/maintainability 19:28
(stil eyeballing some of these results; don't have much time to actual make edits at the moment)
lizmat :q! 19:32
oops :-)_
Geth doc/main: 8af1e830c5 | (Elizabeth Mattijsen)++ | 2 files
Fix some C< trailing space > issues
19:33
lizmat I'm too tired to do more without making big mistakes
cfa thanks lizmat! 19:38
Geth doc/main: bd4e2da23f | (Elizabeth Mattijsen)++ | doc/Type/IO/Path.pod6
Document IO::Path.inode|dev|devtype
19:46
doc/main: de6bd7627b | cfa++ (committed using GitHub Web editor) | xt/pws/code.pws
Add a couple more code words
19:50
doc/main: 400ee360ae | cfa++ (committed using GitHub Web editor) | xt/pws/words.pws
Update words.pws
19:52
cfa the downside of using the web editor 19:53
and now &
Geth doc/main: 7745bec943 | cfa++ | xt/pws/code.pws
Revert changes to code.pws
19:55
[Coke] anyone in the middle of something? I can do the pod6 -> rakudoc rename if i'm clear. 21:59
[Coke] almost done. 22:22
cfa 👍 22:26
[Coke] WOOF 22:34
Geth doc/main: 4 commits pushed by (Will Coleda)++
[Coke] let's definitely make sure that works on docs-dev before next prod push 22:35
cfa great 22:37
cfa rebuilds locally 22:38
[Coke] next test run will be slow as it's rebuilding all the pod-cache. 22:39
but I did finally delete the test to make sure there were no pod5 files.
cfa i'll try and get to the C<> changes later today 22:46
glad we weren't working in parallel
makes for less of a headache
anyway, afk again for a few hours 22:51
coleman Counted some 404s envs.sh/5V 22:53
The full logs have PII like people's IP addresses, but I'm going to document my scripts for fetching this 22:55
[Coke] lets get that in front of richard.
coleman will do
I'll upload this file to the ticket 22:56
[Coke] coleman++
coleman the ones prefixed "/syntax/*" seem like they should be legit
[Coke] /language/nativetype looks like it might be missing some newlines? 22:57
(there's a very long linr)
we can add simple rules to support things like $COLON 22:58
6 -> /language/regexes.html.html 22:59
ok, that's not our fault. :)
cfa i think there's already a ticket re: /syntax links not working 23:00
[Coke] yup, anything with syntax and routine can go there. 23:01
cfa github.com/Raku/doc-website/issues/181
oh coleman's on top of that issue already
coleman github.com/Raku/doc-website/issues...1454914971 23:02
cfa coleman++
back later
&
coleman Yeah, I added a relationship between the two issues
[Coke] afk a bit 23:04