docs: add some more information to the README.md

README.md

@@ -4,6 +4,10 @@
 
 ## Motivation
 
+Are you annoyed by having to fix the absolute imports generated by `protoc`?
+
+If so, then `protoletariat` is the tool for you.
+
 `protoletariat` has one goal: fixing the broken imports for the Python code
 generated by `protoc`.
 
@@ -19,6 +23,11 @@ generated by `protoc`.
 
 ## Usage
 
+`protoletariat` is designed to be run as a post-processing step _after_ running
+`protoc`. It operates directly on the generated code.
+
+### Example
+
 Here's an example of how to use the tool, called `protol`:
 
 1. Create a few protobuf files
@@ -66,7 +75,7 @@ $ protol \
   protoc --proto-path=directory/containing/protos thing1.proto thing2.proto
 ```
 
-The `out/thing1_pb2.py` file should show a diff containing at least these lines:
+The `out/thing1_pb2.py` module should show a diff containing at least these lines:
 
 ```patch
 -import thing2_pb2 as thing2__pb2
@@ -80,12 +89,24 @@ At a high level `protoletariat` converts absolute imports to relative imports.
 
 However, it doesn't convert just any absolute import to a relative import.
 
-The `protol` tool will only convert imports that were generated from `.proto` files. It
-does this by inspecting `FileDescriptorProtos` from the protobuf files.
+The `protol` tool will only convert imports that were generated from `.proto`
+files. It does this by inspecting `FileDescriptorProtos` generated from the
+proto files.
 
 The core rewrite mechanism is implemented using a simplified form of pattern
-matching, that looks at the Python AST, and if an import pattern is matched a
-corresponding rewrite rule is invoked.
+matching that looks at the Python AST, and invokes rewrite rules for matched
+import patterns.
+
+## Subcommands
+
+`protoletariat` has a subcommand for each tool that you might like to use to
+generate `FileDescriptorSet` bytes:
+
+| Subcommand | Description                                                                |
+| :--------: | :------------------------------------------------------------------------- |
+|  `protoc`  | Uses `protoc` to generate `FileDescriptorSet` bytes                        |
+|   `buf`    | Uses `buf` to generate `FileDescriptorSet` bytes                           |
+|   `raw`    | You provide the `FileDescriptorSet` bytes as a file or directly from stdin |
 
 ## Help