Include ASCII Equivalents in Official Docs code Examples

[shishini]

For Perl6 new comers, those who are not familiar with the Perl6 community and culture
and how Perl6 came to be or evolve

The special Unicode Characters in code and especially in operators, can look very intimidating
it can be quiet engaging to find out how to insert those characters in your favorite OS or editor

Having Unicode only code samples and examples, might give the impression, that there is no other way to write that code, except using the unicode characters

It should be made clear in the docs, that for example this line
my @primes = ^∞ .grep: *.is-prime;
Can simply be written as
my @primes2 = ^Inf .grep: *.is-prime;

And if possible any unicode operator mentioned in the docs, should have a link to its ascii equivalent
I understand, that Perl6 might be trying to promote itself as a 100 year language, and that part of this is promoting the use of the nicer looking unicode characters, but for new comers who are not aware of this or sold on this idea, this can be very intimidating and confusing

[JJ]

In fact, we have the opposite policy for the docs. It's not written in stone, but this means that most examples are going to follow your example number 1, not the second.
If you want to follow through giving more good reasons, we'd be happy to listen to them, but this would be a major change (meaning little possibility to happening any time soon) so even if it was passed by reversing the guideline above, there's slim chance it's actually enforced.
In the example you mention, I don't see Inf particularly more informative (pun intended) than ∞, which is universally acknowledged as the Infinity sign. But in other cases it could be so, and we could include additional explanations to the example if that's the case. So please if you spot particular examples of that kind, feel free to create issues to improve them.
Bear in mind that Unicode symbols are a Perl 6 feature. Not using it in examples does not make any sense, since we actually want people to use Perl 6 to its full extent.

[AlexDaniel]

OK, actually, here's what happened. We had some examples using ascii chars, and other examples using non-ascii chars. While in some cases it's ok, generally it's inconsistent, so I came up with #1520, take a look at the issue for a justification.

Basically, we introduced “Prefer non-ASCII syntax in examples” not to piss off those who don't like unicode chars, but because you can then deunicodify examples with dumb-as-bricks code and very high rates of success (basically just s:g/∞/Inf/ will do).

So we can actually “Include ASCII Equivalents” as requested, someone just needs to do it. And then, should it be done in javascript or do we have any better alternative?

[tbrowder]

A dynamic method would be cool if it could be done fairly easily so non-fluent js folks could cookbook enter it fairly easily when the spirit moves them.

[shishini]

Hi, thanks for the feedback, I was not aware of the policy or issue #1520
And it seems that this was thoroughly discussed before

I don't want to waste anybodies time on this, but I will this say and I promise, I wont take it further or argue more, this was a very negative experience for me, and I am very sure, it will be a negative experience for many outsiders and new comers

This policy as it is implemented today

• Hides a feature, that ASCII equivalents exists and can be used

I think, we can keep the policy, but fix the undesirable side effect, it can be mentioned somewhere prominent on the site, that ASCII codes exist (this is not the case today)
Or adopt one of the proposed solutions from the previous discussions, for example a mouse over that shows the ASCII equivalent

[zoffixznet]

I was not aware of the policy

Sorry, I should've mentioned I was vaguely aware of something like that when I suggested you file the Issue.

If you want to follow through giving more good reasons, we'd be happy to listen to them

Here's the user not understanding how to write the code shown in the examples. The rest of the channel are in the middle of some weird religious discussion and answer the user only three minutes later.

So we can actually “Include ASCII Equivalents” as requested, someone just needs to do it. And then, should it be done in javascript or do we have any better alternative?

A really easy thing to implement would be just a piece of JS that scans for Unicode ops and sticks a tiny question mark icon next to that line. Hover over it and it shows a tooltip explaining that we have ASCII alternatives for all the fancy ops and the Language section has both a section on how to type fancy ops and a map of all the fancy ops to ASCII equivalents.

Basically, just making the user aware they don't have to use fancy symbols if they don't want to.

---

(the CSS code that genned the shown example. Probably needs more tweakage to work with different fonts. Also, since pres must have overflow set, the icon should be genned by JS outside of them):

.line.marked .source::before {
    content: "？";
    position: absolute;
    left: -4ex;
    font-size: 80%;
    display: block;
    background: #aaf;
    color: #fff;
    border-radius: 3ex;
    width: 2.5ex;
    height: 2.5ex;
    text-align: center;
    vertical-align: middle;
    box-shadow: 0 0 1px rgba(0,0,0,.2);
    margin-top: 1px;
}

[coke]

https://docs.raku.org/language/unicode_ascii exists, which shows the alternatives. See the related commit for an addition of this information to the intro page, which should answer the modified ask.