Getting Started Guide: add rendering to HTML example
oldfartdeveloper opened this issue · comments
Per PR #324, this discussion, we should add an example of how Purescript renders to the browser and why using spago run instead of npx parcel index.html --open breaks.
I'd rather not, actually; I think this should be beyond the scope of this guide, especially because there are quite a few options for this, and none of them seem ideal. I don't think the low-level DOM API bindings are a good fit because they're very verbose and people are unlikely to be using them in a real project either; alternatively you could use one of the web UI libraries like halogen or react-basic, but then you have to privilege one library over the others, and I think such documentation is better placed in those individual libraries anyway.
The overarching issue I have with the Getting Started Guide is, as a new user who doesn't know ANYTHING about PureScript at this point, the complexities of DOM API, etc. are daunting, and, as you suggest, inappropriate for a newbie anyways.
I think that the Euler example introducing these complexities is drifting away from the purpose of this guide: it shouldn't be showing off PureScript; rather it should be assisting the reader in verifying:
- That his installation basically works.
- That PureScript can do what a newbie would expect it to do: render some result of a PureScript function to an HTML page element.
The typical newbie isn't ready to process the JavaScript explanations for Euler yet at this point in this guide.
Issue #326 discusses this and suggests the diagonal exercise.
I dunno, I think part of the purpose of the getting started guide should be to give people a feel of what PureScript feels like to write code in, and taking a list of things, filtering it, and then summarising it is a pretty common thing to want to do, so to me it feels like a good way of achieving this. I don’t think the Euler example detracts from verifying that the compiler has been installed properly, because I think that has already been established once you’ve managed to have the repl evaluate something. In principle I think it makes sense to widen the scope of the guide to include having a PureScript program which modifies HTML on the current page but as I say there are practical considerations that, imo, rule that out.
This seems to have been decided, at least tentatively, by the current commit level as of Dec 29, 2022; the text uses the browser debugger. I do believe that there should be an HTML example, but that's another issue. Hence closing this issue.