1. Phix Tutorial problems

This is only a minor grievance to me, but I thought I'd bring it up because it might put off potential users of Phix.

Following the "run pw edita" suggestion on the "Tutorial" page of the Phix website, I came across these issues in the "Welcome" text:

I recommend the tutorial by Wolfgang Fritz & Ad Rienks -> 404 Not Found
… and also the 'gateway' by Dan Moyer -> this is 22 years old
Visit http://www.listfilter.com/EUforum/ to ask questions or request help. -> Domain for sale
Open ealtest.exw and press F5 to run it. -> Cannot open arwen\arwen.ew

And then, in the "Help" menu, "Manual" -> 404 Not Found

This is where I gave up. Again, not really a problem for me, I'm happy enough with Phix without even knowing what Edita is meant to do, but for someone interested in Phix who is happy to see "Tutorial" (and probably expects one for Phix, not Edita), this is probably not a good experience?

Robert

new topic     » topic index » view message » categorize

2. Re: Phix Tutorial problems

Good catch, thanks. That text is I would guess 16 years old, untouched since, and quite probably predates the very existence of Phix!!

new topic     » goto parent     » topic index » view message » categorize

3. Re: Phix Tutorial problems

Might it be helpful if I tried to write an entry-level introduction to Phix? Just covering some 0.5% of the language, but possibly helping those who are either new to Phix or new to programming take the first steps and understand some of the basics? I don't want to obtrude, and I'd willingly take no for an answer, but I'd as willingly try to see what I can come up with, if you think it's worth a try.

new topic     » goto parent     » topic index » view message » categorize

4. Re: Phix Tutorial problems

Sounds pretty good to me, certainly no objections here. If I think it's any good I'll include it in the distro (if appropriate/you want) and put a clickable link to it right at the top of that welcome.txt - said link could easily open it in Edita, Phix.chm, or a web browser, or even have three separate links to that effect, and maybe some matching menu entries for when welcome.txt is no longer opened.

new topic     » goto parent     » topic index » view message » categorize

5. Re: Phix Tutorial problems

Great! Give me two or three weeks, then I'll post a link to a draft version, and we can see if it's any good and how to proceed with it.

new topic     » goto parent     » topic index » view message » categorize

6. Re: Phix Tutorial problems

Happy New Year, everybody! Here is the first draft of the Introduction to Phix that I've promised:
hypatia-rpn.net/phix-introduction.pdf

It's a PDF file, but could be easily converted to plain text, epub, HTML, or whatever.

Please tell me what you think of it, and what might need to be fixed, added, or improved. Also, English is not my native language, so please point out any mistakes I have made, in addition to what mistakes I may have made regarding Phix.

Robert

new topic     » goto parent     » topic index » view message » categorize

7. Re: Phix Tutorial problems

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).

new topic     » goto parent     » topic index » view message » categorize

8. Re: Phix Tutorial problems

Thank you for correcting my errors, and for teaching me things I had not been aware of. Apart from that, what I was aiming at, regardless of how far I missed the mark, from lack of ambition or lack of skills, was so different from the tutorial that you envision — thinking along different lines, writing from a different POV, and for a different hypothetical audience — that it makes no sense for me to try to improve or rewrite my “Introduction.” While I regret that I failed to contribute anything usable, I still learned a lot in the process, so at least I do not regret having tried.

new topic     » goto parent     » topic index » view message » categorize

9. Re: Phix Tutorial problems

RobertS said...

Thank you for correcting my errors, and for teaching me things I had not been aware of. Apart from that, what I was aiming at, regardless of how far I missed the mark, from lack of ambition or lack of skills, was so different from the tutorial that you envision — thinking along different lines, writing from a different POV, and for a different hypothetical audience — that it makes no sense for me to try to improve or rewrite my “Introduction.” While I regret that I failed to contribute anything usable, I still learned a lot in the process, so at least I do not regret having tried.

