Revisit command documentation

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

README.markdown

@@ -67,11 +67,6 @@ documentation:
 - [Bundling](./docs/bundle.markdown)
 - [Framing](./docs/frame.markdown)
 
-The following global options apply to all commands:
-
-- `--verbose / -v`: Enable verbose output
-- `--resolve / -r`: Import the given JSON Schema into the resolution context
-
 Coming Soon
 -----------
 

docs/bundle.markdown

@@ -2,21 +2,82 @@ Bundling
 ========
 
 ```sh
-jsonschema bundle <path/to/schema.json>
+jsonschema bundle <schema.json> [--http/-h] [--verbose/-v] [--resolve/-r <schema.json> ...]
 ```
 
-A schema may contain references to remote schemas located in other files or
-even shared over the Internet. JSON Schema supports a standardized process,
-referred to as
+A schema may contain references to remote schemas outside the scope of the
+given schema. These remote schemas may live in other files, or may be server by
+others over the Internet. JSON Schema supports a standardized process, referred
+to as
 [bundling](https://json-schema.org/blog/posts/bundling-json-schema-compound-documents),
-to resolve remote references in advance and inline them into the given schema.
-The JSON Schema CLI supports this functionality through the `bundle` command.
+to resolve remote references in advance and inline them into the given schema
+for local consumption or further distribution.  The JSON Schema CLI supports
+this functionality through the `bundle` command.
 
 Examples
 --------
 
-### Bundle a JSON Schema preloading another one
+For example, consider the following schema that references a
+`https://example.com/string` remote schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "https://example.com/string"
+}
+```
+
+The referenced schema is defined in a `string.json` file that looks like this:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/string",
+  "type": "string"
+}
+```
+
+We can bundle the former schema by registering the latter schema into the
+resolution context using the `--resolve / -r` option as follows:
+
+```sh
+jsonschema bundle schema.json --resolve string.json
+```
+
+The resulting schema, which will be printed to standard output, would look like
+this:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "https://example.com/string",
+  "$defs": {
+    "https://example.com/string": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "$id": "https://example.com/string",
+      "type": "string"
+    }
+  }
+}
+```
+
+### Bundle a JSON Schema importing a single local schema
 
 ```sh
 jsonschema bundle path/to/my/schema.json --resolve path/to/external.json
 ```
+
+### Bundle a JSON Schema importing multiple local schemas
+
+```sh
+jsonschema bundle path/to/my/schema.json \
+  --resolve path/to/one.json \
+  --resolve path/to/two.json \
+  --resolve path/to/three.json
+```
+
+### Bundle a JSON Schema while enabling HTTP resolution
+
+```sh
+jsonschema bundle path/to/my/schema.json --http
+```

docs/format.markdown

@@ -2,7 +2,7 @@ Formatting
 ==========
 
 ```sh
-jsonschema fmt [schemas-or-directories...] [--check|-c]
+jsonschema fmt [schemas-or-directories...] [--check|-c] [--verbose/-v]
 ```
 
 Schemas are code. As such, they are expected follow consistent stylistic

docs/frame.markdown

@@ -2,7 +2,7 @@ Framing
 =======
 
 ```sh
