Prefer non-ASCII syntax in code samples

[AlexDaniel]

I am inclined to create this ticket because:

• There was a ticket asking to provide texas versions of code snippets: #526
• “The community as a whole is pushing unicode; I think the docs should lead in this effort, and it's OK to be unicode only, because […]”⁽¹⁾
• Replacing non-texas ops will be relatively easy should we decide to move in another direction (much easier than doing the opposite)
• Automatically replacing non-texas ops on the fly will be possible if we decide to reopen #526 (other way around is nearly impossible)
• Copy-pasting code snippets from docs into perl6 -e '…' is easy for users if non-ascii quotes are used consistently
• Currently our docs are using "…" type of quotes too much (possibly contributors are preferring "…" instead of '…' so that things can be copy-pasted into perl6 -e '…', but I'd much rather see single quotes used consistently when no interpolation is needed)
• The transition is relatively easy given that we don't have to force contributors to use non-ascii stuff. We can simply have some xxt/ tests and someone who can type non-ascii stuff easily will rework a bunch of new code snippets once a few months.

It may sound radical but I guess that's technically the right thing to do.

TODOs:

• [x] Document this style decision
• [ ] Rework the majority of code samples, perhaps in a semi-automated way (over 50% is enough)
• [ ] Help with https://github.com/vim-perl/vim-perl6/issues/8 https://github.com/perl6/atom-language-perl6/issues/72 https://github.com/perl6/perl6-mode/issues/14
• [ ] https://github.com/drforr/perl6-Perl6-Tidy/issues/3 ?
• [ ] Add some xt or xxt tests?

[AlexDaniel]

FWIW for downvoters: consider upvoting instead. This ticket will give enough incentive to provide automatically generated texas code samples. Right now we have a bunch of code samples with texas syntax and a bunch of code samples with non-texas syntax. Everyone loses. But we can possibly have a win-win situation if we start moving into the direction this ticket suggests.

[AlexDaniel]

Just to clarify the texas/non-texas confusion, this ticket is saying that we should change in code samples:

• Inf to ∞
• >> to »
• etc.

[JJ]

I'm all for this, but we should either provide a test that checks it or an exhaustive list to start modifying it.

[nxadm]

I understand that a lot of people love unicode source code. For a lot of people in my surroundings, however, it's seen as "cute". Needing to configure shortcuts and keyboard profiles just for "hello world"-type of examples is a non starter for a lot of people. It would be for me.

[AlexDaniel]

@nxadm that's OK and I think nobody is objecting. But what is your proposal?

As stated in the OP, we already have some examples with non-ascii characters. Changing them all to ASCII is not going to happen I think, but we can perhaps turn them into links that point to unicode_ascii page, so that anyone can quickly see the ascii equivalent if they need to. Would that be good enough in your opinion? And if not, what would be then?

[nxadm]

I don't know about web development enough, but it would be could if the ascii example would he hidden under a click-open arrow beneath the unicode example.

[JJ]

Not sure we can do that with POD6. Can you show an example? We could use CSS and regexen, right? Isn't that supposed to work now?

[nxadm]

@JJ: https://www.w3schools.com/howto/howto_js_collapsible.asp

[AlexDaniel]

Looking at it now:

Automatically replacing non-texas ops on the fly will be possible if we decide to reopen #526 (other way around is nearly impossible)

This is probably incorrect, as Perl6::Tidy can do the conversion both ways (https://github.com/drforr/perl6-Perl6-Tidy/issues/3). One is more difficult that the other for sure, but both should be possible.

[JJ]

We can generate them statically and have some CSS magic select one or the other.

El sáb., 21 jul. 2018 a las 13:42, Aleks-Daniel Jakimenko-Aleksejev (< [email protected]>) escribió:

Looking at it now:

Automatically replacing non-texas ops on the fly will be possible if we decide to reopen #526 https://github.com/perl6/doc/issues/526 (other way around is nearly impossible)

This is probably incorrect, as Perl6::Tidy can do the conversion both ways (drforr/perl6-Perl6-Tidy#3 https://github.com/drforr/perl6-Perl6-Tidy/issues/3). One is more difficult that the other for sure, but both should be possible.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/perl6/doc/issues/1520#issuecomment-406789964, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAB9Ly5p7HYV9Q5X6-Y-CileC_0Kt5jks5uIxOigaJpZM4PLD84 .

-- JJ