Documentation Channel for #raku | This channel is logged | Roadmap: github.com/raku/doc/wiki
Set by [Coke] on 23 May 2022.
Geth doc/main: a4b1c308b8 | cfa++ | doc/Type/independent-routines.rakudoc
Fix link markup.

Closes #4254.		 00:04
doc/main: 50f82d30a8 | cfa++ | doc/Language/regexes.rakudoc
Remove formatting codes from regexes table

These are currently unsupported (and therefore incorrectly rendered).
A grep of the doc tree suggests that no other `=table`s are currently using formatting codes.
Related issue: github.com/Raku/doc-website/issues/195.		 01:37
cfa [Coke]: candidate for a test 👆 01:52
[Coke] Not sure if we can easily check, maybe look at the raw table source for C<>'s ? 02:02
OMG, I just spent an hour trying to figure out why this wasn't working, I had a "next" inside a subroutine instead of a routine, and it was apparently next'ing through the for loop in the caller. 02:03
instead of a return, I mean.
Geth doc/type-links: 99f060a811 | (Will Coleda)++ | xt/rakudoc-types.rakutest
Add test for Type link formatting.

Accepted formatting is, e.g.:
L<C<Int>|/type/Int>		 02:12
[Coke] Will no doubt be some false positives there. 02:15
cfa neat
and yeah, i think a type page for Foo will often have an opening paragraph mentioning bare C<Foo> 02:16
i guess those could self link
[Coke] That'd be fine, or we could check if we're on that page.
cfa yeah, might be nicer 02:17
[Coke] thinks like C<Raku> will be problematic, maybe.
currently 4060 failures.
cfa here's an issue
i think you'll want to convert the candidate type Foo::Bar to Foo/Bar before doing the path check 02:18
btw, is there a documented trap for that `next` case you ran into?
[Coke] that brings it to 4598 failures. :) 02:19
Geth doc/type-links: f1e00509db | (Will Coleda)++ | xt/rakudoc-types.rakutest
Find Foo::Bar types.
 02:20
[Coke] Nope. I'll open a ticket.
cfa 4598 -- oof 02:21
(that seems very high) 02:22
[Coke] added github.com/Raku/doc/issues/4255
cfa, There's never been a consistent effort to clean this up 02:23
cfa sure
[Coke] so it's basically "nearly every time we reference a type"
cfa i guess i'm just surprised that there're 4.5k bare type mentions in the docs
[Coke] Note that this doesn't do anything about when it just appears as is inside a paragraph.
Could also be the test isn't right. :) 02:24
Geth doc/type-links: bd4d0c3c47 | (Will Coleda)++ | xt/rakudoc-types.rakutest
Remove stale comment
 02:30
doc: coke++ created pull request #4256:
Type links		 02:31
[Coke] Made it a draft, we can kick the tires for a bit (and maybe work on fixing some failures first.) 02:32
cfa, please feel free to commit to that branch.
nemokosch pointed out that the prod site's edit buttons are currently broken due to the big file rename. 02:35
I'll do a prod push tomorrow afternoon if we're in a good spot on docs-dev
cfa whoops 02:42
sg re: update 02:43
spot checking a few of these test results -- no problems so far 02:47
(with the test, that is)
02:48 rf left
cfa i'm seeing a lot of `bad parent class: Pod::Block::Para`s though 02:49
gist.github.com/cfa/742305aaaed549...dd08c4b6fa 02:52
`# Failed test` lines with counts 02:53
gist.github.com/cfa/6ad2ce9c34f706...7fa7c236d1 with s/- bad parent.*$// 02:54
top 13 account for over a thousand of the failures 02:57
03:07 rf joined 03:14 rf left 03:43 cfa left
[Coke] need to allow #tags 03:55
Geth doc/type-links: a8963e1d62 | (Will Coleda)++ | 2 files
clean up test descriptions
 04:53
doc/type-links: aa83d5088d | (Will Coleda)++ | xt/rakudoc-types.rakutest
Support #tags on link urls
doc/type-links: 6eac901a4f | (Will Coleda)++ | xt/rakudoc-types.rakutest
remove debug output
 12:28
13:10 rf joined
[Coke] What's our desired link style for Foo::Bar types? /type/Foo/Bar or /type/Foo::Bar? website supports both, path separator is more natural for source, :: is more natural for users, probably. 14:53
we can use this test on type-links branch to push towards either. 14:54
16:01 cfa joined
lizmat if you ask me: I'd prefer /type/Foo::Bar 16:14
[Coke] ok, two votes for ::, one for /
(based on #raku convo) 16:15
lizmat yeah, just saw that
[Coke] I dipped my toes in, now I'm done. :)
cfa +1 to Foo::Bar
[Coke]: i'm just testing automated replacement of C<Str> and L<Str> here: 16:27
one other point to bear in mind -- we often have stuff like 'the C<Str> method'
which we don't want to link to the type page
(rather that should be a #method_Str link)
Geth doc/type-links: 96dbf7cd6f | (Will Coleda)++ | xt/rakudoc-types.rakutest
Prefer colons in link URLs.
 16:35
[Coke] Sure, we can make these smarter. Might end up having to declare what *those* links should look like as well. 16:36
like, it should probably be L<C<Str> method|/type/Int#method_Str>, etc.
if we put the method inside the link text, we avoid the false positive on this test. 16:37
maybe we can then write a test for the *method* links.
ok with cfa & lizmat, we're at 3 to 1, I pushed a version that prefers the ::'s
lizmat [Coke]++ 16:38
[Coke] before merging this, I am going to squash some commits here. Maybe we have one commit to add the script, and one for any updates to docs to pass tests.
Wonder what else is in the backlog that we could be writing xts for.
Geth doc/missing-c: 90102adbf0 | (Will Coleda)++ | xt/rakudoc-brackets.rakutest
Add test for <> (missing formatcode)
 16:57
doc: coke++ created pull request #4257:
Add test for <> (missing formatcode)		 16:58
[Coke] that one.
cfa 👍 16:59
[Coke] only 41 instances of that one, and half are things like <*> that should probabyl be C<< <*> >> 17:04
cfa i've yet to render these changes but please take a look at github.com/cfa/doc/commit/4be822 for a first (automated) pass 17:07
[Coke] nice! 17:11
cfa added Seq updates too, github.com/Raku/doc/compare/main.....type-links 17:13
oh whoops 17:14
lizmat Q: has the doc site recently been updated ? 17:15
I don't see the entry for "nano" yet 17:16
wondering whether that is to be expected or not
cfa [Coke]: Str, Seq and Nil expansions are in that branch 17:17
testing rendering now to eyeball some of these; please re-run your latest test if you get a chance to see what the impact is 17:18
(i picked the top 3 types from the count i made yesterday)
lizmat: i don't think so
lizmat ok, check :-) 17:19
cfa docs-dev.raku.org/language/terms.html#term_nano
it's here
but i think the main docs site is outdated by a few days
lizmat ok, good to know :-)
[Coke] type test is buggy on case insensitive FS. 17:20
if docs-devlooks ok, will push now 17:21
cfa was the edit (site) bug fixed?
Geth doc/type-links: 3a8c16c082 | (Will Coleda)++ | xt/rakudoc-types.rakutest
Types should be C<> on their own page.
[Coke] will be with the push 17:22
cfa great
btw, that expand-type-links is very much a draft / test
... expand-type-links branch* is ...
[Coke] pushed 17:23
cfa++
cfa lizmat: docs.raku.org/language/terms.html#term_nano
[Coke]++ 17:24
[Coke] cfa, added the change so type ref on that type's page expects only C<>
cfa thanks
the substitution/expansion isn't intelligent so these changes will violate that i'm sure
lizmat cfa: oddly enough, the search on that URL doesn't know about "nano" yet? 17:25
cfa not sure how the search index is generated 17:26
[Coke, any ideas?
[Coke]*
[Coke] I see it 17:27
cfa it's not autocompleting for me 17:28
[Coke] refresh try again? it's statically generated, so if you had doc site open when I pushed it wouldn't be there.
this may also be related to the "are we overeagerly caching" issue.
cfa i think my browser has cached the index
works in an incognito window
[Coke] can you open a ticket on website going through the steps? 17:30
I think we need a cache buster when deploying.
cfa github.com/Raku/doc-website/issues/207 17:34
hopefully that's clear
[Coke]: glancing at the Str page, built from the expand-type-links branch, i'm not sure self-links are actually that problematic 17:36
perhaps they incorrectly suggest a link to a different page though
anyway, PTAL 17:39
(back in a bit) 17:40
[Coke] I'm fine with self-links being actual links; only a slight preference for no 17:45
cfa knocked them out of that branch 18:01
[Coke] ok 18:05
cfa pushed expansions of Pair and List 18:14
that should be enough for testing
Geth doc/main: cae02e1565 | cfa++ | doc/Language/regexes.rakudoc
Fix table header
 18:28
cfa hmm 18:40
.control spans now have a different (larger) font size in code examples
this seems to be a recent change (unless i just didn't notice it before) 18:41
it's not 18:48
[Coke] Please report any weirdness you find, thanks. 18:57
cfa yeah i've been trying a fix
i've checked in two browsers: can you confirm that for/when/default/... are sized differently there? docs.raku.org/language/control.html#for 19:00
[Coke] 14px vs. 16px 19:02
cfa thanks
Geth doc-website: cfa++ created pull request #208:
Use consistent font size for highlighted control keywords		 19:05
cfa there 19:06
[Coke] nice. 19:08
cfa and now &
19:37 cfa_ joined, cfa left 19:38 cfa_ left
Geth doc/missing-c: 5028c1227e | (Will Coleda)++ | xt/rakudoc-brackets.rakutest
Skip comments

Comments can have text like C<push> that looks correct, but since it's all just text, this would otherwise trigger a test failure.		 21:22
doc/missing-c: 454e06dfeb | (Will Coleda)++ | 17 files
Fixup some missing C<> in pod.
[Coke] ww. 21:25
infix:<cmp> triggers the missing C< complaint. I think I will whitelist infix:< and prefix:<
Geth doc/missing-c: 96857487a2 | (Will Coleda)++ | xt/rakudoc-brackets.rakutest
whitelist infix:<> prefix:<>
 21:37
doc/missing-c: 40d34ca852 | (Will Coleda)++ | 2 files
Fixup some missing C<> in pod.

Powered by Cro and the Raku® Programming Language.

Please report any issues / comments / feature requests as an issue on App::Raku::Log.

Thank you!