docs: update README and example config to include explanations

README.md

@@ -37,6 +37,7 @@ A simple tool that makes self-contained abominations of C code called bundles. I
   * [Directives](#directives)
     * [bundle](#bundle)
     * [impl](#impl)
+  * [Configuration](#configuration)
   * [Workflow](#workflow)
 * [Installation](#installation)
   * [cargo](#cargo)
@@ -210,22 +211,39 @@ Arguments:
           Path to the entry source file.
 
 Options:
-      --no-format
-          Don't pass the resulting bundle through the formatter.
+      --no-config
+          Don't load any configuration file. (Overrides `--config`)
 
-      --formatter <exe>
-          Code formatter. Must format the code from stdin and write it to stdout.
+      --config <path>
+          Specify an alternate configuration file.
 
-          [default: clang-format]
+          [default: .cbundl.toml cbundl.toml]
 
-      --deterministic
+      --deterministic[=<boolean>]
           Output a deterministic bundle.
 
+          [possible values: yes, no]
+
   -o, --output <path>
           Specify where to write the resulting bundle.
 
           [default: -]
 
+      --no-banner[=<boolean>]
+          Don't output the banner at the top of the bundle.
+
+          [possible values: yes, no]
+
+      --no-format[=<boolean>]
+          Don't pass the resulting bundle through the formatter.
+
+          [possible values: yes, no]
+
+      --formatter <exe>
+          Code formatter. Must format the code from stdin and write it to stdout.
+
+          [default: clang-format]
+
   -h, --help
           Print help (see a summary with '-h')
 
@@ -262,6 +280,15 @@ The bundle directive must always appear exactly above a local `#include`, withou
 
 The `impl` directive, also called an implementation directive, informs `cbundl` that the current file is implemented by the file specified by `<path>`. This directive can appear any number of times in the file (if the implementation is split across many other files). It can also appear anywhere in the file, but convention is that `impl` directives appear only at either the start or the end of the file. Just like `#include`-ing `.c` files, using an implementation directive that points to a `.h` file is generally considered bad practice.
 
+### Configuration
+
+`cbundl` can be configured via a configuration file. The configuration file exposes fine-grained settings for `cbundl` not available through the command line. By default, `cbundl` looks for configuration files named `.cbundl.toml` or `cbundl.toml` (in that order), though a custom configuration file can be specified via `--config`. Alternatively, `--no-config` tells `cbundl` to ignore any configuration files.
+
+> [!NOTE]
+> Command line flags always take priority over the configuration file.
+
+Configuration files for `cbundl` are written in [TOML](https://toml.io/en). An example configuration is given in [`cbundl.toml`](./cbundl.toml).
+
 ### Workflow
 
 Ok that's all cool and all but how do I integrate it into my workflow? I'm glad you asked. Simple, instead of running just:

cbundl.toml

@@ -1,32 +1,85 @@
 [bundle]
+# Add separators between the contents of each source file inside the bundle.
 separators = true
+
+# Produce a deterministic bundle. This switch makes cbundl a pure function.
+# This means that for the same source files, the same bundle is always produced.
+# One sideffect is that dates will be displayed as the UNIX epoch and quotes
+# will always be the same. This switch is useful if you intend to check into
+# source control the bundle, where you wouldn't want to pollute diffs with
+# changed to the generated date, or the quotes inside the bundle.
 deterministic = false
+
+# Write the final bundle to this path.
 output = "test/frob/final.c"
 
+##
+## This section configures a custom header to be added to the very top of the
+## bundle. Useful for adding license text or copyright notices.
+##
 [header]
+# Whether to add the custom header.
 enable = true
+
+# The text to be added. Before you ask: yes, you can inject code from here but
+# you shouldn't have to. If you find yourself doing that, you are doing something
+# wrong.
 text = """
 // My amazing header text!
 """
+
+# Specify a file which contains the text for the header. The contents of the file
+# will be pasted in verbatim. This means that the file must contain the text in
+# C comments.
 #source = "header.txt"
 
+# NOTE: `text` and `source` cannot be specified both at the same time.
+
+##
+## This section configures the banner at the top of the bundle.
+##
 [banner]
+# Whether to add the banner.
 enable = true
 
+##
+## This section configures the quotes displayed inside the banner.
+##
 [banner.quote]
+# Whether to add quotes inside the banner.
 enable = true
+
+# Pick quotes from this location. Specifying "all" here will allow cbundl to
+# choose at random one quote without restrictions. "builtin" will only pick
+# quotes that are built-in to cbundl. "custom" will only pick quotes that are
+# configured here.
+#
+# Valid values: "all", "builtin", "custom"
 pick = "custom"
 
+##
+## This section configures how cbundl will format the bundle.
+##
 [formatter]
+# Whether to format the bundle.
 enable = true
+
+# Path to the formatter binary. Specifying just the executable will make cbundl
+# search in PATH for it.
 path = "clang-format"
+
+# Extra arguments to pass to the formatter.
 args = ["--verbose", "--sort-includes"]
 
+
+# A custom quote.
 [[quote]]
+# Quote text. Will appear as is.
 text = """
 Use a gun. And if that don't work...
                                       use more gun.
 """
+# Quote author. Make sure to give proper credit.
 author = "Dr. Dell Conagher"
 
 [[quote]]