Raku
//= Not easy to find in docs
The problem
Using the search on docs.perl6.org, I couldn't find documentation for the //= operator.
Suggestions
I'm not sure if it is documented somewhere, but if not it would be good to document it. If it is documented somewhere, it would be good for it to be findable.
I think it is a general problem for every case of <op>'=' application-assignment...
It is described in general at https://docs.perl6.org/language/operators#Assignment_operators
and I wonder if we can detect this form and point it to this section, with static search it is not so possible.
Adding And you can use it with assignment operator, see $section-link near every described operator somehow seems like a bad way to me, not sure why though.
That's the thing. It's asummed that every infix operator can get = appended for that effect. //= does not have any kind of special behavior, if you compare it with += or ~=. If you think it merits special treatment, please clarify. Also maybe we should automatically create indices for this kind of operators (more than special content), but that would need some work...
The relevant description of assignment is here.
Now, I don't know how to give people who don't already know what they are looking for, a hint that this phenomenon exists in the first place. Maybe a short segment that can be generated to each and every infix operator could help; something that redirects to a page where the commonalities of these operators (I'm mostly thinking of the available metaoperators) are listed.
Actually, this could be done for any operator.
Maybe a short segment that can be generated to each and every infix operator could help
Let's make the search bar smarter rather than pollute the text with copypasta (Raku has tons of ops to document and, more so, read about).
"let's make the search bar smarter" sounds nice in theory but there are multiple reasons why it doesn't seem realistic at all. For starters, it's in a barely functional state for several months by now, and it doesn't seem like anyone will pick up on it all of a sudden. Furthermore, the search was quite heavy on the client side so there was the idea to delegate it as a service as much as possible - now, that also received pushback immediately because it complicates deployment by a margin. And then we still haven't thought about what "smarter" would actually mean.
Besides the search being in a terrible state, the problem is that no matter how much content exists out there somewhere, one simply doesn't know what they don't know. This goes beyond //=. The valueable piece of information here is that you can combine basically any operator with given metaoperators. The discoverability of this fact cannot even be compared with the discoverability of operator references, and to make it worse, = is not listed among the metaoperators; there isn't even a consistent terminology carrying on ("combine operators with assignment", "compound assignment", "assignment metaoperator" being used at different places).
Considering this, it doesn't seem like a lot of copypasta (if it's copypasta at all) to literally generate a part that reminds you of commonalities shared by all operators, like, literally a sentence with a link. People don't usually "binge read" operator references. Also, this is essentially what we have been doing all along by generating complete inheritance chains into references of classes.
For starters, it's in a barely functional state for several months by now
Can you please elaborate?
so there was the idea to delegate it as a service as much as possible - now, that also received pushback immediately because it complicates deployment by a margin
Well, at some point we had an option to go towards dynamic engine with https://github.com/Altai-man/docs.raku.org/ but historically we chose to go for static website using Collection on the premise the functionality won't be compromised.
And then we still haven't thought about what "smarter" would actually mean
The search code can have a table of operators and detect the input like //=, redirecting it to e.g. a single place where the principle is explained.
here isn't even a consistent terminology carrying on ("combine operators with assignment", "compound assignment", "assignment metaoperator" being used at different places).
This is true! A part of the effort would be to work on a place that makes it solid rather than sprinkling all the ops descriptions with auto-generated text.
Can you please elaborate?
Honestly, let the issues speak instead of me: https://github.com/Raku/doc-website/issues?q=is%3Aissue+is%3Aopen+label%3Asearch . Really, even the pace of your keystrokes influences the results, but the order and the outlook are also problematic.
Well, at some point we had an option to go towards dynamic engine with https://github.com/Altai-man/docs.raku.org/ but historically we chose to go for static website using Collection on the premise the functionality won't be compromised.
I know this right and I can't even imagine the permanent pushback that it would have involved, about the caching, load balancing, setting up the web server, the container and all.
Having said that, it is possible to do what the old site did (fetch all the data all the time and let the client process and render it); one can see how well that works with the list of subroutines when executed as naive single-threaded Javascript blocking the DOM updates.
The search code can have a table of operators and detect the input like
//=, redirecting it to e.g. a single place where the principle is explained.
Again, this is a decent solution if we strictly focus on this old issue. It came up at yesterday's Raku Study meetup and I found this ticket; I didn't want to open a brand new one because I thought it would be more practical to just "widen" this one.
My premise is that if you know the concept of op= being a productive formation, you don't actually need to look //= up literally. You can just use your knowledge of // and your "imagination". (This is why "advertising" op= would be so very useful.)
At the same time, if you don't know about the op= pattern, why would you type this pattern out of the blue with random operators? My concern is that it would need to show up as a "recommendation", somewhere up in the list. Now I think the question legitimately arises whether we also want to put other meta-stuff there, X//, Z//, [//] or something, and if the answer is yes, we basically created a bigger and more apparent bloat than if we just generated a couple of sentences into the individual operator references.
If only the op= pattern were included in the search, I think eventually someone else would also start wondering, why only that. I can't say it for sure but it makes me feel itchy for sure.
And anyway, would it be "special-cased" so that only reasonably useful combos get added? That doesn't seem feasible but I can see why someone would feel over- and underwhelmed at the same time when being shoved andthen= (apparently even that works), minmax=, (cont)=, &= and the likes, right in the face.
A part of the effort would be to work on a place that makes it solid rather than sprinkling all the ops descriptions with auto-generated text.
I think this is a false dilemma all along.
The documentation tries to do more things at once basically, and the huge monolithic operators page is really the worst of it. The language/ path is mostly reserved to the exploratory, explanatory tutorial/howto part, something that people read to get to know more about the language in general, with no particular goal. The type/ path is mostly a reference guide, with a thin layer of explanation to it.
As things stand currently, neither group of people would be pleased with the operators page; it's way too large in the first place and besides, it starts off as a tutorial, then it still contains a massive table (which isn't exhaustive nevertheless so it's really just an oversized table in a tutorial), then it basically intermixes tutorial-ish topics (concept of identity, metaoperators, assignments) with an exhaustive(-ish) reference guide containing all operators grouped by precedence.
The "place that makes it solid" would be a reworked version of the tutorial-ish parts. Its primary audience is the people who want to know more about the language.
The "sprinkling all the ops descriptions with auto-generated text" would belong to the extracted version of the reference-ish parts, parts that should make sense on their own if you searched for one operator. As I said, nobody "binge reads" operator references, and that sort of content usually wouldn't even appear on one site.
So, why do I think that reference readers need to be directed to the tutorial-ish part, if only by a 1-2 sentence disclaimer and a link? Well, because people don't know what they don't know. Even the people who aren't interested in reading an elaborate description of the broader language might want to know about synthetic operators. It would be much more painful (and less expressive, even) to actually generate a reference for all those operators that often don't even exist as individual operators in Rakudo.
In short, my whole point is that the bigger problem of users is not that they cannot recite an operator like //= but that they don't get to know about it, and when they first see it/hear about it, they desperately start to look for it in the docs, and cannot find it. I think we should read between the lines here. It's "how do I get to know this", not literally "where do I find this".
At the same time, if you don't know about the op= pattern, why would you type this pattern out of the blue with random operators?
I assume people can try to look it up while reading sources of others. //= is pretty intuitive too, but as you mentioned, it goes deeper than just =, so we should address the whole "pattern" here.
Now I think the question legitimately arises whether we also want to put other meta-stuff there, X//, Z//, [//]
My idea was to parse the input and decide if we need to do the "special case", not to include all the possible meta combinations in the search list (that would be really bad).
I can see why someone would feel over- and underwhelmed at the same time when being shoved andthen= (apparently even that works), minmax=, (cont)=, &= and the likes, right in the face.
You are right! We should not suggest them, but should provide something for the user who inputs them.
The "place that makes it solid" would be a reworked version of the tutorial-ish parts. Its primary audience is the people who want to know more about the language.
True.
It's "how do I get to know this", not literally "where do I find this".
You are right, maybe we are thinking about different cases.
I am more concerned of a situation like this:
- The user sees some synthetic op in code
- Tries to look it up in our search
- No sensible results (?)
It would be resolved by making the input bar to "understand" the synthetic nature of the input and providing a way to see some explanation somewhere.
But maybe it makes sense and it's easier to, instead of trying to do the parsing part, just let the user jump to = part (or // part) and see the explanation on their individual sections.
A completely different angle to approach this:
Have a syntax highlighter or some dedicated tool, that can deparse Raku and provide insight into how a piece of code is built up. Then one can know which operator a synthetic is made up of. Similar to what regex101.com is for regexes.
You are right, maybe we are thinking about different cases.
Yes, it really seems so. I absolutely don't oppose giving something to people who literally typed //= (or even RX~) in; it's just I'm skeptical of both the resolution of the searchbar anomalies, and the... practicality(?) of the scenario you are considering.
I mean, if you know what // is (which you can look up) and you come across //=, you should at least have the right impression what it may be, right? So I still think that the actual feelings of somebody in that situation would not be "hm, what is this really" but much rather "why have nobody told me about this" or "how does this other person know about it".
Have a syntax highlighter or some dedicated tool, that can deparse Raku and provide insight into how a piece of code is built up. Then one can know which operator a synthetic is made up of.
Good idea and I would really hope that one day the new, RakuAST-oriented parser would be a great aid towards that.
What I see as a problem that already kind of arises is the "not a real operator" situation. You remember the .= weirdness with the precedence, right? I'm thinking of similar cases. Should such a highlighter highlight based on the "naive" abstractions where everything that syntactically looks like an operator, is considered an operator, or expose them according to how Rakudo utilizes them? And anyway, do we have canonical, standard guidance on what a "real operator" is, or what can/can't be expected to work like a regular extensible operator?
This has broken up into a few asks. One is: "find //= when searching the doc site" which belongs in doc/website. Another is general syntax highlighting, which isn't a doc issue. Is there anything else that is an actionable request on the doc content itself?
