Breathe some life into the readme

README.md

@@ -1,20 +1,27 @@
 # <img src="https://i.imgur.com/nPCcxts.png" height=25> MCStatus
+
 [![discord chat](https://img.shields.io/discord/936788458939224094.svg?logo=Discord)](https://discord.gg/C2wX7zduxC)
 ![supported python versions](https://img.shields.io/pypi/pyversions/mcstatus.svg)
 [![current PyPI version](https://img.shields.io/pypi/v/mcstatus.svg)](https://pypi.org/project/mcstatus/)
 [![Validation](https://github.com/py-mine/mcstatus/actions/workflows/validation.yml/badge.svg)](https://github.com/py-mine/mcstatus/actions/workflows/validation.yml)
 [![Tox test](https://github.com/py-mine/mcstatus/actions/workflows/tox-test.yml/badge.svg)](https://github.com/py-mine/mcstatus/actions/workflows/tox-test.yml)
 
-Mcstatus provides an easy way to query Minecraft servers for any information they can expose.  
-It includes three modes of access (`query`, `status` and `ping`), the differences of which are listed below in usage.
+Mcstatus provides an API and command line script to fetch publicly available data from Minecraft servers. Specifically, mcstatus retrieves data by using these protocols: [Server List Ping](https://wiki.vg/Server_List_Ping) and [Query](https://wiki.vg/Query). Because of mcstatus, you do not need to fully understand those protocols and can instead skip straight to retrieving minecraft server data quickly in your own programs.
 
-## Usage
+## Installation
+
+Mcstatus is available on [PyPI](https://pypi.org/project/mcstatus/), and can be installed trivially with:
+
+```bash
+python3 -m pip install mcstatus
+```
 
-We provide both an API which you can use in your projects, and a command line script, to quickly query a server.
+## Usage
 
 ### Python API
 
-Java Edition
+#### Java Edition
+
 ```python
 from mcstatus import JavaServer
 
@@ -23,21 +30,25 @@ from mcstatus import JavaServer
 server = JavaServer.lookup("example.org:1234")
 
 # 'status' is supported by all Minecraft servers that are version 1.7 or higher.
+# Don't expect the player list to always be complete, because many servers run
+# plugins that hide this information or limit the number of players returned or even
+# alter this list to contain fake players for purposes of having a custom message here.
 status = server.status()
-print(f"The server has {status.players.online} players and replied in {status.latency} ms")
+print(f"The server has {status.players.online} player(s) online and replied in {status.latency} ms")
 
 # 'ping' is supported by all Minecraft servers that are version 1.7 or higher.
 # It is included in a 'status' call, but is also exposed separate if you do not require the additional info.
 latency = server.ping()
 print(f"The server replied in {latency} ms")
 
-# 'query' has to be enabled in a servers' server.properties file!
+# 'query' has to be enabled in a server's server.properties file!
 # It may give more information than a ping, such as a full player list or mod information.
 query = server.query()
 print(f"The server has the following players online: {', '.join(query.players.names)}")
 ```
 
-Bedrock Edition
+#### Bedrock Edition
+
 ```python
 from mcstatus import BedrockServer
 
@@ -53,55 +64,8 @@ print(f"The server has {status.players_online} players online and replied in {st
 
 ### Command Line Interface
 
-At present time, this only works with Java servers, Bedrock is not yet supported.
-```
-$ mcstatus
-Usage: mcstatus [OPTIONS] ADDRESS COMMAND [ARGS]...
-
-  mcstatus provides an easy way to query Minecraft servers for any
-  information they can expose. It provides three modes of access: query,
-  status, and ping.
-
-  Examples:
-
-  $ mcstatus example.org ping
-  21.120ms
-
-  $ mcstatus example.org:1234 ping
-  159.903ms
-
-  $ mcstatus example.org status
-  version: v1.8.8 (protocol 47)
-  description: "A Minecraft Server"
-  players: 1/20 ['Dinnerbone (61699b2e-d327-4a01-9f1e-0ea8c3f06bc6)']
-
-  $ mcstatus example.org query
-  host: 93.148.216.34:25565
-  software: v1.8.8 vanilla
-  plugins: []
-  motd: "A Minecraft Server"
-  players: 1/20 ['Dinnerbone (61699b2e-d327-4a01-9f1e-0ea8c3f06bc6)']
-
-Options:
-  -h, --help  Show this message and exit.
-
-Commands:
-  json    combination of several other commands with json formatting
-  ping    prints server latency
-  query   detailed server information
-  status  basic server information
-```
-
-## Installation
-
-Mcstatus is available on [PyPI](https://pypi.org/project/mcstatus/), and can be installed trivially with:
-
-```bash
-python3 -m pip install mcstatus
-```
-
-Alternatively, just clone this repo!
+This only works with Java servers; Bedrock is not yet supported. Use `mcstatus -h` to see helpful information on how to use this script.
 
 ## License
 
-Mcstatus is licensed under the Apache 2.0 license.
+Mcstatus is licensed under the Apache 2.0 license. See LICENSE for full text.