Merge pull request #277 from alvinj/aa-docs-review

Initial edits to Overview and Commands

Author: romanowski

website/docs/commands/basics.md

@@ -3,36 +3,40 @@ title: Basics
 sidebar_position: 3
 ---
 
-Scala CLI is a command line tool that executes a given command on provided inputs with given [configuration](../guides/configuration.md) to produce a result. Most important commands are:
+Scala CLI is a command line tool that executes a given command on the inputs it’s provided with a given [configuration](../guides/configuration.md) to produce a result.
 
-  - [compile](./compile.md) to compile you code (this exclude tests)
-  - [run](./run.md) - to run your code using provided arguments (also used when no other command is provided)
-  - [test](./test.md) - to compile and run tests defined in your code
-  - [package](./package.md) - to package your code into a jar or other format
-  - [repl](./repl.md) / [console](./repl.md) - to run interactive Scala shell
-  - [fmt](./fmt.md) - to format your code
+The most important commands are:
 
-If Scala CLI is run without any command provided, it will default to the `run` command, so `scala-cli a.scala` will run your `a.scala` file.
+  - [compile](./compile.md) compiles your code (excluding tests)
+  - [run](./run.md) runs your code using the provided arguments (it’s also used when no other command is provided)
+  - [test](./test.md) compiles and runs the tests defined in your code
+  - [package](./package.md) packages your code into a jar or other format
+  - [repl](./repl.md) / [console](./repl.md) runs the interactive Scala shell
+  - [fmt](./fmt.md) formats your code
+
+When Scala CLI is run without any commands, it defaults to the `run` command, so <br/>`scala-cli a.scala` runs your `a.scala` file.
 
 ## Input formats
 
 The `scala-cli` CLI commands accept input in a number of ways, most notably:
+
 - as source files
-- as one or several directories, containing sources
+- as one or several directories that contain source files
 - as URLs, pointing to sources
-- by piping or process substitution source code directly
+- by processing source code via piping or process substitution
 
-Lastly, note that all these input formats can used alongside each other.
+Note that all of these input formats can used alongside each other.
 
 ## Source files
 
-Scala CLI accepts following kinds of source:
- - `.scala` files containing Scala code
- - `.sc` files, containing Scala scripts (see more in [Scripts guide](../guides/scripts.md))
- - `.java` files containing Java code
+Scala CLI accepts the following types of source code:
 
-This is the simplest input format. Just write a source file, and pass it to
-`scala-cli` to run it:
+- `.scala` files, containing Scala code
+- `.sc` files, containing Scala scripts (see more in [Scripts guide](../guides/scripts.md))
+- `.java` files, containing Java code
+
+This example shows the simplest input format.
+First, create a source file:
 
 ```scala title=Hello.scala
 object Hello {
@@ -41,13 +45,14 @@ object Hello {
 }
 ```
 
-Run it with
+The run it by passing it to `scala-cli`:
+
 ```bash
 scala-cli Hello.scala
 # Hello from Scala
 ```
 
-You can also split your code in multiple files, and pass all of them to `scala-cli` :
+You can also split your code into multiple files:
 
 ```scala title=Messages.scala
 object Messages {
@@ -62,30 +67,33 @@ object Hello {
 }
 ```
 
-Run them with
+and the run them with `scala-cli`:
+
 ```bash
 scala-cli Hello.scala Messages.scala
 # Hello from Scala
 ```
 
 :::note
-Scala CLI compiles together only the provided inputs.
-:::
-
-If we provide only one of the files above:
+Scala CLI compiles only the provided inputs.
+For example, if we provide only one of the files above:
 
 ```bash fail
 scala-cli Hello.scala
 ```
 
-compilation will fail even though a moment ago files compiled together without any problem.
+compilation will fail. `scala-cli` compiles only the files it’s given.
+:::
+
+While this is *very* convenient for projects with just a few files, passing many files this way can be cumbersome and error-prone.
+For larger projects, directories can help.
 
