cleanup for release

CHANGELOG.md

@@ -1,18 +1,20 @@
 # Changes
 
-## Unreleased
+## 2.0.0 - 2024-10-15
 
-The new portable-color will focus on better alignment with other tools, better code, and easier embeddability.
+This version focuses on better alignment with other tools, better code, and a better integration experience.
 
-1.  Environment variable processing is now fully aligned with the [Standard for ANSI Colors in Terminals](http://bixense.com/clicolors/). Change-wise, this means "NO_COLOR" takes priority over everything, and neither "NO_COLOR" and "CLICOLOR_FORCE" have special behavior if set to "0". This matches the behavior of other tools.
+1.  Color functions now take a single quoted string argument instead of trying to act like "echo". For example:
 
-2.  Authors may choose to use a new "default-off" color mode, where their scripts will not use color unless "CLICOLOR" or "CLICOLOR_FORCE" is explicitly set, even if they would otherwise.
+    ```shell
+    echo $(green "It's not easy being... you know.")
+    ```
 
-3.  Color functions now take a single quoted string argument instead of trying to act like "echo". For example:
+2.  Setup is no longer explicit. Call "setup_color" to configure.
 
-```shell
-echo $(green "It's not easy being... you know.")
-```
+3.  Environment variable semantics are now fully aligned with the [Standard for ANSI Colors in Terminals](http://bixense.com/clicolors/). Change-wise, this means "NO_COLOR" takes priority over everything, and neither "NO_COLOR" and "CLICOLOR_FORCE" have special behavior if set to "0". This matches the behavior of other tools.
+
+4.  Authors may choose to use a new "default-off" color mode when calling "setup_color", where their scripts will not use color unless "CLICOLOR" or "CLICOLOR_FORCE" is explicitly set, even if they would otherwise.
 
 ## 1.0.0 - 2023-06-17
 

NOTES.md

@@ -26,6 +26,6 @@ but then also provides this example source code:
 >     color = false;
 > ```
 
-It seemed logical at the time to also run with this "0" or "1" thing to me, but on reflection (and observing the behavior of some tools, e.g. "brew"), I'm going to reverse course and just go by "is it set?" This also will simplify color configuration detection.
+It seemed logical at the time to me to also run with this "0" or "1" thing, but on reflection (and observing the behavior of some tools, e.g. "brew"), I'm going to reverse course and just go by "is it set?" This also will simplify color configuration detection.
 
 "NO_COLOR" should also take priority over "CLICOLOR_FORCE", which is again a change in behavior.

README.md

@@ -1,15 +1,67 @@
 # portable-color
 
-This script fragment is designed to be included or sourced in your shell scripts, providing you the capability to output in bold and color to emphasize some of your output for humans.
+portable-color is designed to be included or sourced in your shell scripts, providing you the capability to use color and other emphasis to make your output easier for humans to parse.
 
-I wrote more about it in ["How and Why You Should Add Color to Your Scripts"](https://spin.atomicobject.com/2023/05/25/color-scripts/) at [Atomic Spin](https://spin.atomicobject.com/).
+portable-color is _portable_ because it has been carefully written to work everywhere possible, sticking closely to POSIX, working with standard facilities for terminal capabilities, and gracefully backing down when those aren't available.
 
-See [the example script](./example) to see how to use it.
+portable-color is also _respectful_, sticking to the [Standard for ANSI Colors in Terminals](http://bixense.com/clicolors/) (e.g. "NO_COLOR", "CLICOLOR", and friends) and also offering script authors the ability to easily create scripts that don't even use color unless specifically asked-for.
+
+This is a new version of portable-color. I wrote about the original in ["How and Why You Should Add Color to Your Scripts"](https://spin.atomicobject.com/2023/05/25/color-scripts/) at [Atomic Spin](https://spin.atomicobject.com/), and have since changed my mind on a few things. See [the change log](./CHANGELOG.md) for the quick story, and [my notes](./NOTES.md) for more details.
 
 ## Installation
 
-I recommend you install or link "portable-color.sh" into `${HOME}/.local/bin` and add this directory to your PATH if it is not already there.
+You can use portable-color a few ways.
+
+### Embedded
+
+The easiest way to use portable-color is to embed the parts you're going to use into your script. 
+
+That includes, at a minimum, the following functions:
+
+- _try_color
+- setup_color
+- _qtput
+
+All of the color functions and "bold" also require "_twrap".
+
+Finally, you can add just the color and emphasis functions you need.
+
+### As a library
+
+You can install or link "portable-color.sh" into `${HOME}/.local/bin` and add this directory to your PATH if it is not already there.
+
+Don't make it executable. The [POSIX standard dot](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#dot) will search PATH and does not require files it finds to be executable, so leaving it non-executable means it won't be executed interactively by accident, or show up in autocomplete.
+
+I wrote more about my thoughts about how a shell library setup works in ["A proposal for shell libraries"](https://mattiebee.io/44251/a-proposal-for-shell-libraries).
+
+## Usage
+
+Before you can do anything with portable-color, your script must get set up. You can do this two ways.
+
+"setup_color" with no arguments will default to using color (unless the user expresses a preference for none.)
+
+```shell
+setup_color
+```
+
+"setup_color" with a "default-off" argument will default to _not_ using color unless the user expresses a preference for color, e.g. by setting "CLICOLOR".
+
+```shell
+setup_color default-off
+```
+
+Once "setup_color" has run, the variable "TPUT" will contain either the path to the system's [tput](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/tput.html) program, or "true" which works as a no-op. (You generally don't need to know this, but you can leverage this fact if you want to stop here and use capabilities directly.)
+
+Several emphasis functions can be used as wrappers. Each one takes a _single_ argument (note how this is different from "echo"); the easiest way to work with this is by using double quotes, which allow you to nest more emphasis functions and variable subsitutions and the like within.
+
+```shell
+echo $(green "Hello, ${USER}.")
+```
+
+It's important to note that many emphasis functions, like colors and bold, will do a full reset when they close out, because that's the way their terminal capabilities work.
 
-I also recommend you do _not_ make it executable. The [POSIX standard dot](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#dot) will search PATH and does not require files it finds to be executable. Marking this non-executable will it not be invoked interactively.
+This means that, in the example below, at the conclusion of "blue", "bold" is actually reset—so we can't just add more text after the call to "blue" here. It's best to just make another "bold" call.
 
-I wrote more about my thoughts in ["A proposal for shell libraries"](https://mattiebee.io/44251/a-proposal-for-shell-libraries) on [my blog](https://mattiebee.io/).
+```shell
+echo $(bold "Welcome to $(blue "portable-color")")$(bold ".")
+```

portable-color.sh

@@ -1,6 +1,6 @@
 # shellcheck shell=sh
 #
-# Copyright (c) 2023 Mattie Behrens.
+# Copyright (c) 2023, 2024 Mattie Behrens.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -45,7 +45,7 @@ setup_color() {
 # and discard errors.
 
 _qtput() {
-	[ -z "${TPUT}" ] && return 0
+	[ -z "${TPUT}" ] && return 0 # if not set up, don't do anything
 	"${TPUT}" "$@" 2>/dev/null || true
 }
 

spec/portable_color_spec.sh

@@ -1,4 +1,25 @@
 # shellcheck shell=sh disable=SC2034,SC2317
+#
+# Copyright (c) 2024 Mattie Behrens.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
 
 Describe "portable-color.sh"
     Include portable-color.sh