-jsonschema frame <path/to/schema.json>
+jsonschema frame <schema.json> [--verbose/-v]
 ```
 
 To evaluate a schema, an implementation will first scan it to determine the
@@ -16,7 +16,7 @@ is often useful for debugging purposes.
 Examples
 --------
 
-For example, consider the following schema with a local reference:
+For example, consider the following schema that includes a local reference:
 
 ```json
 {

docs/lint.markdown

@@ -2,18 +2,47 @@ Linting
 =======
 
 ```sh
-jsonschema lint [schemas-or-directories...] [--fix|-f]
+jsonschema lint [schemas-or-directories...] [--fix|-f] [--verbose/-v]
 ```
 
 JSON Schema is a surprisingly expressive schema language. Like with traditional
-programming languages, writing efficient and maintainable schemas take
-experience, and there are lots of ways of doing it wrong. To help with this,
-the JSON Schema CLI provides a `lint` command that can check your schemas
-against various common anti-patterns and automatically fix many of them.
+programming languages, writing efficient and maintainable schemas takes
+experience, and there are lots of common pitfalls. Just like popular linters
+like [ESLint](https://eslint.org),
+[ClangTidy](https://clang.llvm.org/extra/clang-tidy/), and
+[PyLint](https://www.pylint.org), the JSON Schema CLI provides a `lint` command
+that can check your schemas against various common anti-patterns and
+automatically fix many of them.
 
 Examples
 --------
 
+For example, consider the following schema that asserts that the JSON instance
+is the string `foo`:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "enum": [ "foo" ]
+}
+```
+
+While this schema is technically correct, the JSON Schema 2020-12 dialect has a
+[`const`](https://www.learnjsonschema.com/2020-12/validation/const/) keyword
+that better expresses the intention of matching a single possible value.
+
+Running the JSON Schema CLI linter against the previous schema will produce the
+following output:
+
+```sh
+$ jsonschema lint schema.json
+schema.json
+     An `enum` of a single value can be expressed as `const` (enum_to_const)
+```
+
+Furthermore, running the `lint` command with the `--fix / -f` option will
+result in the JSON Schema CLI *automatically* fixing the warning for you.
+
 ### Lint JSON Schemas in-place
 
 ```sh

docs/test.markdown

@@ -1,13 +1,19 @@
 Testing
 =======
 
+> [!WARNING]
+> Only JSON Schema Draft 4 is supported at this point in time. We have plans
+> to support *every* dialect of JSON Schema from Draft 0 to Draft 2020-12 soon.
+
 ```sh
-jsonschema test [schemas-or-directories...]
+jsonschema test [schemas-or-directories...] [--http/-h] [--metaschema/-m] [--verbose/-v] [--resolve/-r <schema.json> ...]
 ```
 
 Schemas are code. As such, you should run an automated unit testing suite
-against them. The JSON Schema CLI provides a schema-oriented test runner
-inspired by the [official JSON Schema test
+against them. Just like popular test frameworks like [Jest](https://jestjs.io),
+[GoogleTest](https://google.github.io/googletest/), and
+[PyTest](https://docs.pytest.org), the JSON Schema CLI provides a
+schema-oriented test runner inspired by the [official JSON Schema test
 suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite).
 
 Examples

docs/validate.markdown

@@ -1,12 +1,17 @@
 Validating
 ==========
 
+> [!WARNING]
+> Only JSON Schema Draft 4 is supported at this point in time. We have plans
+> to support *every* dialect of JSON Schema from Draft 0 to Draft 2020-12 soon.
+
 ```sh
-jsonschema validate <path/to/schema.json> <path/to/instance.json>
+jsonschema validate <schema.json> [instance.json] [--http/-h] [--metaschema/-m] [--verbose/-v] [--resolve/-r <schema.json> ...]
 ```
 
 The most popular use case of JSON Schema is to validate JSON documents. The
-JSON Schema CLI offers a `validate` command to do exactly that.
+JSON Schema CLI offers a `validate` command to evaluate a JSON instance against
+a JSON Schema, presenting human-friendly information on unsuccessful validation.
 
 Examples
 --------
@@ -16,4 +21,3 @@ Examples
 ```sh
 jsonschema validate path/to/my/schema.json path/to/my/instance.json
 ```
-

src/main.cc

@@ -29,7 +29,7 @@ Global Options:
        is valid with respects to its dialect metaschema even if an instance
        was passed.
 
-   test [schema.json...] [--http/-h] [--metaschema/-m]
+   test [schemas-or-directories...] [--http/-h] [--metaschema/-m]
 
        A schema test runner inspired by the official JSON Schema test suite.
        Passing directories as input will run every `.json` file in such
@@ -39,15 +39,15 @@ Global Options:
       protocol. The `--metaschema/-m` option checks that the given schema is
       valid with respects to its dialect metaschema.
 
-   fmt [schema.json...] [--check/-c]
+   fmt [schemas-or-directories...] [--check/-c]
 
        Format the input schemas in-place. Passing directories as input means
        to format every `.json` file in such directory (recursively). If no
        argument is passed, format every `.json` file in the current working
        directory (recursively). The `--check/-c` option will check if the given
        schemas adhere to the desired formatting without modifying them.
 
-   lint [schema.json...] [--fix/-f]
+   lint [schemas-or-directories...] [--fix/-f]
 
        Lint the input schemas. Passing directories as input means to lint
        every `.json` file in such directory (recursively). If no argument is