-Passing many files this way can be cumbersome and error-prone. Directories can help.
 
 ## Directories
 
-`scala-cli` accepts whole directories as input. This is convenient when you have many
-`.scala` files and passing them all one-by-one on the command line isn't practical:
+`scala-cli` accepts whole directories as input.
+
+This is convenient when you have many `.scala` files, and passing them all one-by-one on the command line isn't practical:
 
 ```scala title=my-app/Messages.scala
 object Messages {
@@ -100,30 +108,32 @@ object Hello {
 }
 ```
 
-Run them with
+For this case, run all the source code files in `my-app` by supplying the directory name:
+
 ```bash
 scala-cli my-app
 # Hello from Scala
 ```
 
-From our experience, `scala-cli .` is the most used command (it will compile and run all sources from within current directory.)
+In our experience, `scala-cli .` is the most used command; it compiles and runs all sources in the current directory.
 
 :::note
-Scala CLI will process all files within the directories and all its subdirectories.
-
-Scala CLI ignores all subdirectories that starts with `.` like `.scala` or `.vscode`. (But such directories can be explicitly provided as inputs.)
+Scala CLI process all files within the specified directories and all of its subdirectories.
 
+Scala CLI ignores all subdirectories that start with `.` like `.scala` or `.vscode`.
+Such directories needs to be explicitly provided as inputs.
 :::
+
 ## URLs
 
 :::warning
-Running unverified code from the internet may be really dangerous since Scala CLI does not provide any sandboxing at this moment.
+Running unverified code from the internet can be very handy for *trusted* sources, but it can also be really dangerous, since Scala CLI does not provide any sandboxing at this moment.
 
 Make sure that you trust the code that you are about to run.
 :::
 
 `scala-cli` accepts input via URLs pointing at `.scala` files.
-It will download their content, and run them.
+It downloads their content, and runs them:
 
 ```bash
 scala-cli https://gist.github.com/alexarchambault/f972d941bc4a502d70267cfbbc4d6343/raw/2691c01984c9249936a625a42e29a822a357b0f6/Test.scala
@@ -132,8 +142,8 @@ scala-cli https://gist.github.com/alexarchambault/f972d941bc4a502d70267cfbbc4d63
 
 ### GitHub Gist
 
-`scala-cli` accepts input via the URLs of GitHub gists.
-It wil download the gists' zip archives, cache their content, and run them.
+`scala-cli` accepts input via Github Gist’s urls.
+It downloads the gist zip archive and runs it:
 
 ```bash
 scala-cli https://gist.github.com/alexarchambault/7b4ec20c4033690dd750ffd601e540ec
@@ -142,15 +152,17 @@ scala-cli https://gist.github.com/alexarchambault/7b4ec20c4033690dd750ffd601e540
 
 ## Piping
 
-You can just pipe Scala code to `scala-cli` for execution:
+You can also pipe Scala code to `scala-cli` for execution:
+
 ```bash
 echo 'println("Hello")' | scala-cli -
 # Hello
 ```
 
 ## Process substitution
 
-`scala-cli` accepts input via shell process substitution:
+Lastly, `scala-cli` also accepts input via shell process substitution:
+
 ```bash
 scala-cli <(echo 'println("Hello")')
 # Hello

website/docs/commands/clean.md

@@ -3,4 +3,4 @@ title: Clean
 sidebar_position: 16
 ---
 
-Deletes all generated files that are a part of your working directory, including the `.scala` directory.
+The `clean` command deletes all of the files that are generated by `scala-cli`. This including the `.scala` directory where Scala CLI generated its output and stores its caches.

website/docs/commands/compile.md

@@ -3,7 +3,8 @@ title: Compile
 sidebar_position: 5
 ---
 
-Scala CLI can compile your code with its `compile` command:
+Scala CLI compiles your code with its `compile` command:
+
 ```bash
 cat Hello.scala
 # object Hello {
