Support: Improve documentation (#47)

Author: chriskilding

README.md

@@ -5,15 +5,14 @@
 
 Semantic Versioning utility.
 
-## Overview
+## Description
 
-The `semver` command line utility extracts, parses, sorts, and validates [Semantic Version](https://semver.org/) strings.
+The `semver` utility is a text filter for [Semantic Version](https://semver.org/) strings. It searches text from the standard input, selects any Semantic Versions that are present, and writes them to the standard output. It can optionally sort or tabulate the selected versions.
 
-The Semantic Versioning format is:
+A *version* string will be selected within the text stream if the following criteria are met:
 
-    major.minor.patch[-prerelease][+build]
-
-Examples: `1.2.3`, `1.2.3-alpha`, `1.2.3+2008`, `1.2.3-alpha+2008`.
+- *version* is a valid Semantic Version.
+- *version* is a whole line. (This can be modified with the `-w` option.)
 
 ## Install
 
@@ -45,7 +44,7 @@ Options:
 - `-t --tabulate`
   Tabulate the matched versions (separator: '\t').
 - `-w --word-match`
-  Select words that match the semver pattern.
+  Select words that match the semver pattern. (Equivalent to the *grep(1)* `--word-regexp` option.)
 
 Most options can be combined. For example, `semver -stw` will word-match occurrences of semvers, sort them, and print them in tabulated form. 
 
@@ -57,6 +56,25 @@ man semver
 
 ## Examples
 
+**Select** lines that are version strings:
+
+```bash
+semver < example.txt
+```
+
+**Calculate** the next Git tag:
+
+```bash
+# ++major
+git tag | semver -st | tail -n 1 | awk -F '\t' '{ print ++$1 "." 0 "." 0 }'
+
+# ++minor
+git tag | semver -st | tail -n 1 | awk -F '\t' '{ print $1 "." ++$2 "." 0 }'
+
+# ++patch
+git tag | semver -st | tail -n 1 | awk -F '\t' '{ print $1 "." $2 "." ++$3 }'
+```
+
 **Cut** out the major, minor, and patch components of a version:
 
 ```bash
@@ -72,33 +90,48 @@ while curl -fs "https://example.com/artifact/$v.tar.gz" > "$v.tar.gz"; do
 done
 ```
 
+**Find** the current Git tag:
+
+```bash
+git tag | semver -s | tail -n 1
+```
+
 **Format** versions as CSV:
 
 ```bash
-semver -tw < versions.txt | tr '\t' ','
+semver -tw < example.txt | tr '\t' ','
 ```
 
-**Get** the latest Git tag:
+**Validate** a candidate version string:
 
 ```bash
-git tag | semver -s | tail -n 1
+semver -q <<< '1.2.3' && echo 'ok'
 ```
 
-**Increment** the current Git tag:
+## Functions
+
+These Bash helper functions can make complex versioning operations easier.
 
 ```bash
-# ++major
-git tag | semver -st | tail -n 1 | awk -F '\t' '{ print ++$1 "." 0 "." 0 }'
+#!/usr/bin/env bash
 
-# ++minor
-git tag | semver -st | tail -n 1 | awk -F '\t' '{ print $1 "." ++$2 "." 0 }'
+function ++major {
+    semver -t <<< "$1" | awk -F '\t' '{ print ++$1 "." 0 "." 0 }'
+}
 
-# ++patch
-git tag | semver -st | tail -n 1 | awk -F '\t' '{ print $1 "." $2 "." ++$3 }'
+function ++minor {
+    semver -t <<< "$1" | awk -F '\t' '{ print $1 "." ++$2 "." 0 }'
+}
+
+function ++patch {
+    semver -t <<< "$1" | awk -F '\t' '{ print $1 "." $2 "." ++$3 }'
+}
 ```
 
-**Validate** a candidate version string:
+Examples:
 
 ```bash
-semver -q <<< '1.2.3' && echo 'ok'
+++major '1.2.3'   #=> 2.0.0
+++minor '1.2.3'   #=> 1.3.0
+++patch '1.2.3'   #=> 1.2.4
 ```

semver.1

@@ -10,13 +10,13 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility can search text from the standard input, select any Semantic Version strings that are
-present, and write them to the standard output. It can optionally sort or tabulate the selected
+utility is a text filter for Semantic Version strings. It searches text from the standard input, selects any Semantic
+Versions that are present, and writes them to the standard output. It can optionally sort or tabulate the selected
 versions.
 .Pp
 A
 .Sq version
-string will be matched within the text stream if the following criteria are met:
+string will be selected within the text stream if the following criteria are met:
 .Bl -bullet -compact
 .It
 .Sq version
@@ -27,20 +27,6 @@ is a whole line. (This can be modified with the
 .Fl w
 option.)
 .El
-.Pp
-Example:
-.Pp
-.Bd -literal -offset indent
-$ semver <<EOF
-1.1.1
-bar
-2.2.2-alpha+1
-foo-3.3.3.txt
-EOF
-
-1.1.1
-2.2.2-alpha+1
-.Ed
 .Sh OPTIONS
 .Pp
 The
@@ -114,6 +100,25 @@ EOF
 .El
 .Sh EXAMPLES
 .Pp
+\fBSelect\fR lines that are version strings:
+.Pp
+.Bd -literal -offset indent -compact
+semver < example.txt
+.Ed
+.Pp
+\fBCalculate\fR the next Git tag:
+.Pp
+.Bd -literal -offset indent -compact
+# major++
+git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print ++$1 "." 0 "." 0 }'
+
+# minor++
+git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print $1 "." ++$2 "." 0 }'
+
+# patch++
+git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print $1 "." $2 "." ++$3 }'
+.Ed
+.Pp
 \fBCut\fR out the major, minor, and patch components of versions:
 .Pp
 .Bd -literal -offset indent -compact
@@ -129,29 +134,16 @@ while curl -fs "https://example.com/artifact/$v.tar.gz" > "$v.tar.gz"; do
 done
 .Ed
 .Pp
-\fBFormat\fR version strings as CSV:
-.Pp
-.Bd -literal -offset indent -compact
-semver -tw < versions.txt | tr '\\t' ','
-.Ed
-.Pp
-\fBGet\fR the current Git tag:
+\fBFind\fR the current Git tag:
 .Pp
 .Bd -literal -offset indent -compact
 git tag | semver -s | tail -n 1
 .Ed
 .Pp
-\fBIncrement\fR the Git tag:
+\fBFormat\fR version strings as CSV:
 .Pp
 .Bd -literal -offset indent -compact
-# major++
-git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print ++$1 "." 0 "." 0 }'
-
-# minor++
-git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print $1 "." ++$2 "." 0 }'
-
-# patch++
-git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print $1 "." $2 "." ++$3 }'
+semver -tw < example.txt | tr '\\t' ','
 .Ed
 .Pp
 \fBValidate\fR a candidate version string: