Upgrade to cowel 0.10.1

.devcontainer/post-create.sh

@@ -2,6 +2,6 @@
 
 set -euo pipefail
 
-version=0.10.0
+version=0.10.1
 
 npm install -g "cowel@${version}"

.github/skills/cowel-version-upgrade/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: cowel-version-upgrade
+description: 'Upgrade COWEL paper sources and repo tooling to a newer COWEL release. Use when bumping : cowel version lines in src/*.cow, updating scripts and GitHub workflows, rebuilding docs, and verifying bitwise-identical outputs.'
+argument-hint: '<old-version> <new-version> [--dry-run]'
+user-invocable: true
+---
+
+# COWEL Version Upgrade
+
+Upgrade this repository from one COWEL version to another in a repeatable, low-risk way.
+
+## When To Use
+- Bumping COWEL from one release to another (for example 0.10.0 to 0.10.1)
+- Updating paper headers in `src/*.cow`
+- Updating workflow and script pins for COWEL
+- Rebuilding docs and checking for bitwise-identical output
+
+## Inputs
+- Old version (currently in sources), for example `0.10.0`
+- New version (target), for example `0.10.1`
+- Optional `--dry-run` to preview changed files
+
+## Procedure
+1. Run version replacement:
+   - [upgrade-cowel-version.sh](./scripts/upgrade-cowel-version.sh)
+2. Rebuild and verify:
+   - [rebuild-and-verify.sh](./scripts/rebuild-and-verify.sh)
+3. If verification fails, patch only impactful nested inline-code rendering sites (for example switching selected `tcode` to `ocode`) and rerun verification.
+
+## Decision Points
+- If only source headers changed and verify passes: no content-level patching required.
+- If verify fails with nested-highlighting artifacts in generated HTML: update only the specific nested inline-code call sites that affect output.
+- If a file should intentionally remain on an older COWEL syntax version: do not force-upgrade it; keep versioned legacy files unchanged unless explicitly requested.
+
+## Files Typically Touched
+- `src/*.cow`: version header lines like `\: cowel X.Y.Z`
+- `scripts/rebuild-docs.sh`: version comments/grep patterns
+- `.github/workflows/*.yml`: pinned `cowel@X.Y.Z`
+- `README.md`: documented version pin(s)
+- `.devcontainer/post-create.sh`: devcontainer COWEL version pin
+- Optional repo-specific setup docs (for example `.github/copilot-instructions.md`)
+
+## Completion Criteria
+- No remaining old-version references:
+  - `rg -n "<old>|cowel@<old>|\\: cowel <old>"`
+- Rebuild succeeds for targeted docs.
+- Verification passes with no mismatches.
+
+## Notes
+- Keep changes minimal and targeted.
+- Prefer surgical source edits over broad style changes when restoring bitwise output compatibility.

.github/skills/cowel-version-upgrade/scripts/rebuild-and-verify.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Rebuild docs for current versioned sources, then verify generated output.
+# Usage:
+#   ./scripts/rebuild-and-verify.sh
+
+repo_root="$(cd "$(dirname "$0")/../../../.." && pwd)"
+cd "$repo_root"
+
+if [[ ! -x scripts/rebuild-docs.sh ]]; then
+  echo "Missing executable scripts/rebuild-docs.sh" >&2
+  exit 1
+fi
+
+if [[ ! -x scripts/verify-docs.sh ]]; then
+  echo "Missing executable scripts/verify-docs.sh" >&2
+  exit 1
+fi
+
+./scripts/rebuild-docs.sh
+./scripts/verify-docs.sh
+
+echo "Rebuild + verify completed successfully."

