Merge pull request #220 from crytic/dev-readme

README improvements

Author: elopez

README.md

@@ -1,7 +1,9 @@
 # solc-select
+
 A tool to quickly switch between Solidity compiler versions.
 
 The tool is split into two CLI utilities:
+
 - `solc-select`: manages installing and setting different `solc` compiler versions
 - `solc`: wrapper around `solc` which picks the right version according to what was set via `solc-select`
 
@@ -12,26 +14,27 @@ The versioned binaries are stored in `~/.solc-select/artifacts/`.
 
 ## Quickstart
 
-```
+```bash
 pip3 install solc-select
 ```
 
-To automatically install and use a version, run `solc-select use <version> --always-install`. 
+To automatically install and use a version, run `solc-select use <version> --always-install`.
 
 ### Running on ARM (Mac M1/M2)
 
 `solc` requires Rosetta to be installed. See the FAQ on [how to install Rosetta](#oserror-errno-86-bad-cpu-type-in-executable).
 
 ## Usage
 
-By default, `solc-select` will install the most recent available Solidity file for your version. This will automatically be done when you run `solc` for the first time. 
+By default, `solc-select` will install the most recent available Solidity file for your version. This will automatically be done when you run `solc` for the first time.
 
-```bash 
-solc 
+```bash
+solc
 ```
 
 The global version of `solc` will automatically be set to to the latest version. You can reset this with the `solc-select use <version>` command:
-```
+
+```shell
 $ solc --version
 solc, the solidity compiler commandline interface
 Version: 0.5.2+commit.1df8f40c.Linux.g++
@@ -41,8 +44,10 @@ $ solc --version
 solc, the solidity compiler commandline interface
 Version: 0.4.24+commit.e67f0147.Linux.g++
 ```
+
 Use `SOLC_VERSION` environment variable to override the global version:
-```
+
+```shell
 $ solc --version
 solc, the solidity compiler commandline interface
 Version: 0.4.24+commit.e67f0147.Linux.g++
@@ -51,16 +56,17 @@ solc, the solidity compiler commandline interface
 Version: 0.5.2+commit.1df8f40c.Linux.g++
 ```
 
-By default, solc-select will halt if you try to use a version that you do not have installed already. Use the `--always-install` flags to bypass this. 
+By default, solc-select will halt if you try to use a version that you do not have installed already. Use the `--always-install` flags to bypass this.
 
-```bash 
-solc-select use 0.8.1 --always-install
+```shell
+$ solc-select use 0.8.1 --always-install
 Installing '0.8.1'...
 Version '0.8.1' installed.
 ```
 
 You can list all available versions with `solc-select install`:
-```
+
+```shell
 $ solc-select install
 Available versions to install:
 0.3.6
@@ -98,55 +104,54 @@ If it is not installed, it can be installed with the command
 
 Uninstall other installations of solc on your machine. `solc-select` re-installs solc binaries for your operating system and acts as a wrapper for solc. With duplicate solc installations, this may result in your `solc` version not being up to date.
 
-### "Unsupported Platform" on Windows 
+### "Unsupported Platform" on Windows
 
-The solc-select version that supports Windows is currently in beta. Uninstall `solc-select` through `pip3 uninstall solc-select` and run 
+You might be using an old version of `solc-select` or Python if you are seeing this error message. The current stable release supports Windows; try upgrading your `solc-select` installation with the following command.
 
-```bash 
-pip install solc-select==1.0.0b1
-```
-
-Alternatively, for the most up-to-date version, clone this repository and run 
-```bash 
-pip install . --user
+```bash
+pip install --upgrade solc-select
 ```
 
 ## Known Issues
 
 ### `SSL: CERTIFICATE_VERIFY_FAILED` on running `solc-select` commands [investigation ongoing]
 
-**OS X**
+**OS X**: Python distributions on OS X has no certificates and cannot validate SSL connections, a breaking change introduced in Python 3.6. See [StackOverflow](https://stackoverflow.com/a/42334357) post for additional details.
+
+The following commands may resolve the issue; adjust the Python version to the one installed on your system:
+
 ```bash
 pip3 install certifi
 /Applications/Python\ 3.8/Install\ Certificates.command
 ```
 
-Python distributions on OS X has no certificates and cannot validate SSL connections, a breaking change introduced in Python 3.6. See [StackOverflow](https://stackoverflow.com/a/42334357) post for additional details.
-
 ### `Connection refused` [investigation ongoing]
 
+Our `0.2.1` version of `solc-select` pulls older Linux binaries from [crytic/solc](https://github.com/crytic/solc) which seems to have introduced unexpected behavior in certain instances. Apparently, [certain ISPs such as Jio](https://github.com/crytic/solc-select/issues/205#issuecomment-1825171056) may be blocking access to certain GitHub domains. If possible, try using a different Internet provider to see if it resolves the problem.
+
+Alternatively, try downgrading to `solc-select version 0.2.0`.
+
 ```bash
-pip3 uninstall solc-select 
+pip3 uninstall solc-select
 pip3 install solc-select==0.2.0
-solc-select install 
+solc-select install
 ```
 
-Try downgrading to `solc-select version 0.2.0`. 
-
-Our `0.2.1` version of `solc-select` pulls older Linux binaries from [crytic/solc](https://github.com/crytic/solc) which seems to have introduced unexpected behavior in certain instances.
-
 ### `solc-select` version changes, but `solc --version does not match`
 
-Users seem to be experiencing situations in which the following command is successful: 
-```
-solc-select use <version> 
+Users seem to be experiencing situations in which the following command is successful:
+
+```bash
+solc-select use <version>
 ```
+
 However, when running the following command, it points to an older version of Solidity.
-```
+
+```bash
 solc --version
 ```
 
-`solc-select` is intended to work with custom binaries. This means that Solidity installed through other means (i.e: `brew install solidity`) will _not_ work!. 
+`solc-select` is intended to work with custom binaries. This means that Solidity installed through other means (i.e: `brew install solidity`) will _not_ work!.
 
 Uninstall other versions Solidity from your computer.