📝 Additional CLI change documentation

docs/CeedlingPacket.md

@@ -874,8 +874,8 @@ Ceedling provides robust command line help for application commands.
 Execute `ceedling help` for a summary view of all application commands.
 Execute `ceedling help <command>` for detailed help.
 
-_Note:_ Because the built-in command line help is thorough, we will only briefly
-list and explain the available application commands.
+_Note:_ Because the built-in command line help is thorough, we will only 
+briefly list and explain the available application commands.
 
 * `ceedling [no arguments]`:
 
@@ -885,18 +885,20 @@ list and explain the available application commands.
 
 * `ceedling build <tasks...>` or `ceedling <tasks...>`:
 
-  Runs the named build tasks. `build` is optional. Various option flags
-  exist to control what project configuration is loaded, verbosity 
-  levels, logging, etc. See next section for build tasks. Of note,
-  this application command provides optional test case filters using
-  traditional option flags (ex. `--test-case=<filter>`) whose contents
-  are provided to Rake test tasks behind the scenes.
+  Runs the named build tasks. `build` is optional (i.e. `ceedling test:all` 
+  is equivalent to `ceedling build test:all`). Various option flags
+  exist to control project configuration loading, verbosity levels, 
+  logging, test task filters, etc.
+
+  See next section to understand the build & plugin tasks this application
+  command is able to execute. Run `ceedling help build` to understand all
+  the command line flags that work with build & plugin tasks.
 
 * `ceedling dumpconfig`:
 
   Process project configuration and write final result to a YAML file. 
-  Various option flags exist to control what project configuration is 
-  loaded.
+  Various option flags exist to control project configuration loading,
+  configuration manipulation, and configuration sub-section extraction.
 
 * `ceedling environment`:
 
@@ -944,12 +946,15 @@ list and explain the available application commands.
 
   Displays version information for Ceedling and its components.
 
-## Ceedling build tasks
+## Ceedling build & plugin tasks
 
 Build task are loaded from your project configuration. Unlike 
 application commands that are fixed, build tasks vary depending on your
 project configuration and the files within your project structure.
 
+Ultimately, build & plugin tasks are executed by the `build` application
+command (but the `build` keyword can be omitted — see above).
+
 * `ceedling paths:*`:
 
   List all paths collected from `:paths` entries in your YAML config

docs/Changelog.md

@@ -19,6 +19,16 @@ As was explained in the _[Highlights](#-Highlights)_, Ceedling can now run its i
 
 Enabling this speedup requires either or both of two simple configuration settings. See Ceedling’s [documentation](CeedlingPacket.md) for `:project` ↳ `:compile_threads` and `:project` ↳ `:test_threads`.
 
+### A proper command line
+
+Ceedling now offers a full command line interface with rich help, useful order-independent option flags, and more.
+
+The existing `new`, `upgrade`, `example`, and `exampples` commands remain but have been improved. For those commands that support it, you may now specify the project file to load (see new, related mixins feature discussed elsewhere), log file to write to, exit code handling behavior, and more from the command line.
+
+Try `ceedling help` and then `ceedling help <command>` to get started.
+
+See the _[Release Notes](ReleaseNotes.md)_ and _[CeedlingPacket](CeedlingPacket.md)_ for more on the new and improved command line.
+
 ### `TEST_INCLUDE_PATH(...)` & `TEST_SOURCE_FILE(...)`
 
 Issue [#743](https://github.com/ThrowTheSwitch/Ceedling/issues/743)
@@ -59,11 +69,11 @@ All the options for loading and modifying a project configuration are thoroughly
 
 Issue [#43](https://github.com/ThrowTheSwitch/Ceedling/issues/43)
 
-Each test executable is now built as a mini project. Using improved `:flags` handling and an updated section format within Ceedling’s project file, you have much better options for specifying flags presented to the various tools within your build, particulary within test builds.
+Each test executable is now built as a mini project. Using improved `:flags` handling and an updated section format within Ceedling’s project configuration, you have much better options for specifying flags presented to the various tools within your build, particulary within test builds.
 
 ### More better `:defines` handling
 
-Each test executable is now built as a mini project. Using improved `:defines` handling and an updated section format within Ceedling’s project file, you have much better options for specifying symbols used in your builds' compilation steps, particulary within test builds.
+Each test executable is now built as a mini project. Using improved `:defines` handling and an updated section format within Ceedling’s project configuration, you have much better options for specifying symbols used in your builds' compilation steps, particulary within test builds.
 
 One powerful new feature is the ability to test the same source file built differently for different tests. Imagine a source file has three different conditional compilation sections. You can now write unit tests for each of those sections without complicated gymnastics to cause your test suite to build and run properly.
 
@@ -105,7 +115,7 @@ Much glorious filepath and pathfile handling now abounds:
 * Matching globs were advertised in the documentation (erroneously, incidentally) but lacked full programmatic support.
 * Ceedling now tells you if your matching patterns don't work. Unfortunately, all Ceedling can determine is if a particular pattern yielded 0 results.
 
-### Bug fixes for command line tasks `files:header` and `files:support`
+### Bug fixes for command line build tasks `files:header` and `files:support`
 
 Longstanding bugs produced duplicate and sometimes incorrect lists of header files. Similarly, support file lists were not properly expanded from globs. Both of these problems have been fixed. The `files:header` command line task has replaced the `files:include` task.
 

docs/ReleaseNotes.md

@@ -67,10 +67,18 @@ Until this release, Ceedling depended on Rake for most of its command line handl
 
 Ceedling now offers a full command line interface with rich help, useful order-independent option flags, and more.
 
-The existing `new`, `upgrade`, and `example` commands remain but have been improved. You may now even specify the project file to load, log file to write to, and exit code handling behavior from the command line.
+The existing `new`, `upgrade`, `example`, and `exampples` commands remain but have been improved. For those commands that support it, you may now specify the project file to load (see new, related mixins feature discussed elsewhere), log file to write to, exit code handling behavior, and more from the command line.
 
 Try `ceedling help` and then `ceedling help <command>` to get started.
 
+**_Important Notes on the New Command Line:_**
+
+* The new and improved features for running build tasks — loading a project file, merging mixins, verbosity handling, etc. — are documented within the application command `build` keyword. A build command line such as the following is now possible: `ceedling test:all --verbosity obnoxious --logfile my/path/build.log`. Run `ceedling help build` to learn more and definitely see the next bullet point as well.
+* The `build` keyword is assumed by Ceedling. That is, it’s optional. `ceedling test:all` is the same as `ceedling build test:all`. The `build` keyword handling tells the Ceedling application to execute the named build task dynamically generated from your project configuration. 
+* In the transition to remove Rake from Ceedling, two categories of command line interactions now exist. Note this distinction in the `help` headings.
+   1. **Application Commands** — `help`, `build`, `new`, `upgrade`, `environment`, `examples`, `example`, `dumpconfig`, and `version`. These have full help via `ceedling help <command>` and a variety of useful command line switches that conform to typical command line conventions.
+   1. **Build & Plugin Tasks** — Operations dynamically generated from your project configuration. These have only summary help (listed in `ceedling help`) and work just as they previously did. Common command line tasks including `ceedling test:all` and `ceedling release` are in this category.
+
 ### Medium Deal Highlights 🥈
 
 #### `TEST_SOURCE_FILE(...)`