.github/skills/cowel-version-upgrade/scripts/upgrade-cowel-version.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Bulk-upgrade repo references from one COWEL version to another.
+# Usage:
+#   ./scripts/upgrade-cowel-version.sh <old-version> <new-version> [--dry-run]
+
+if [[ $# -lt 2 || $# -gt 3 ]]; then
+  echo "Usage: $0 <old-version> <new-version> [--dry-run]" >&2
+  exit 2
+fi
+
+old="$1"
+new="$2"
+dry_run="${3:-}"
+
+repo_root="$(cd "$(dirname "$0")/../../../.." && pwd)"
+cd "$repo_root"
+
+if [[ "$old" == "$new" ]]; then
+  echo "Old and new versions are identical: $old" >&2
+  exit 2
+fi
+
+# Update only files that are expected to contain version pins.
+mapfile -t files < <(
+  {
+    find src -type f -name '*.cow' -print
+    printf '%s\n' README.md scripts/rebuild-docs.sh
+    find .github/workflows -type f \( -name '*.yml' -o -name '*.yaml' \) -print
+    printf '%s\n' .devcontainer/post-create.sh
+    [[ -f .github/copilot-instructions.md ]] && printf '%s\n' .github/copilot-instructions.md
+  } | sort -u
+)
+
+changed=0
+for f in "${files[@]}"; do
+  [[ -f "$f" ]] || continue
+
+  if [[ -n "$dry_run" ]]; then
+    if rg -q "${old}|cowel@${old}|\\\\: cowel ${old}" "$f"; then
+      echo "WOULD UPDATE: $f"
+      changed=1
+    fi
+    continue
+  fi
+
+  if rg -q "${old}|cowel@${old}|\\\\: cowel ${old}" "$f"; then
+    sed -i "s/${old//./\\.}/${new}/g" "$f"
+    echo "UPDATED: $f"
+    changed=1
+  fi
+done
+
+if [[ -n "$dry_run" ]]; then
+  if [[ $changed -eq 0 ]]; then
+    echo "No files would be updated for ${old} -> ${new}."
+  fi
+  exit 0
+fi
+
+if [[ $changed -eq 0 ]]; then
+  echo "No files updated for ${old} -> ${new}."
+else
+  echo "Version upgrade applied: ${old} -> ${new}."
+fi

.github/workflows/verify-docs.yml

@@ -15,7 +15,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Install cowel
-        run: npm install -g cowel@0.10.0
+        run: npm install -g cowel@0.10.1
 
       - name: Verify docs match sources
         run: bash scripts/verify-docs.sh

README.md

@@ -10,5 +10,5 @@ or if you have suggestions for improvement.
 
 This repository includes a GitHub Codespaces/devcontainer setup
 that installs Node.js,
-`cowel@0.10.0`,
+`cowel@0.10.1`,
 and the COWEL VS Code extension automatically.

scripts/rebuild-docs.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Rebuild HTML files in docs/ for every COWEL 0.10.0 source file,
+# Rebuild HTML files in docs/ for every COWEL 0.10.1 source file,
 # but only when a corresponding HTML file already exists in docs/.
 #
 # Usage: scripts/rebuild-docs.sh
@@ -18,6 +18,6 @@ while IFS= read -r src; do
   fi
   cowel run "$src" "$dest"
   echo "BUILT: $src -> $dest"
-done < <(grep -rl '\\: cowel 0\.10\.0' src/)
+done < <(grep -rl '\\: cowel 0\.10\.1' src/)
 
 exit $failed

src/array.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title = {\tcode{std::array} is a wrapper for an array!}){

src/ascii.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")\
 \
 \cowel_macro("charset"){\tt{\hl("string"){[\cowel_put]}}}\

src/better-shifting.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Better shifting}){

src/big-int.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={\tcode{std::big_int}}){

src/bit-cast-padding.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Fixing \tcode{std::bit_cast} of types\br{}with padding bits}){

src/bit-permutations-simd.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={\tcode{std::simd} overloads for bit permutations}){

src/bitint.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Bit-precise integers}){

src/case-ranges.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Case ranges}){

src/charconv-ext.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Extending \tcode{<charconv>} support to more character types}){

src/clarify-fp-overflow.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Clarify the behavior of floating-point overflow}){

src/clmul.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Carry-less product: \tt{std::clmul}}){

src/cmath-c23.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Rebasing \tt{<cmath>} on C23}){

src/concise-grammar.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Improve readability of the C++ grammar by adding a syntax for groups and repetitions}){

src/correctly-rounded-math.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Correctly rounded floating-point maths functions}){

src/deprecate-unicode-conversion.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Deprecate implicit conversions

src/fix-declaration-font.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Fix inappropriate font choices for "declaration"}){

src/fix-floating-from-chars.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Fix defects in floating-point \tcode{std::from_chars}\br

src/floating-point-values.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Values of floating-point types}){

src/intdiv.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Integer division}){

src/libwg21-9.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_actions{
 
 \cowel_macro("hl"){\cowel_paragraph_enter\cowel_highlight_as(...){\cowel_put}}

src/more-bitset-operations.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={More bitset operations}){

src/more-trailing-commas.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={More trailing commas}){

src/more-unicode-escapes.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \cowel_macro("zwnbsp"){\'ZERO WIDTH NO-BREAK SPACE'}

src/n-algorithms.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={\tcode{partial_sort_at_most}, \tcode{nth_element_at_most}}){

src/named-args.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Named function arguments}){

src/random-chars.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Supporting \tt{signed char} and \tt{unsigned char}\br in random number generation}){

src/rename-sat.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Renaming saturation arithmetic functions}){

src/replace-charconv.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Provide a better replacement for \tt{std::to_chars} and \tt{std::from_chars}}){

src/sd-7-updates.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \cowel_macro("bolden"){\del{\cowel_put} \ins{\b{\cowel_put}}}

src/sequential-hex-digits.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Sequential hexadecimal digits}){

src/template-9.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(

src/to-signed-unsigned.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={\tcode{std::to_signed} and \tcode{std::to_unsigned}}){

src/trivially-copyable-optional-ref.cow

@@ -1,4 +1,4 @@
-\: cowel 0.10.0
+\: cowel 0.10.1
 \cowel_include("libwg21-9.cow")
 
 \wg21_head(title={Make \tcode{optional<T&>} trivially copyable\br{}(NB comment US 134-215)}){