decont index is wrong

[librasteve]

Problem or new feature

Search on decont in the index takes you to the glossary.

Beginners are unable to find the decont operator page i the doc unless they know it is ``<>``` beforehand.

Suggestions

Please change the index target to the <> operator page.

[2colours]

To redirect decont to zen-slicing or one of the two (!) postcircumfix operators that can be used for decontainerisation (yes, [] is no different) is simple. If that's fine with you, please say your preference.

However, the bigger problem is that the decont operator only exists in our heads. I think this is the kind of metaphysical problem that is really hard to resolve. Perhaps the clearest thing to do would be to really just introduce a dedicated method or operator for it. Please read that discussion and try to think about solutions yourself as well.

[librasteve]

Ha! So any Zen slice of one thing returns the value, eh? That's funny.

I liked the world where there is a decont postcircumfix operator with syntax xxx<>.

Please take me back there... by linking to the decont operator page (i) because while raku containers are almost invisible, almost is not the same as entirely (ii) many folk coming from other languages will look for decont in the docs and the current decont operator page does what they expect

Then we can gently introduce the intersection with zen slices (which is somewhat confusing), then a small link at the bottom of that page that says something like "The decont operation is one of the uses of Zen slices when there is just one element."

Actually the zen slice page already does a good job of linking back to the decont page.

[2colours]

Could you please clarify? I'm not sure what you miss; the way I understand is that you imply the same thing @0rir said explicitly in the other issue - namely that there is a postfix <> operator that does the decontainerisation.

So, again, we have 2 concepts and 1 behavior. I see 3 resolutions:

• don't change the behavior but do discuss the 2 concepts strongly distinguished: I think this is basically the status quo, plus continuous improvement as with anything. It is an option but I don't like it. This lead to all of us being tripped up and thinking there is actually a "decont operator".
• sink the "decont" ship altogether and only talk about it as a sub-case of zen-slicing. I think if properly implemented, this is better than the status quo. although somewhat risky. I see the key to this in keeping the "decont" terminology BUT without "operator". "decont" is conveniently done by zen-slicing and that's about the associated syntax
• separate the 2 concepts into 2 distinct "behaviors". Preferably, create something that does this and only this. I think the sole existence of a dedicated thing (that is, without it being actually preferred and used by people) could ease the life of a learner - because at least one could say "this is explicitly for this purpose - but for XYZ reasons, you can see zen-slicing as a convenient way to achieve the same thing"

[librasteve]

To clarify per @2colours request, here is what I would like to see...

The facts:

• There is one general mechanism, zen slicing
• One of zen slicing's specific uses, when applied to a single element, is decont behaviour

The presentation:

• If newbies, coming from a language with containers and decont operators, look for it there is a decont operator page like the one we have ... this should be improved by a gentle reference to this being a special case of zen slice behaviour
• Those who encounter zen slices first should be informed that decont behaviour is a special case (no change to today)

I do not see an issue with describing the decont behaviour as a postcircumfix <> operator since, err, it is an operator, and that way sits nicely in the list. The art of documentation is to choose words that can carry levels of meaning to multiple audiences.

The merits of what I propose are:

• It is a very small adjustment to the current docs (change the index target and add one line to the current decont operator page)
• It is a practical help for folks to find a way to do a decont operation

FWIW I love that raku often has 2 concepts and 1 behaviour ... IMO it is a power to recognise that a specific point feature (here decont) is a special case of a more generic and elegant semantics (here zen slices). And the existing doc is very close to what we need in that it brings in searchers for the specific and gives them a practical answer ... just needs to add a subtle on ramp to the zen slice angle.

[raiph]

@p6steve

One of zen slicing's specific uses, when applied to a single element, is decont behaviour

The ", when applied to a single element" bit has me baffled. It's applied to the LHS, which is assumed to be a collection (eg an array), no?

If newbies, coming from a language with containers and decont operators, look for it

I'm pretty sure Raku is the only source in the world of the word "decont" in the context of "containers" that's relevant to this discussion. (If you look through the matches for a google for "decont" "containers" I think you'll agree I'm right. If not, please comment on something I missed.)

If so, presumably only folk who have read/heard Raku mentions of "containers" and "decont" will search Raku's doc for them.

The only PLs I know with essentially the same thing at a conceptual level are APL family PLs. (I imagine there may be others; I just don't know them.) I think what Raku refers to as containers (aka Scalars) APLs refer to as "enclosures", and decontainerization as "disclosure", done by a "disclose" operator.

FWIW, after a serious effort to find a better name for these concepts, I concluded APLs were the best I encountered for my taste, but weren't so much better than "containers" and "decont" that it felt worthwhile discussing with Rakoons. I think this is my first mention of that effort (and presumably last).

[librasteve]

@raiph

I stand corrected that (to my surprise) raku variable containers are not called that in other languages. And so the term decont is less widely used than I had assumed.

Nevertheless it is peppered through the current docs and has some resonance. This Issue does not propose to materially change the docs, but to point the index search term decont to an existing informational page rather than the glossary.

I see that I have confused matters with my poor understanding of what a Zen slice does. I have re-read the docs and would ask folks to ignore my "when applied to a single element" words. Thanks for gently explaining my error!

[0rir]

The decont operator should be find-able by name.

I think this well made simple issue is being damaged by excess noise.

[2colours]

I disagree that there is a "simple issue", just like I disagreed at your related issue that I already linked. I thought the revealing explanation from @raiph blew the illusion of the "simple issue" away for good - not because I love keeping things complicated but because acting upon our own confusion caused by the docs might just cause further harm. Some of that harm comes simply from a kind of reassurance of misunderstandings: the more a misunderstanding is acted upon, the more we will actually believe it to be right.

I realize it only now that this part of the documentation is causing the confusion and it doesn't even say "technically, not a real operator" or anything like that... In fact, neither "postcircumfix < >", nor "postcircumfix <>" are real operators; moreover, they are the same thing: &postcircumfix:<{ }>, handled here (v6.d): https://github.com/rakudo/rakudo/blob/2022.12/src/core.c/array_slice.pm6#L281.

To call zen-slicing "decont operation" is fine by me but I heavily oppose keeping this "fake operator" in the documentation. I do think it's a good thing to give people helpful mental frameworks - but give me a break, to populate the documentation with operators that don't even exist, and then split them up by a distinction that also doesn't exist? That's too much, and honestly, I don't understand why this should even be controversial.

I would really like to eliminate the [postcircumfix <>](https://docs.raku.org/language/operators#___top) and then return to this question. It simply shouldn't be one of the options to explicitly foster this misunderstanding that there are two vaguely overlapping operators with different semantics.

[codesections]

Two thoughts: First, the docs don't need to exactly mirror the Rakudo implementation – even if Rakudo doesn't define a separate <> decontainerization operator, it may be clearer to describe separate operators in the docs (or it may not be; I'm just saying the implementation details don't matter).

Second, does part of the problem come from documenting postcircumfix <> when it should be postfix <>? If we're talking about a pure decont operator, then there can never be anything inside the <> – and that's exactly the point of distinguishing it, right?

[lizmat]

See also: https://github.com/rakudo/rakudo/pull/5124

[2colours]

First, the docs don't need to exactly mirror the Rakudo implementation – even if Rakudo doesn't define a separate <> decontainerization operator, it may be clearer to describe separate operators in the docs (or it may not be; I'm just saying the implementation details don't matter).

That's almost literally what I said here in the other issue but let me quickly quote myself:

To be honest, I don't think this can be done in a non-confusing way if there isn't a tested implementation that does separate the concepts on a code level, so I'm afraid to do something like this right would result in a change on a language level, for relatively small benefit.

So yes, I absolutely agree with the principle but I think this is a very risky road to walk down upon.

Second, does part of the problem come from documenting postcircumfix <> when it should be postfix <>? If we're talking about a pure decont operator, then there can never be anything inside the <> – and that's exactly the point of distinguishing it, right?

And that's literally the topic of the other issue.

Yes, pretty sure it's better to call the fake operator postfix <> than postcircumfix <> and that's a "small issue" - but what does this matter in the bigger picture that in my opinion, whatever we call this, it desperately needs to go. It's "too dangerous to be kept alive".

[0rir]

If one can find fault with the user documentation only by reading the source, there is no fault in the documentation.

It would have saved me a significant amount of time if I had found <> more easily.

[2colours]

I have completely oppositional experience: I didn't need to read the source whatsoever to suspect something is off about this "decont operator" and I would rather spare this confusion from others as well, not build upon it further. Just a few examples that can be concerns of a user:

• when is the "decont operator" invoked and when subscripting?
• how can one overload the "decont operator"?

I did find myself asking questions of this sort and eventually it turned out that the questions themselves were nonsensical. I would say there is fault in the documentation if it leads you into this situation.

As much as the documentation is not a Rakudo cookbook, I very strongly believe that it is not the right place to feed the users with "comforting lies". The documentation is bearing with a lot of stuff a reference or a specification is about - the "technically, not a real operator" notes also illustrate that. Mind you: I'm not arguing against a possible mental framework that masks the decont use of <> (and well, {} and []) as an operator - what I'm saying is that the documentation, and in particular the structured, non-tutorial part of the it, is not the right place for that.

I truly hope this approach is convincing enough... the docs are very much the last line of defense. If something could be better explained in a less accurate but simpler manner, there are loads of places to discuss that. However, if something is inaccurate or downright misleading in the one and only documentation - currently the most formal maintained textual resource about the Raku language, - then we really leave those users alone who want to confidently know how Raku code works. And then they have to go read Rakudo sources.

[librasteve]

@2colours , yes I agree with your good points made on postfix / postcircumfix and on the fact that decont is not an Operator.

It seems to me that:

• there is an operator called "zen slice"
• one use of this operator is to remove single items from their container (an idea called "decont")
• it also does some other stuff

I would be opposed to completely removing the idea of decont from the documents and replacing entirely with the idea of zen slices. Why? Well, as mentioned, I think that the idea of decont is analagous to the more familiar dereferencing and unboxing found is other languages and where you have containers, from time to time you will want to decont the contents. Also, I think that zen slices is rather a hokey term that is unique to raku ...

If you agree that both terms should have a place in the docs, then the option is:

1. have a zen slice section that describes how it can be used to decont
2. have a decont section that describes how it is a particular use of zen slices
3. have both and link them

So I suppose the variant that is most accurate would be #1.

Perhaps the word 'decont' could be put in the Reference part of the index as it is not formally part of the language?

[2colours]

@p6steve I think "we are getting there", one way or another.

I think you summarized it well (one might nitpick that "zen slice" would rather be the result of subscript invocation with no "indexes" but yes - eventually it's like a thing on its own),

I also agree that the concept of decontainerisation needs to be captured and preserved in some shape or form. I also think that the PR @lizmat created helps on the case by offering tools that do decontainerisation and (clearly) only that. This could immediately help the convergence of decont-related content:

• the concept can still be mentioned in the glossary but now there would be a sub and method with one-to-one correspondence to it
• the concept can be further elaborated in a how-to article or the traps section (e.g iterating nested arrays might deserve a note about deconting the inner Iterable)
• zen-slicing can still cite decontainerisation as a common use (either the glossary or downright the sub and method)
• the sub/method page can include a note about the prevalence of using zen-slices for a similar purpose

If we remove the PR from this picture, it's more awkward but not completely hopeless. That would put greater demand on writing a howto guide on the topic, for it couldn't be mapped to a reference ("type") page.

Similarly, the "decont" terminology kind of depends on the outcome of the PR - if you think it helps to move it, I see no reason not to.

[librasteve]

cool