README.md overhaul

[bradenbest]

I overhauled the readme. Be sure to read the commit message.

Aside from re-working the sentences to be slightly less awkward, this fleshes out a lot of the details and adds more examples to further illustrate the points. I even added a couple section (Preface and Troubleshooting) to the installation instructions and re-worked all of that stuff to make it less confusing.

Ignore the first commit (Phase 1 of 2: quick test), and the commit messages for the latter two commits are the same.

If you have any comments, questions or concerns, please share.

[codecov-io]

Codecov Report

Merging #97 into master will not change coverage. The diff coverage is n/a.

@@          Coverage Diff           @@
##           master     #97   +/-   ##
======================================
  Coverage    83.7%   83.7%           
======================================
  Files           8       8           
  Lines         362     362           
======================================
  Hits          303     303           
  Misses         59      59

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update fff9f44...a5cad27. Read the comment docs.

[bradenbest]

I wanted to have it done in one commit, but that sadly didn't work out quite as I had planned. So to make it easier to review, here are the differences:

Main vs commit 1

commit 2 vs commit 3

The only differences between 1 and 2 are that I removed the "markdown testing" stuff and added in $'s to allow freedom to further flesh out comman-line examples (as expressed in the commit message).

Finally, here's what it looks like when rendered

[bradenbest]

It occurs to me just now that I made a minor error in Troubleshooting:

$ sudo ed $(which mal) <<< $'1s/python$/python3\nwq'
28
#!/usr/bin/python3
29
$ head -1 $(which mal)
#!/usr/bin/python3

The 28/29 implies that the file is only 28 bytes long, this is because I used a test file to generate that output.

#!/usr/bin/python
ajhlsgldjg

Obviously not a big deal, but if ed's output bothers you at all, feel free to do this:

$ sudo ed -s $(which mal) <<< $'1s/python$/python3\nwq'
         ^^^
$ head -1 $(which mal)
#!/usr/bin/python3

The -s puts ed in silent mode.