Aw, don't give up so easily! It was inevitable I was going to say something a bit harsh, and quite remiss of me to forget a little "thank you", it is quite good really, just that of course pretty much everything can be improved. It's fine if your vision and mine differ, I was just trying to push you towards loftier goals, and it's in my nature to never ever accept the first thing offered. The one/only thing I think it misses is an "inspirational image", and I was just trying to think of a way to justify one. I often find myself reading/skimming quite a few tutorials, and "show me an image then" is a faily common thought. Maybe deliberately leave it to one side for a couple of weeks and come back to it, see how you feel then.

new topic     » goto parent     » topic index » view message » categorize

10. Re: Phix Tutorial problems

Thank you! In what I wrote, I tried to retrace the path that had led me to Euphoria some 20 years ago (2.x, there were still $30 to pay), captivated by the concept of Euphoria’s "object" data type. Meanwhile, from my POV, this path has been so overgrown with lush vegetation (bearing delicious fruits, of course), that I wouldn’t see it anymore, if I were looking for a programming language now.

I’ll gladly fix all the errors and omissions that you’ve pointed out to me, and try to think of a few things to improve. On the "show me an image" front, though, I’m afraid I just cannot deliver – I know nothing about it, have never written a line of code that did anything graphic, and it’s just not how my mind works or what I’m interested in. I thought that maybe someone else could add some chapters to what I’ve written, but maybe it would be a better idea to have more than one “Introductions” – my very austere and abstract one, and one or more others that have more visual appeal, offer more practical examples, and approach Phix (or Euphoria) from different directions.

Maybe it’s a bit like explaining how to buy tickets for the London Underground, vs. writing a city guide book telling people where they may want to go, vs. discussing the train engines and the power supply they run on. I totally understand that what I can offer doesn’t even come close to being a tutorial, and will not appeal to potential users with an interest in doing anything with GUI – this just would have to be done by others.

I’ll post a note here when I’ve updated my text. Robert

new topic     » goto parent     » topic index » view message » categorize

11. Re: Phix Tutorial problems

Here is an updated version: www.hypatia-rpn.net/phix-introduction.pdf

I've fixed the errors that Pete has pointed out (really embarrassing ones among them), but I'm afraid that the main point of criticism still holds, that as an introduction it lacks ambition, is restricted to console apps, and doesn't provide inspirational examples that might appeal to potential users. Of course, I have no idea who those potential users may be, where they'd be coming from, what they might be looking for … Anyway, some further edits apart, this is all I can do – I think it might be better than nothing, but I'm probably not a good judge for that. Even if it is, it would be good if someone else would add the things that are missing (I could write a bit more about some basic language features, but that wouldn't address the main issue).

Robert

new topic     » goto parent     » topic index » view message » categorize

12. Re: Phix Tutorial problems

In my opinion, it starts off on the wrong foot.

Comparing Phix (a virtually unknown programming language) to Euphoria (another virtually unknown programming language) doesn't help anyone, and any mention of technical details needs to go into a footnote, not the main sales pitch.

IOW, the first two paragraphs provide no incentive for anyone to read further.

Learn about the "elevator pitch". In business, if you want to be successful, you should be able to "sell" a new idea or product in the time it takes to ride an elevator. Once you've got their interest - which generally boils down to "what can this do for me?" - maybe they'll sit down and discuss details.

First, burn page 3.

Start with why someone would want to use Phix. Why is it better/easier/more efficient than the popular languages? You only begin to touch on that by page 9, and then immediately mention pitfalls. It's not a pitfall - it's a feature. Nobody likes pitfalls.

Now, about the audience. You should decide if you are writing for someone who has never used any programming language, or to someone who is familiar with one (probably Python), or someone already fluent in several languages. That's 3 different groups of readers. Those who expect or require a GUI are the 4th. Ignoring their interest is counterproductive.

Summary: altogether too technical, complex, and with a strong negative vibe, but fixable with a total rewrite.

new topic     » goto parent     » topic index » view message » categorize

