🦋 Welcome to the IRC channel of the core developers of the Raku Programming Language (raku.org #rakulang). This channel is logged for the purpose of history keeping about its development | evalbot usage: 'm: say 3;' or /msg camelia m: ... | Logs available at irclogs.raku.org/raku-dev/live.html | For MoarVM see #moarvm
Set by lizmat on 8 June 2022.
08:43 sena_kun joined 09:36 sena_kun left 14:08 kjp left 14:11 finanalyst joined
finanalyst [Coke] is there any other issue that you're waiting for my feedback on? 14:12
[Coke] The number of link errors is much reduced. I notice that there seem to be alot where C<> markup is used inside X<>. Should these be removed at Build or should they be removed in the sources? 14:18
lizmat I guess X<C< should be changed to C<X< in the source 14:20
finanalyst I think that would fix things, and be an easier fix 14:21
lizmat hmmmm what to do with: 14:24
X<C<\n> and C<\N>|Regexes,\n;Regexes,\N>
also, do we want to keep C< in =headN ? 14:27
[Coke] I think it's fine to have a C< in a head. 14:28
lizmat and what about: X<C<package>, C<module>, C<class>, C<role>, and L<C<Grammar>|/type/Grammar> declaration|Syntax,unit;Syntax,module;Syntax,package> 14:29
[Coke] =head1 the C<leg> operator
that L<> shouldn't be in the X<>
That was probably me being over-eager.
(it was probably a C<Grammar> that got tagged in the report.) 14:30
lizmat It was more about the multiple C<>'s inside the X<>
[Coke] Yes, even those seem wrong 14:31
lizmat simple case: 14:32
X<C<is rw> trait|Tutorial,is rw>
[Coke] You're referencing text, not formatted text, IMO.
lizmat I'm taking examples from the doc sources :-) 14:33
[Coke] What does the new spec say about that sort of thing?
lizmat finanalyst might know offhand
[Coke] I'm happy to force raku/doc to conform to the new standard.
finanalyst the new standard allows both C<X<> > and X<C< > >. The problem is how the anchor names are created, and then referenced by other authors 14:37
lizmat I guess the any formatting would need to be flattened inside a X<> when creating anchor names 14:38
*that
finanalyst So there should be no problem when the renderer finds a X<C<is rw> trait| one;two> and puts an anchor to that location in the text
But then what happens when an author is linking to 'is rw trait'? 14:39
[Coke] ok. I think it makes sense for us to prohibit L<>'s in the X<> though 14:40
From an author standpoint, we just need to know what the standard is so we can follow it.
I think lizmat's suggestion to flatten it makes sense. 14:41
finanalyst Correctly it should be 'index-entry_<code>is_rw<code>_trait' or something like that
[Coke] so the anchor would be #is_rw_trait or something, with no reference to the C<>
index-entry_is_rw_trait would be much better.
finanalyst An editorial standard would be best, then the renderer should follow the standard
[Coke] The only place I'd expect the formatting to show up is in search entry formatting (but not needed to find with search key text) 14:42
If I got to pick, I'd want "is_rw_trait', with no mention of index-entry
finanalyst I agree, for search only is_rw_trait, but if linking to an indexed item, we should have L< blah | index-entry_is_rw_trait> 14:45
otherwise L< blah | #is_rw_trait > (missed # above) would be a heading 14:47
the new standard does not dictate anything about anchor ids, whether there should be spaces or _. 14:48
We did discuss this, but the problem is that there are too many variations between output formats 14:49
at the beginning, HTML did not like spaces in anchors, so all spaces were converted to _, and special chars were converted to escaped or $SOLIDUS type forms 14:50
[Coke] ... ok, the link can be to that, but can it render in HTML without the "index_entry" ? 14:54
sl L< blah | #index-entry_is_rw_trait> (btw, don't like mixed - and _), but as <a href="#is_rw_trait">blah</a> ? 14:55
from an HTML standpoint, anchors are already mixed between various types of elements, so I'm having trouble adjusting my mental model to caring in the rakudoc. 14:58
related topic: there was an ask years ago for authors to be able to do something like A<arbitrary> and then be able to link to #arbitrary (to avoid this very issue) 15:02
15:12 kjp joined
finanalyst [Coke] please bear in mind that I very much dislike the anchor naming scheme, and I would choose another if I could, but it is a legacy that I have had to work with 15:57
the - _ mix is because index-entry has to be distinguished from a heading, and the _ are to replace ' ' 15:58
[Coke] who is using the legacy method aside from us? 15:59
finanalyst no one
Alex was arguing a long time ago that there should be a unified anchor naming system. 16:00
[Coke] So I'm not sure we need to continue to support it - certainly we can break with it in the new version.
but we can work on just getting things working with this standard separately from considering changes to the standard.
finanalyst problem is that there are a lot of links to the old anchors from outside our site
[Coke] I know that was something JJ was very concerned about, but I am less concerned. It's an ideal we should aspire to, but isn't a blocker we must strictly adhere to, IMO 16:02
finanalyst regarding HTML anchors as in the <a href=" " > where the href is the anchor, we still need to distinguish between indexed locations and headings
[Coke] Biggest change I'd like to see right now is getting rid of the formatting codes in the anchor name
finanalyst: why? 16:03
a link to a header is no different than a link to an arbitrary dom id
finanalyst OK suppose you have `=head1 is rw trait` and X<is rw trait>. They are in different places. How do refer to them both? 16:04
[Coke] "assume a single namespace and don't do that."
which seems reasonable to me - shouldn't have multiple instances of the same anchor in the same document. 16:05
that could be a compile time warning on the doc. (and I'd probably make it an error on the raku/doc tests)
rephrasing: make it an author problem instead of a tooling problem. 16:06
finanalyst That really puts more strain on the author
The assumption so far is that it is the renderers problem 16:07
[Coke] I think that use case is a DIHWIDT.
... but that's a long term change we can consider. for now, can we get rid of <code> in the anchors? (e.g. use only the rendered flat text for any formatting codes in an X<>) 16:08
so then X<L<C<Grammar>|/type/Grammar>> would be index-entry_Grammar?
If we are concerned about legacy links, the renderer could include an anchor point in the rendered HTML that had it the old way that our current tooling would ignore, but if someone came in with an old link it would work - I think this is a possible approach (but not needed IMO) 16:10
finanalyst So when we have `=head1 class A ... =head2 The Foo method` and `=head1 Class B =head2 The Foo method` in the same document, the renderer generates unique anchors for both headers. The authorial dilemma is then to link correctly using `L<>`
[Coke] We can write up a section on whatever the write way to do that is, sure. Worst case, we run the report and see it's broken and fix it (better case, we run a test in raku/doc pre-commit and catch it then) 16:11
finanalyst I'll get rid of <code> and other formating in links as soon as possibe.
The question of anchor naming is a lot more complex than it first seems 16:12
[Coke] Sure. We could probably use a brief overview in raku/doc/writing-docs as an explainer to authors. 16:13
... "the right way", I mean. pun was not intended.
finanalyst For example, when `=head X<Some header| Syntax; something>` and `X<Some header>` are created, they are treated completely differently 16:14
When the documentation was first rendered, the anchors were created in different places, and it took weeks for me to work out why they were different 16:15
If you look at the recommendations for indexing, some of them do not make much sense. 16:18
One of the problems IMO is that the X<> markup was not used to create indexes, but to insert anchors into the text that could be used for contents 16:19
I have tried to include a rendered index (the right hand part in the left-hand column), so that now authors can see what X<> markup actually does 16:21
FYI the A<> markup was specified by Damian for RakuDoc v1, but it was never implemented. It will be available in the new renderer. 16:22
Would it be possible to create an issue / discussion about what the linking standards should be 16:23
[Coke] oh, cool, I'll mention that in the raku/doc ticket
that should be a PS ticket, I think, not a raku/doc ticket.
finanalyst 'PS ticket' ?? 16:24
[Coke] problem-solving repo
finanalyst Problem solvers?
[Coke] +1
raku/doc has opinions, I think, but we shouldn't be the decider.
(and I do mean opinions plural. :) 16:25
finanalyst Frankly I think that it should be the Raku/doc authors who have the primary input
RakuDoc is neutral about links, so it is a question of style
and that would make Raku/doc authors the decision makers 16:26
[Coke] OK. Then I'd start with a discussion on raku/doc and if we get something actionable, make it a ticket.
(not excited about how discussions have worked out, lots of steam and no resolution, it seems)
(but still better than putting that in a ticket) 16:27
github.com/Raku/doc/issues/2535
finanalyst As far as I am concerned, I would love to have a consistent system
[Coke] (not for your issue, just an old ticket)
github.com/Raku/doc/issues/111 was the A<> related one 16:28
closed it 16:29
finanalyst [Coke] I have just been analysing the first error on the report, namely `<code>callsame<code>` 16:43
In the source that contains the L<> markup, '5-6-nutshell', the link is `L<C<callsame>|/language/functions#index-entry-dispatch_callsame>` 16:45
the L<C<callsame>| is not relevant because thats just the display text 16:46
the link is to #index-entry_dispatch_callsame
In language/functions, we have `=head2 X<sub callsame|Subroutines,callsame>` 16:47
But I can for the life of me figure out why there should be 'dispatch_` in the link. 16:50
the correct link should be simply '#sub_callsame', without any 'index-entry' 16:53
If there was a consistency about these errors, such as formatting, then I could fix it, but I cant see a pattern 16:56
Is it possible that at one point, the heading had the word dispatch in it, and then was changed? 16:57
17:02 finanalyst left
[Coke] ... where are you getting the errors from? 17:05
I thought you were generating those, so I'm surprised at your surprise. :)
Yes, it's quite possible someone renamed something and never changed the links. 17:06
Once we get the report clean, we can catch those things closer to as they happen. 17:09
but there's no expectation that this maintenance has been happening as we go
17:22 sena_kun joined 19:48 finanalyst joined 19:53 ugexe left, ugexe joined
finanalyst [Coke] I'm just fixing some bad links. Do you want to review the changes, or shall I just commit to the repo? The changes are obvious. 20:08
[Coke] I asked you to review them so far. 20:09
[Coke] I can work on a few files each day. 20:11
[Coke] for raku/doc? If you're just fixing links, those don't need review. 21:47
I'll get those 4 merged shortly. Thanks! 21:48
23:19 finanalyst left 23:28 sena_kun left

Powered by Cro and the Raku® Programming Language.

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

Thank you!