README style updates.

* Try to keep text within 80 columns.
* Use better markdown header names.
* Move markdown link URLs to the bottom.
* Remove duplicate markdown link URLs.
* Remove note about manually formatting GHSA sync'ed advisory PRs, since
  the GHSA sync script has been improved since then.
* Capitalize YAML.
* Other grammatical changes.

Author: postmodern

README.md

@@ -1,12 +1,15 @@
 # Ruby Advisory Database
 
-The Ruby Advisory Database is a community effort to compile all security advisories that are relevant to Ruby libraries.
+The Ruby Advisory Database is a community effort to compile all security
+advisories that are relevant to Ruby libraries.
 
-You can check your own Gemfile.locks against this database by using [bundler-audit](https://github.com/rubysec/bundler-audit).
+You can check your own Gemfile.locks against this database by using
+[bundler-audit].
 
-## Support Ruby security!
+## Support Ruby Security!
 
-Do you know about a vulnerability that isn't listed in this database? Open an issue or submit a PR.
+Do you know about a vulnerability that isn't listed in this database? Open an
+issue or submit a PR.
 
 ## Directory Structure
 
@@ -43,7 +46,7 @@ Within each directory are one or more advisory files for the Ruby
 implementation. These advisory files are named using the advisories' [CVE]
 or [GHSA] ID.
 
-## Format
+## Examples
 
 Each advisory file contains the advisory information in [YAML] format.
 Here are some example advisories:
@@ -112,7 +115,7 @@ patched_versions:
   - '>= 3.1.2'
 ```
 
-## Schema
+## YAML Schema
 
 ### `gems`
 
@@ -158,55 +161,50 @@ patched_versions:
 * `related` \[Hash\<Array\<String\>\>\] (optional): Sometimes an advisory references many urls and other identifiers. Supported keys: `cve`, `ghsa`, `osvdb`, and `url`
 * `notes` \[String\] (optional): Internal notes regarding the vulnerability's inclusion in this database.
 
-[CVSSv2]: https://www.first.org/cvss/v2/guide
-[CVSSv3]: https://www.first.org/cvss/v3.1/user-guide
-[CVSSv4]: https://www.first.org/cvss/v4.0/user-guide
-
-### Tests
+## Tests
 
 Prior to submitting a pull request, run the tests:
 
-```
+```shell
 bundle install
 bundle exec rspec
 ```
 
-### GitHub Advisory Sync
+## GitHub Advisory Sync
 
-There is a script that will create initial yaml files for RubyGem advisories which
-are in the [GitHub Security Advisory API](https://developer.github.com/v4/object/securityadvisory/),
-but are not already in this dataset.  This script can be periodically run to ensure
-this repo has all the data that is present in the GitHub Advisory data.
+There is a script that will create initial YAML files for RubyGem advisories
+which are in the [GitHub Security Advisory API], but are not already in this
+dataset. This script can be periodically run to ensure this repo has all the
+data that is present in the GitHub Advisory data.
 
 The GitHub Advisory API requires a token to access it.
-- It can be a completely scopeless token (recommended); it does not require any permissions at all.
-- Get yours at https://github.com/settings/tokens
 
-To run the GitHub Advisory sync to retrieve all advisories, start by executing the rake task:
+* It can be a completely scope-less token (recommended); it does not require any
+  permissions at all.
+* Get yours at: https://github.com/settings/tokens
 
-```
-GH_API_TOKEN=<your GitHub API Token> bundle exec rake sync_github_advisories
+To run the GitHub Advisory sync to retrieve all advisories, start by executing
+the rake task:
+
+```shell
+GH_API_TOKEN="your GitHub API Token" bundle exec rake sync_github_advisories
 ```
 
 Or, to only retrieve advisories for a single gem:
 
+```shell
+GH_API_TOKEN="your GitHub API Token" bundle exec rake sync_github_advisories[gem_name]
 ```
-GH_API_TOKEN=<your GitHub API Token> bundle exec rake sync_github_advisories[gem_name]
-```
-
-- The rake task will write yaml files for any missing advisories.
-- Those files must be further edited.
-  - Fill in `cvss_v3` field by following the CVE link and getting it from page
-  - Fill in `cvss_v4` field by following the CVE link and getting it from page
-  - Fill in `patched_versions` field, using the comments at the bottom of the file
-  - Fill in `unaffected_versions`, optional, if there are unaffected_versions
-  - delete the GitHub data at the bottom of the yaml file
-  - double check all the data, commit it, and make a PR
-    - *The GitHub Advisory data is structured opposite of RubySec unfortunately:
-       GitHub identifies version range which are vulnerable; RubySec identifies
-      version ranges which are not vulnerable.  This is why some manual
-      work to translate is needed.*
 
+* The rake task will write YAML files for any missing advisories.
+* Those files must be further edited.
+  * Fill in `cvss_v3` field by following the CVE link and getting it from page.
+  * Fill in `cvss_v4` field by following the CVE link and getting it from page.
+  * Fill in `patched_versions` field, using the comments at the bottom of the
+    YAML file.
+  * Optionally fill in `unaffected_versions`.
+  * Delete the GitHub data at the bottom of the YAML file.
+  * Double check all the data, commit it, and make a PR.
 
 ## Credits
 
@@ -216,9 +214,11 @@ This database also includes data from the [Open Sourced Vulnerability Database][
 developed by the Open Security Foundation (OSF) and its contributors.
 
 [rubygems.org]: https://rubygems.org/
+[bundler-audit]: https://github.com/rubysec/bundler-audit
 [CVE]: https://cve.mitre.org/
 [OSVDB]: https://en.wikipedia.org/wiki/Open_Source_Vulnerability_Database
 [GHSA]: https://help.github.com/en/articles/about-maintainer-security-advisories
+[GitHub Security Advisory API]: https://developer.github.com/v4/object/securityadvisory/
 [CVSSv2]: https://www.first.org/cvss/v2/guide
 [CVSSv3]: https://www.first.org/cvss/v3.1/user-guide
 [CVSSv4]: https://www.first.org/cvss/v4.0/user-guide