@@ -13,17 +14,18 @@ cat Hello.scala
 scala-cli compile Hello.scala
 ```
 
-Note that most commands of the Scala CLI will automatically compile your code if necessary.
-The `compile` command is useful if you'd like to simply check that your code compiles,
-or see compilation warnings, without running it or packaging it for example.
+Note that most Scala CLI commands automatically compile your code, if necessary.
+The `compile` command is useful if you'd like to check that your code compiles,
+or know of compilation warnings, without running it or packaging it.
 
-We list below some options the `compile` command accepts. For a full list of options,
-run `scala compile --help`, or check the options linked in the
+The most common `compile` options are shown below. 
+For a full list of options, run `scala compile --help`, or check the options linked in the
 [reference documentation](../reference/commands.md#compile).
 
 ## Watch mode
 
-`--watch` makes `scala-cli` watch your code for changes, and re-compiles it upon change:
+`--watch` makes `scala-cli` watch your code for changes, and re-compiles it upon any change:
+
 ```bash
 scala-cli compile --watch Hello.scala
 # Compiling project-cef76d561e (1 Scala source)
@@ -42,10 +44,11 @@ Scala CLI uses the latest stable version of Scala by default (`3.1.0` when this
 scala-cli compile --scala 2.13.6 Hello.scala
 ```
 
-`scala-cli` should work with all major `2.12.x`, `2.13.x`, and `3.x` Scala versions.
+`scala-cli` works with all major `2.12.x`, `2.13.x`, and `3.x` Scala versions.
 
-`--scala` also accepts "short" Scala versions, such as `2.12`, `2`, or `3`. In that
+`--scala` also accepts "short" Scala versions, such as `2.12`, `2`, or `3`. In this
 case, it picks the highest corresponding stable Scala version:
+
 ```bash ignore
 scala-cli compile --scala 2.12 Hello.scala
 scala-cli compile --scala 2 Hello.scala
@@ -54,26 +57,28 @@ scala-cli compile --scala 3 Hello.scala
 
 ## Dependencies
 
-You can add dependencies on the command-line, via `--dependency`:
+You can add dependencies on the command-line with `--dependency`:
+
 ```bash
 scala-cli compile Hello.scala \
   --dependency org.scala-lang.modules::scala-parallel-collections:1.0.4
 ```
 
-Note that `--dependency` is only meant as a convenience. You should favour
-adding dependencies in the sources themselves via [using directives](../guides/configuration.md#special-imports).
+Note that `--dependency` is only meant as a convenience. You should favor
+adding dependencies in the source files themselves via [`using` directives](../guides/configuration.md#special-imports).
+
+You can also add simple JAR files — those that don’t have transitive dependencies — as dependencies, with `--jar`:
 
-You can also add simple JAR files as dependencies, with `--jar`:
 ```bash
 scala-cli compile Hello.scala --jar /path/to/library.jar
 ```
 
-We have a guide dedicated to [Dependency management](../guides/dependencies.md)
+See the [Dependency management](../guides/dependencies.md) guide for more details.
 
 ## Scala compiler options
 
-Most [Scala compiler options](https://docs.scala-lang.org/overviews/compiler-options) can be passed as
-is to `scala-cli` :
+Most [Scala compiler options](https://docs.scala-lang.org/overviews/compiler-options) can be passed as-is to `scala-cli`:
+
 ```bash
 scala-cli compile Hello.scala -Xlint:infer-any
 # Compiling project_b729aa2200-cef76d561e (1 Scala source)
@@ -83,7 +88,8 @@ scala-cli compile Hello.scala -Xlint:infer-any
 # Compiled 'project_b729aa2200-cef76d561e'
 ```
 
-In more detail, all options starting with
+All `scala-cli` options that start with:
+
 - `-g`
 - `-language`
 - `-opt`
@@ -96,15 +102,16 @@ In more detail, all options starting with
 
 are assumed to be Scala compiler options.
 
-Compiler options can also be passed with `-O`:
+Scala compiler options can also be passed with `-O`:
+
 ```bash
 scala-cli compile Hello.scala -O -deprecation -O -Xlint:infer-any
 # [warn] ./Hello.scala:3:7: method x in class Some is deprecated (since 2.12.0): Use .value instead.
 # [warn]   opt.x
 # [warn]       ^
 ```
 
-`-O` accepts both options with the prefixes above and those without such a prefix.
+`-O` accepts both options with the prefixes shown above, and those without such a prefix.
 
 ## Scala compiler plugins
 Use `--compiler-plugin` to add compiler plugin dependencies:
@@ -116,18 +123,18 @@ scala-cli compile Main.scala --compiler-plugin org.typelevel:::kind-projector:0.
 
 ## Printing a class path
 
-`--class-path` makes `scala compile` print a class path that can be passed to other tools:
+`--class-path` makes `scala-cli compile` print a class path:
 ```bash
 scala-cli compile --class-path Hello.scala
 # /work/.scala/project-cef76d561e/classes:~/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/org/scala-lang/scala-library/2.12.14/scala-library-2.12.14.jar:~/Library/Caches/ScalaCli/local-repo/0.1.0/org.virtuslab.scala-cli/runner_2.12/0.0.1-SNAPSHOT/jars/runner_2.12.jar:~/Library/Caches/ScalaCli/local-repo/0.1.0/org.virtuslab.scala-cli/stubs/0.0.1-SNAPSHOT/jars/stubs.jar
 ```
 
-You can pass this class path to `java -cp` for example:
+This is handy when working with other tools.
+For example, you can pass this class path to `java -cp`:
 ```bash
 java -cp "$(scala compile --class-path Hello.scala)" Hello
 # Hello
 ```
 
-Note that you should favour the [`run`](./run.md) command to run your code, rather than running `java -cp`.
-The class path obtained this way is meant for scenarios where `scala-cli` doesn't offer a more
-convenient option.
+Note that you should favor the [`run`](./run.md) command to run your code, rather than running `java -cp`.
+The class path obtained this way is only meant for scenarios where `scala-cli` doesn't offer a more convenient option.

website/docs/commands/fmt.md

@@ -9,28 +9,30 @@ Scala-cli supports formatting your code using [Scalafmt](https://scalameta.org/s
 scala-cli fmt
 ```
 
-Under the hood scala-cli will download and run Scalafmt over your code.
+Under the hood, `scala-cli` downloads and runs Scalafmt on your code.
 
-If you are working on setting up a CI, scala-cli also has you covered.
+If you’re setting up a continuous integration (CI) server, `scala-cli` also has you covered.
 You can check formatting correctness using a `--check` flag:
 
 ```bash
 scala-cli fmt --check
 ```
 
-### Dialects
+### Dialects 
+
 Scala-cli also supports dialects that are passed to the formatter.
-This value will only be used if there is no `.scalafmt.conf` file. If that file exists, then all configuration should be placed there.
-For a list of all possible values you may want to consult the [official documentation](https://scalameta.org/scalafmt/docs/configuration.html#scala-dialects)
+This value is only used if there is no `.scalafmt.conf` file.
+However, if it exists, then all configuration should be placed there.
+For a list of all possible values, consult the [official Scala Dialects documentation](https://scalameta.org/scalafmt/docs/configuration.html#scala-dialects):
 
 ```bash
 scala-cli fmt --dialect scala212
 ```
 
 ### Current limitations
-Right now scala-cli doesn't read the `.scalafmt.conf` files,
-therefore in some scenarios versions of those two may be mismatched.
-It is possible to set the version manually if you encounter any issues:
+
+At this time, `scala-cli` doesn't read a `scalafmt` version from `.scalafmt.conf` files.
+Therefore, in some scenarios, wrong version may be used. In such situations,  it is possible to set the version manually if you encounter any issues:
 
 ```bash
 scala-cli fmt --scalafmt-tag v3.0.3