Update install instructions

1. Clarify we don't like IntelliJ 2. Update Windows instructions 3. General clarifications
creativescala · Sep 19, 2023 · ca3cda0 · ca3cda0
1 parent c5e7240
commit ca3cda0
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 107 deletions.
diff --git a/book/src/pages/setup/README.md b/book/src/pages/setup/README.md
@@ -3,7 +3,7 @@
 Our first step is to install the software we need to work with Creative Scala. We describe two pathways here:
 
 1. Working with a text editor and a terminal. *We recommend this setup to people completely new to programming* as there are fewer moving parts.
-2. Working with IntelliJ IDEA. We recommend this setup to people who are used to using an IDE or are uncomfortable with the terminal.
+2. Working with IntelliJ IDEA. We do not recommend this setup to new learning, but mention it here as some people will have prior experience with IntelliJ or similar IDEs.
 
 If you're an experienced developer, with a setup you are happy with, just keep the tools you know and adapt the instructions below as needed.
 

diff --git a/book/src/pages/setup/intellij.md b/book/src/pages/setup/intellij.md
@@ -1,6 +1,6 @@
 ## IntelliJ
 
-IntelliJ is an integrated development environment (IDE) for Scala and other programming languages. It integrates an number of programming tools into one application, and we recommend it for people who are used to using other IDEs such as Visual Studiol or Eclipse.
+IntelliJ is an integrated development environment (IDE) for Scala and other programming languages. It integrates an number of programming tools into one application. We do not recommend using IntelliJ, but some people are used to using it or other IDEs such as Visual Studio or Eclipse and so we have instructions here.
 
 Start by [downloading][intellij-download] and installing IntelliJ. You can use the free community edition for Creative Scala. When installing IntelliJ you will be asked a lot of questions. You can accept the defaults for the most part. When you are asked about "featured plugins", *make sure you install the Scala plug-in*.
 

diff --git a/book/src/pages/setup/terminal.md b/book/src/pages/setup/terminal.md
@@ -1,162 +1,120 @@
-## Installing Terminal Software and a Text Editor
+## Our Recommended Setup
 
-This section is our recommended setup for people new to programming, and describes how to setup Creative Scala with the terminal and a text editor.
+This section is our recommended setup for people new to programming, and describes how to setup Creative Scala with the terminal and [Visual Studio Code][vs-code].
 We need to install:
 
 - the JVM;
 - Git;
-- a text editor; and
+- a text editor (Visual Studio Code); and
 - the template project for Creative Scala.
 
 
-### OS X
+### Installing the JVM
 
-Open the terminal. (Click the magnifying glass icon on the top righthand side of the toolbar. Type in "terminal".)
+The easiest way to install the JVM is to install [Coursier][coursier]. 
+It will also install some other useful Scala programs at the same time.
+Follow the instructions on the home page to install it.
 
-Install Java.
-Type into the terminal
+Then follow the instructions below that are specific to your operating system.
 
-```bash
-java
-```
-
-If this runs you already have Java installed.
-Otherwise it will prompt you to install Java.
+### MacOs
 
-Install homebrew.
-Paste into the terminal
-
-```bash
-/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-```
+After installing [Coursier][coursier]:
 
-Install `git` using homebrew.
-At the terminal, type
+1. Open the terminal. (Click the magnifying glass icon on the top righthand side of the toolbar. Type in "terminal".)
+2. Install [homebrew][homebrew], following the instructions on its site.
+3. Install `git` using homebrew. At the terminal, type
+ ```bash
+ brew install git
+ ```
+4. Now install the text editor Visual Studio Code. Again type at the terminal
+ ```bash
+ brew install --cask visual-studio-code
+ ```
+5. Install Scala support inside Visual Studio Code: Code > Preferences > Extensions and install:
 
-```bash
-brew install git
-```
+ - Scala (Metals)
+ - Scala Syntax (official)
 
-Now install the text editor Visual Studio Code.
-Again type at the terminal
+6. Now we will use Git to get an SBT project that will work with Creative Scala. Type
+ ```bash
+ git clone https://github.com/creative-scala/creative-scala-template.git
+ ```
 
-```bash
-brew install --cask visual-studio-code
-```
-
-Install Scala support inside Visual Studio Code: Code > Preferences > Extensions and install:
-
-- Scala (Metals)
-- Scala Syntax (official)
-
-Now we will use Git to get an SBT project that will work with Creative Scala.
-Type
-
-```bash
-git clone https://github.com/creative-scala/creative-scala-template.git
-```
-
-<div class="callout callout-info">
-#### Sharing Your Work {-}
+@:callout(info)
+#### Sharing Your Work
 
 There is an alternative setup that involves first forking the Creative Scala template project, and then cloning it to your computer.
-This is the setup to choose if you want to share your work with other people; for example you might be taking Creative Scala with a remote instructor or you might just (quite rightfully) be proud of your work.
+This is the setup to choose if you want to share your work with other people; for example you might be taking Creative Scala with a remote instructor or you might quite rightfully be proud of your work and want others to see it.
 
 In this setup you first *fork* the Creative Scala template.
 Then you make a clone of *your* fork.
 This alternative setup is described in more detail in the section on GitHub later in this chapter.
-</div>
-
+@:@
 
-Now change to the directory we just created and run SBT.
+To finish, change to the directory we just created and run sbt:
 
 ```bash
 cd creative-scala-template
-./sbt.sh
+sbt
 ```
 
-SBT should start.
-Within SBT type `console`.
-Finally type
-
-```scala
-Example.image.draw()
-```
-
-and an image of three circles should appear!
-
-If you've made it this far you've successfully installed all the software you need for work through Creative Scala.
+sbt should start. Within sbt type `run` and an image should appear. It it does you have everything correctly installed!
 
 The final step is to load Visual Studio Code and use it to open `Example.scala`, which you can find in `src/main/scala`.
 
 
 ### Windows
 
-Download and install Java.
-Search for the "JDK" (Java development kit).
-This will take you to Oracle's site.
-Accept their license and download the JDK.
-Run the installer you just downloaded.
+After installing [Coursier][coursier]:
 
-Download and install Atom.
-Go to `https://atom.io/` and download Atom for Windows.
-Run the installer you've just downloaded.
+1. Download and install [Visual Studio Code][vs-code] using the installer on their site.
+2. Open Visual Studio Code and add Scala support: Code > Preferences > Extensions and install:
 
-Download and install Git.
-Go to `https://git-scm.com/` and download Git for Windows.
-Run the installer you've just downloaded.
-At the very end it gives you the option to open Git.
-Select that option.
-A window will open up with a command prompt.
-Type
-
-
-```bash
-git clone https://github.com/underscoreio/creative-scala-template.git
-```
+ - Scala (Metals)
+ - Scala Syntax (official)
+3. Download and install [Git](https://git-scm.com). At the very end of the installer it gives you the option to open Git. Select that option. A window will open up with a command prompt.
+4. In the Git command prompt type
+ ```bash
+ git clone https://github.com/underscoreio/creative-scala-template.git
+ ```
 
-<div class="callout callout-info">
-#### Sharing Your Work {-}
+@:callout(info)
+#### Sharing Your Work
 
 There is an alternative setup that involves first forking the Creative Scala template project, and then cloning it to your computer.
 This is the setup to choose if you want to share your work with other people; for example you might be taking Creative Scala with a remote instructor or you might just (quite rightfully) be proud of your work.
 
 In this setup you first *fork* the Creative Scala template.
 Then you make a clone of *your* fork.
 This alternative setup is described in more detail in the section on GitHub later in this chapter.
-</div>
+@:@
 
-Open a normal command-prompt.
-Click on the Windows icon on the bottom left of the screen.
-In the search box enter "cmd" and run the program it finds.
-In the window that is opened up type
+5. Open a normal command-prompt. Click on the Windows icon on the bottom left of the screen. In the search box enter "cmd" and run the program it finds. In the window that is opened up type
 
-```bash
-cd creative-scala-template
-```
+ ```bash
+ cd creative-scala-template
+ ```
 
-which will change into the directory of the Creative Scala template project we just downloaded.
-Type
+ which will change into the directory of the Creative Scala template project we just downloaded.
+6. Type
 
-```bash
-sbt.bat
-```
+ ```bash
+ sbt
+ ```
 
-to start SBT.
-Within SBT type `console`.
-Finally type
-
-```scala
-Example.image.draw()
-```
-
-and an image of three circles should appear!
+ sbt should start. Within sbt type `run` and an image should appear. It it does you have everything correctly installed!
 
 If you've made it this far you've successfully installed all the software you need for work through Creative Scala.
 
-The final step is to load Atom and use it to open `Example.scala`, which you can find in the directory `src\main\scala`.
+The final step is to load Visual Studio Code and use it to open `Example.scala`, which you can find in `src\main\scala`.
 
 
 ### Linux
 
 Follow the OS X instructions, using your distributions package manager to install software in place of Homebrew.
+
+[coursier]: https://get-coursier.io/docs/cli-installation
+[vs-code]: https://code.visualstudio.com/
+[homebrew]: https://brew.sh/
+[temurin]: