Docs: update content and various tweaks to the markdown

The "Documentation" section of the https://requests.ryanmccue.info/ website is automatically generated from the files in the `docs` folder.

The last time the site was generated was in 2016. Since then a lot has changed in GH Pages and a lot of the [dependencies](https://pages.github.com/versions/) used to generate a site have been updated to newer releases.

This commit makes various tweaks to the markdown for improved rendering on the current GH Pages setup.
While going through the pages, I've also done a cursory review of the content and fixed up information which was extremely outdated or plain incorrect by now.

Includes:
* Use spaces not tabs for indentation in markdown files.
* Fixing up various URLs/links.
* Removal of various uses of ableist language.
* Punctuation fixes.

README.md

@@ -36,7 +36,7 @@ var_dump($request->body);
 
 Requests allows you to send  **HEAD**, **GET**, **POST**, **PUT**, **DELETE**, 
 and **PATCH** HTTP requests. You can add headers, form data, multipart files, 
-and parameters with simple arrays, and access the response data in the same way. 
+and parameters with basic arrays, and access the response data in the same way.
 Requests uses cURL and fsockopen, depending on what your system has available, 
 but abstracts all the nasty stuff out of your way, providing a consistent API.
 

docs/authentication-custom.md

@@ -1,44 +1,44 @@
 Custom Authentication
 =====================
-Custom authentication handlers are designed to be extremely simple to write.
+Custom authentication handlers are designed to be straight-forward to write.
 In order to write a handler, you'll need to implement the `Requests_Auth`
 interface.
 
-An instance of this handler is then passed in by the user via the `auth`
+An instance of this handler can then be passed to Requests via the `auth`
 option, just like for normal authentication.
 
 Let's say we have a HTTP endpoint that checks for the `Hotdog` header and
-authenticates you if said header is set to `Yummy`. (I don't know of any
+authenticates the call if said header is set to `Yummy`. (I don't know of any
 services that do this; perhaps this is a market waiting to be tapped?)
 
 ```php
 class MySoftware_Auth_Hotdog implements Requests_Auth {
-	protected $password;
+    protected $password;
 
-	public function __construct($password) {
-		$this->password = $password;
-	}
+    public function __construct($password) {
+        $this->password = $password;
+    }
 
-	public function register(Requests_Hooks &$hooks) {
-		$hooks->register('requests.before_request', array($this, 'before_request'));
-	}
+    public function register(Requests_Hooks &$hooks) {
+        $hooks->register('requests.before_request', array($this, 'before_request'));
+    }
 
-	public function before_request(&$url, &$headers, &$data, &$type, &$options) {
-		$headers['Hotdog'] = $this->password;
-	}
+    public function before_request(&$url, &$headers, &$data, &$type, &$options) {
+        $headers['Hotdog'] = $this->password;
+    }
 }
 ```
 
-We then use this in our request calls:
+We then use this in our request calls like this:
 
-```
+```php
 $options = array(
-	'auth' => new MySoftware_Auth_Hotdog('yummy')
+    'auth' => new MySoftware_Auth_Hotdog('yummy')
 );
 $response = Requests::get('http://hotdogbin.org/admin', array(), $options);
 ```
 
-(For more information on how to register and use hooks, see the [hooking
-system documentation][hooks])
+For more information on how to register and use hooks, see the [hooking
+system documentation][hooks].
 
-[hooks]: hooks.md
+[hooks]: hooks.md

docs/authentication.md

@@ -4,11 +4,11 @@ Many requests that you make will require authentication of some type. Requests
 includes support out of the box for HTTP Basic authentication, with more
 built-ins coming soon.
 
-Making a Basic authenticated call is ridiculously easy:
+A Basic authenticated call can be made like this:
 
 ```php
 $options = array(
-	'auth' => new Requests_Auth_Basic(array('user', 'password'))
+    'auth' => new Requests_Auth_Basic(array('user', 'password'))
 );
 Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options);
 ```
@@ -18,12 +18,12 @@ and password, you can also just pass in an array as a shorthand:
 
 ```php
 $options = array(
-	'auth' => array('user', 'password')
+    'auth' => array('user', 'password')
 );
 Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options);
 ```
 
-Note that POST/PUT can also take a data parameter, so you also need that
+Note that `POST`/`PUT` requests take a `$data` parameter, so you need to pass that
 before `$options`:
 
 ```php

docs/goals.md

@@ -1,18 +1,18 @@
 Goals
 =====
 
-1. **Simple interface**
+1. **Straight-forward interface**
 
-   Requests is designed to provide a simple, unified interface to making
+   Requests is designed to provide a straight forward, unified interface to making
    requests, regardless of what is available on the system. This means not worrying.
 
 2. **Fully tested code**
 
    Requests strives to have 90%+ code coverage from the unit tests, aiming for
    the ideal 100%. Introducing new features always means introducing new tests
 
-   (Note: some parts of the code are not covered by design. These sections are
-   marked with `@codeCoverageIgnore` tags)
+   Note: some parts of the code are not covered by design. These sections are
+   marked with `@codeCoverageIgnore` tags.
 
 3. **Maximum compatibility**
 

docs/hooks.md

@@ -6,72 +6,74 @@ process along with internal transport hooks.
 Check out the [API documentation for `Requests_Hooks`][requests_hooks] for more
 information on how to use the hook system.
 
+[requests_hooks]: {{ '/api/class-Requests_Hooks.html' | prepend: site.baseurl }}
+
 Available Hooks
 ---------------
 
-* `requests.before_request`
+* **`requests.before_request`**
 
-    Alter the request before it's sent to the transport.
+    Alter the request before it is sent to the transport.
 
     Parameters: `string &$url`, `array &$headers`, `array|string &$data`,
     `string &$type`, `array &$options`
 
-* `requests.before_parse`
+* **`requests.before_parse`**
 
-    Alter the raw HTTP response before parsing
+    Alter the raw HTTP response before parsing.
 
     Parameters: `string &$response`
 
-* `requests.after_request`
+* **`requests.after_request`**
 
-    Alter the response object before it's returned to the user
+    Alter the response object before it is returned to the user.
 
     Parameters: `Requests_Response &$return`
 
-* `curl.before_request`
+* **`curl.before_request`**
 
     Set cURL options before the transport sets any (note that Requests may
-    override these)
+    override these).
 
     Parameters: `cURL resource &$fp`
 
-* `curl.before_send`
+* **`curl.before_send`**
 
-    Set cURL options just before the request is actually sent via `curl_exec`
+    Set cURL options just before the request is actually sent via `curl_exec()`.
 
     Parameters: `cURL resource &$fp`
 
-* `curl.after_request`
+* **`curl.after_request`**
 
-    Alter the raw HTTP response before returning for parsing
+    Alter the raw HTTP response before returning for parsing.
 
     Parameters: `string &$response, array &$info`
 
     `$info` contains the associated array as defined in [curl-getinfo-returnvalues](http://php.net/manual/en/function.curl-getinfo.php#refsect1-function.curl-getinfo-returnvalues)
 
-* `fsockopen.before_request`
+* **`fsockopen.before_request`**
 
-    Run events before the transport does anything
+    Run events before the transport does anything.
 
-* `fsockopen.after_headers`
+* **`fsockopen.after_headers`**
 
-    Add extra headers before the body begins (i.e. before `\r\n\r\n`)
+    Add extra headers before the body begins (i.e. before `\r\n\r\n`).
 
     Parameters: `string &$out`
 
-* `fsockopen.before_send`
+* **`fsockopen.before_send`**
 
-    Add body data before sending the request
+    Add body data before sending the request.
 
     Parameters: `string &$out`
 
-* `fsockopen.after_send`
+* **`fsockopen.after_send`**
 
-   Run events after writing the data to the socket
+   Run events after writing the data to the socket.
 
-* `fsockopen.after_request`
+* **`fsockopen.after_request`**
 
-    Alter the raw HTTP response before returning for parsing
+    Alter the raw HTTP response before returning for parsing.
 
     Parameters: `string &$response, array &$info`
 
@@ -86,7 +88,7 @@ Authentication guide][authentication-custom] instead.
 [authentication-custom]: authentication-custom.md
 
 In order to register your own hooks, you need to instantiate `Requests_hooks`
-and pass this in via the 'hooks' option.
+and pass the object in via the 'hooks' option.
 
 ```php
 $hooks = new Requests_Hooks();

docs/proxy.md

@@ -1,23 +1,23 @@
 Proxy Support
 =============
 
-You can easily make requests through HTTP proxies.
+Making requests through HTTP proxies is fully supported.
 
 To make requests through an open proxy, specify the following options:
 
 ```php
 $options = array(
-	'proxy' => '127.0.0.1:3128'
+    'proxy' => '127.0.0.1:3128'
 );
 Requests::get('http://httpbin.org/ip', array(), $options);
 ```
 
 If your proxy needs you to authenticate, the option will become an array like
-the following:
+in the following example:
 
 ```php
 $options = array(
-	'proxy' => array( '127.0.0.1:3128', 'my_username', 'my_password' )
+    'proxy' => array( '127.0.0.1:3128', 'my_username', 'my_password' )
 );
 Requests::get('http://httpbin.org/ip', array(), $options);
 ```

docs/usage-advanced.md

@@ -47,7 +47,7 @@ accepted by cURL and OpenSSL):
 
 ```php
 $options = array(
-	'verify' => '/path/to/cacert.pem'
+    'verify' => '/path/to/cacert.pem'
 );
 $response = Requests::get('https://httpbin.org/', array(), $options);
 ```
@@ -60,14 +60,11 @@ avoided.
 Requests supports SSL across both cURL and fsockopen in a transparent manner.
 Unlike other PHP HTTP libraries, support for verifying the certificate name is
 built-in; that is, a request for `https://github.com/` will actually verify the
-certificate's name even with the fsockopen transport. This makes Requests the
-first and currently only PHP HTTP library that supports full SSL verification.
+certificate's name even with the fsockopen transport. Requests was the
+first PHP HTTP library to fully support SSL verification.
 
-(Note that WordPress now also supports this verification, thanks to efforts by
-the Requests development team.)
-
-(See also the [related PHP][php-bug-47030] and [OpenSSL-related][php-bug-55820]
-bugs in PHP for more information on Subject Alternate Name field.)
+See also the [related PHP][php-bug-47030] and [OpenSSL-related][php-bug-55820]
+bugs in PHP for more information on Subject Alternate Name field.
 
 [Mozilla certificate authority list]: http://www.mozilla.org/projects/security/certs/
 [php-bug-47030]: https://bugs.php.net/bug.php?id=47030