13. Re: Phix Tutorial problems

irv said...

Start with why someone would want to use Phix. Why is it better/easier/more efficient than the popular languages?

Possibly... "effective"?

Kat

new topic     » goto parent     » topic index » view message » categorize

14. Re: Phix Tutorial problems

irv said...

Start with why someone would want to use Phix. Why is it better/easier/more efficient than the popular languages?

An excellent suggestion. Someone should write this. Or even better, should have written it ten years ago. Not likely to happen, it seems.

Still, thank you for having taken the time to read and comment. You just propose things that are beyond my abilities.

(As a philosophical aside, features and pitfalls aren't mutually exclusive. Think of the proverbial two-edged sword …)

Robert

new topic     » goto parent     » topic index » view message » categorize

15. Re: Phix Tutorial problems

Having not thought about this myself for a couple of weeks, it is now blindlingly obvious that rather than a boring static image at the start it should be a web page (not pdf) that shows a running clock and finishes with something like:

While it's a bit beyond the scope of this brief introduction, here (better yet inline) is the source code for the clock shown at the start, and the exact same runs almost identically on Windows, Linux, and in a web browser.
It is probably perfectly possible to achieve something similar with, say, node+React, not that I've been able to find a similar example [anyone?], but I think you'll agree that single source file is significantly easier.
Of course the whole JavaScript ecosystem (ditto many other programming languages) has tens of thousands of eager contributors and we're not quite there yet with Phix, but if you're prepared to roll your sleeves up...

May take me a while to cobble something together - pretty much just a slightly tedious manual cut and paste job of the links just given (plus a mere six supporting files).
It would of course be nice to have editable syntax coloured code as per CodePen and the like, maybe on some kind of wiki, but one step at a time, eh?

PS: There's a planned upgrade to Miraheze on Jan 21, fingers crossed that'll include an updated pygments with proper Phix syntax colouring rather than the horrible mess I currently use, so I'll certainly wait for that.
PPS: There's no rush on this and I also certainly wouldn't bother to publish it anyway while that piggin segfault on Linux is still hanging over my head.

new topic     » goto parent     » topic index » view message » categorize

16. Re: Phix Tutorial problems

Sorry to disappoint, but no, can't do. I don't understand how these samples work, I don't understand how they prove the superiority or the unique features of Phix, I'm not interested in JavaScript or anything that happens in a browser (apart from using it), and if I saw a programming language promoted by the image of a running clock I'd be out of there without a second glance, because there hardly is anything that I care about less.

Not that I think it's a bad idea, it's just way too far removed from anything that means anything to me, or that I know anything about. If I'm indeed the only person left on Earth who writes console apps, so be it. As long as Phix keeps letting me do it, I'm happy. Thanks to all who have made it and keep making it possible.

Robert

new topic     » goto parent     » topic index » view message » categorize

17. Re: Phix Tutorial problems

RobertS said...

Sorry to disappoint, but no, can't do.

Erm, ok, <pause>, relax, calm down, that's fine, no worries.. I did say "May take me a while", meaning I expected to do it myself, and there's no hurry, haste or panic here.

RobertS said...

I don't understand how these samples work, I don't understand how they prove the superiority or the unique features of Phix, I'm not interested in JavaScript or anything that happens in a browser (apart from using it), and if I saw a programming language promoted by the image of a running clock I'd be out of there without a second glance, because there hardly is anything that I care about less.

Not that I think it's a bad idea, it's just way too far removed from anything that means anything to me, or that I know anything about. If I'm indeed the only person left on Earth who writes console apps, so be it. As long as Phix keeps letting me do it, I'm happy. Thanks to all who have made it and keep making it possible.

Hmm, that's fine, we're all unique individuals. I must admit I'm a little surprised those 130 lines of code provoked such alarm (geddit?), and I get we're a little different, like you're into books and poetry in a way I'm not, and likewise I trust you understand that I'm simply just trying to appeal to the broadest possible audience.

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu