Re: Phix Tutorial problems
- Posted by petelomax Jan 05, 2023
- 5621 views
OK, brutal bit first, for me it rather "lacks ambition". I appreciate there are limits to what can be explained and know all too well how tough these things can be, for instance my latest additions to the standard docs must be on their fifth complete rewrite by now, and there are 85 automated backups of that one page just from December 2022, most of which would have led to a full rebuild and re-reading of it.
It is all very well and good to write a tutorial that shows how to write a grubby console app that could have been written on a zx80 in the 1980s, but it isn't going to excite or interest anyone. It needs to lead somewhere: maybe something you wrote, or browse https://rosettacode.org/wiki/Category:Phix/online or a selected subset of those, maybe even appropriately grouped and with some nice screenshots. The last part should pick one, reproduce the source code, perhaps manage to explain a few more bits, but without falling down the rabbit-hole, and refer them to the docs for any other questions it might raise. It should be short enough to digest, but also just sufficiently complex to spark someone's imagination. A screen shot of it running should probably be the opening introduction picture right at the start. [I think the Clock example ticks (geddit) more boxes than most, but it's not exactly exciting.]
Anyway, to the text itself (feel free to edit/reject any suggestions, me got plenty places to say stuff):
Phix is not a fork, maybe you could say clone. Here's my version of your opening paragraph (bit too long?):
Phix is similar to another programming language you have probably never heard of, Euphoria, and inherits a few things from that such as .exw and .e file extensions. Euphoria has been around since the 1990s, and is written in C with some parts self hosted and transpiled to C, which should theoretically make it easier to port. Phix has been around quite a bit less, since just before 2010, is a complete rewrite, and is entirely self-hosted/directly generates executables. Both require an existing working version to build, but that can be done on a completely different operating system. The chicken and egg problem was/is solved in Euphoria via C, and was/no longer needed in Phix via FASM.
Aside: technically there is a third kind of subroutine: type (just sayin, you might be quite right to leave it out)
This implies that functions or procedures cannot mutually call each other, at least not without an explicit forward declaration (which we'll explain later)... or maybe:
For two routines to mutually call each other, you need to use an explicit forward declaration[, which is not entirely unlike the way C does things, except in Phix they are the rare exception rather than the rule].
Aside: technically file extensions can be anything you like, but:
Any include statement must exactly match the actual filename.
Most editors use the file extension to determine syntax colouring.
After entering "p hello", and as long as it fails to find "hello", the interpreter will look for "hello.exw", but
it won't for instance[/as yet] try looking for, say, "hello.phix" - but it would be fine if run as "p hello.phix".
Likewise the OS can be set up to open .exw files with the Phix interperter when you double-click on them,
and should you start using (say) ".phix" then any such association would obviously need to be replicated.
Re `selecting the index tab in the Phix documentation`: If you are using the supplied Edita the syntax colouring should immediately alert you to any potential clashes, and of course the same would be true with any other editor once full and proper syntax highlighting for Phix source code is configured.
After "if you change its value, this will not be passed back to the calling routine" add ", unless of course you do so explicitly".
After "Let’s try with declaring s as a string, which is what it is supposed to be, after all." you've left it as "sequence s"
After "Something like s[3][6..8][2] ist not possible, though" (and deleting the rogue t), " - what that would be asking for is actually just s[3][7], so use that simpler form instead, or perhaps you meant vslice(s[3][6..8],2) - if needed look up vslice in the standard docs".
Aside: re doublequotes and backticks: backtick strings cannot contain escaped characters, so `hello\n` is the same as "hello\\n" and not "hello\n".
That the backend shows `It's me` instead of "It's me" is a mini-buglette down to `She said "Ugh" to me` being deemed better than "She said \"Ugh\" to me" if you see what I mean, and the single quote is (incorrectly) triggering what only doublequotes would actually benefit from. The one thing I really try to avoid is displaying {72,101,108,108,111} instead of "Hello", not that I can always manage that.
As you can probably imagine, the number of times I've said to myself "wouldn't it be nice if" about ? (or some other feature) is something I lost track of rather a long time ago, and quite a few got slapped in while I was letting my subconscious unpick something else. Things like puts() do a very specific job and can be/are tested on a regular basis, whereas ? follows no standards and would be difficult to test(/capture) even if it did.
I was co-incidentally thinking of making backticks the primary/more common means of declaring strings, and the default form for ?, on the basis of it being immediately obvious there are no escaped characters, but for now I'm just trying that idea out in this new gui thing I'm toying with (with no changes to ? planned as yet).
