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/eb0efca6-33d4-4321-a75b-ed1c35ba45efn%40googlegroups.com.
