Shameless self-promotion: here is a thing I did some years ago - http://langintro.com/cljsbook/
On Thursday, January 21, 2021 at 1:39:50 AM UTC-8 [email protected] wrote: > Hello! > > I totally agree that allowing beginners to learn ClojureScript and > experimenting with code in the browser bring a huge benefit and will > increase ClojureScript usage. > > Klipse addresses this challenge by providing: > - An online ClojureScript repl: http://app.klipse.tech/ > - A way to embed ClojureScript running snippet in a web page (blog posts, > documentation etc..) > > Several online ClojureScript tutorials leverage Klipse. Here are some > examples: > > 1. Reagent deep dive > http://timothypratley.blogspot.com/2017/01/reagent-deep-dive-part-1.html > 2. How to write macros > https://blog.klipse.tech/clojure/2016/05/05/macro-tutorial-3.html > > On Friday, 9 October 2020 at 17:24:12 UTC+3 [email protected] wrote: > >> Hi. I am new to ClojureScript. Here is my story so far. It highlights the >> unnecessary hurdles a new ClojureScript programmer has to overcome. I hope >> this helps make the ClojureScript better for everyone. >> >> After reading SICP >> <https://en.wikipedia.org/wiki/Structure_and_Interpretation_of_Computer_Programs> >> >> and "On Lisp <https://en.wikipedia.org/wiki/On_Lisp>" I am quite excited >> about lisp especially about lisp macros. The web is a very attractive >> platform to develop for. One day I set out to find an intersection of the >> two. A quick search returned a number of options and ClojureScript was one >> of them. >> >> # Finding a tutorial >> Every Lisp dialect is somewhat different from the rest and I had no prior >> experience with Clojure. How does one pick up a new programming language? I >> needed to find some kind of tutorial or introductory book. Something that >> would at the very least teach me the syntax and semantics of the language, >> the builtins and essential parts of the standard library. Ideally it would >> also teach me some common idioms. I tried to find a link to such a >> book/tutorial on the https://clojurescript.org website, but failed. >> There is a prominently displayed "Get Started!" button, but it currently >> points to a page that teaches you how to install ClojureScript and, for >> some reason, how to do "Production Builds", but does not even cover the >> entire syntax of ClojureScript. Nor does it contain links to more complete >> introductory materials. I did eventually discover the amazing ClojureScript >> Unraveled <https://funcool.github.io/clojurescript-unraveled/>. Only >> later did I find out that the link was there all along, but it was buried >> where I would have never guessed to look: the "community" tab of the >> https://clojurescript.org website. When I think "tutorial" I don't think >> "community", when I read "community" I don't expect to find a tutorial >> there. >> >> Some examples for comparison: >> - https://elm-lang.org has a big and obvious "Tutorial" button on its >> homepage >> - https://www.haskell.org has an interactive tutorial built into its >> homepage. After you chew through it, the tutorial suggests you look in the >> "Documentation" section of the website that contains links to books, >> courses, tutorials etc. >> >> # Finding an online REPL >> OK I found a tutorial. To follow it I want to be able to actually type >> some code and see it print some output. I personally find it more >> convenient at this stage of learning a new language to use an online REPL >> rather than trying to figure out how to install the interpreter or the >> compiler locally. Even if installing is as simple as downloading and >> unpacking a tar or executing a bash script I still prefer an online REPL. I >> again struggled to find a link to an online REPL from the >> https://clojurescript.org website because it was also hidden on the >> "Community" tab. Also: out of the 3 REPLs advertised there only one ( >> https://clojurescript.io) has an HTTPS version. >> >> Some examples for comparison: >> - https://www.python.org has a REPL built into its homepage >> - https://elm-lang.org has a big and obvious "Try" button >> >> # Installing the compiler >> OK I learned a bit of Clojure, I experimented a bit now I want to start >> developing in it. To do that I need to install the compiler on my machine. >> At this point I'm looking for links that say "install" or "download". Where >> do I find the installation instructions? "Get Started!", obviously. >> >> # The REPL hangs on Linux >> A little bit about my system: Linux+Firefox. It turns out that there is a >> known bug that causes the REPL to hang under this configuration. I was >> following the "Get Started!" tutorial. When I executed "clj --main >> cljs.main --compile hello-world.core --repl" I expected to see "Hello >> world!" printed in my terminal, but instead I saw something that looked >> like a REPL prompt but was completely unresponsive. The bug is even >> documented in the tutorial, but in a manner that took me an embarrassingly >> long time to find. Usually when a step in a tutorial fails the steps that >> follow it are irrelevant until you can figure out what went wrong so I did >> not continue to read the tutorial. The workaround for this bug is >> documented almost an entire page *below* the failing step. The >> workaround is also not visually highlighted - easily overlooked when >> skimming. >> >> # It is hard to figure out the REPL and compiler options >> For some reason instead of following the common convention of >> --option=value the compiler (clj --main cljs.main) invents its own command >> line syntax based on the EDN <https://github.com/edn-format/edn>. On top >> of that neither https://clojurescript.org/reference/repl-options nor >> https://clojurescript.org/reference/compiler-options nor >> https://clojurescript.org/reference/repl-and-main actually provides an >> example of specifying EDN on the command line. It currently just so happens >> that https://clojurescript.org/guides/quick-start does provide such an >> example, but only because it needed to document the workaround for the >> above mentioned bug. Also: in many places the extensible data notation is >> referred to by a cryptic 3-letter acronym EDN that probably has 300 >> different meanings. The acronym not being a link pointing to >> https://github.com/edn-format/edn does not help either. Also: >> edn-format.org is missing an HTTPS version. >> >> # Specifying :watch-fn on the command line results in a confusing error >> I specified --compile-opts '{:watch "src" :watch-fn (fn [] (println >> "built!"))}' on the command line and expected to see it print "built!" >> every time my source is rebuilt. Someone more savvy in how EDN works would >> know that this won't work, but to me this wasn't obvious until I tried it. >> Nothing was printed on the command line. It did not print "built!". It did >> not print any error messages. Luckily it did say: "compilation log >> available at: out/watch.log". Opening this file gave me a hint as to what >> went wrong: "java.lang.ClassCastException: clojure.lang.PersistentList >> cannot be cast to clojure.lang.IFn" but the error message could certainly >> be much more newbie-friendly. Out of the two >> <https://clojurescript.org/reference/repl-options#watch-fn> places >> <https://clojurescript.org/reference/compiler-options#watch-fn> where >> watch-fn is documented only one mentions "cljs.build.api/watch", but even >> then it does not actually link to https://cljs.github.io/api/ >> compiler/cljs.build.api/#watch leaving me to wander what >> "cljs.build.api/watch" means. Is it a file? Is it a command line tool? >> Apparently it is an API. How was I supposed to figure that out? >> >> # Hot reload >> "Why was I messing with compiler options and :watch-fn?" you might ask. >> What I actually wanted was hot reload. When I looked at the documentation >> for :watch-fn it looked to me as if the compiler already provides the hot >> reload functionality and no 3rd-party tools are necessary. Someone who >> knows a little bit about the compiler internals would know that :watch-fn >> is executed in the compiler instead of being executed in the context of my >> code, but this is not obvious from the documentation provided on >> https://clojurescript.org. I did eventually figure out that I do have to >> install an additional 3rd-party tool to get hot reload and went with >> https://figwheel.org. >> >> # Reference/Guides split >> A number of miscellaneous documentation topics on >> https://clojurescript.org are split into two sections "Reference" and >> "Guides". Perhaps there is some deep wisdom to which documentation pages >> belong where but so far it eludes me and when I have a question I have to >> look in both sections. Perhaps merging them into one and naming it >> "Documentation" would be better. >> >> # Miscellaneous nitpicks >> - When I first saw your documentation I saw a list of links on the left >> and a list of links on the right. It did not take me long to figure out >> that one is the table of contents for the current document and another is a >> list of links to other documents in the same section but it wasn't >> immediately obvious to me either. A https://readthedocs.org like format >> would be less confusing. Example: https://docs.readthedocs.io/ >> en/stable/intro/getting-started-with-sphinx.html >> >> - When I scroll the page the table of contents and links to other >> documentation topics scroll out of view instead of staying on the screen. >> >> - The landing pages for "Reference" and for "Tools" duplicate the list of >> documentation topics in that section, but not one-to-one. >> https://clojurescript.org/reference/documentation has a heading labeled >> "API Documentation" but this heading is not duplicated in the links on the >> left of the page. The "Tools" section of your website has pages for >> lein-cljsbuild and lein-figwheel, but there are no corresponding links on >> https://clojurescript.org/tools/tools >> >> -- Andrey Bienkowski >> > -- Note that posts from new members are moderated - please be patient with your first post. --- You received this message because you are subscribed to the Google Groups "ClojureScript" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/clojurescript/5ade4964-4962-4ebf-a208-e0e5b30aa86en%40googlegroups.com.
