general boilerplate / project-support improvements

.github/workflows/ci.yml

@@ -3,15 +3,13 @@ name: CI
 on:
   push:
     branches:
-      - master
-      - dev
       - boilerplate
+      - dev
+      - idiomatic
+      - master
       - rc1
       - rc2
       - rc3
-      - rc4
-      - rc5
-      - update
   pull_request:
 
 concurrency:

.gitignore

@@ -54,12 +54,10 @@ perf_test/
 
 scripts/internal/
 
-/include/b64/
 /include/shwild/
 /include/xcontract/
 /include/xcover/
 /include/xtests/
-/src/b64/
 /src/shwild/
 /src/xcontract/
 /src/xcover/

.sis/project_name.txt

@@ -0,0 +1 @@
+cstring

AUTHORS.md

@@ -1,12 +1,12 @@
 # cstring - Authors <!-- omit in toc -->
 
 
-## Major Contributors
+## Major Contributors:
 
-* Matt Wilson ([mwsis](https://github.com/mwsis))
+* **Matt Wilson** ([mwsis](https://github.com/mwsis));
 
 
-## Defect reports, fixes and suggestions (for which we are very grateful)
+## Defect reports, fixes and suggestions (for which we are very grateful):
 
 * \<none>
 

CHANGES.md

@@ -1,6 +1,20 @@
 # cstring - CHANGES <!-- omit in toc -->
 
 
+## 4.0.14-alpha1 - 7th August 2026
+
+* Aligned project boilerplate with **b64** / **Pantheios** (scripts, markdown, CI branches, `.sis`);
+* Added **.sis/project_name.txt**; helper scripts load `ProjectName` for status echoes;
+* CI `on.push.branches` set to lexicographic Pantheios set (`boilerplate`, `dev`, `idiomatic`, `master`, `rc1`–`rc3`);
+* **CMakeLists.txt** — set `CMP0177` for CMake ≥ 3.31;
+* **.gitignore** — removed stray **b64** include/src ignore entries;
+* **README.md** — C++ badge; CI badge alt text; **Introduction**; help links; heading fixes;
+* **AUTHORS.md**, **NEWS.md**, **FAQ.md**, **KNOWN_ISSUES.md** — peer layout/content alignment;
+* Added **HOW_YOU_CAN_HELP.md**;
+* **TODO.md** — marked `CMAKE_INSTALL_LIBDIR` complete;
+* **run_all_examples.sh**, **run_all_unit_tests.sh**, **run_all_scratch_tests.sh** — coloured list/execute path output (via `tput`);
+
+
 ## 4.0.13 - 2nd August 2026
 
 * Modular GitHub Actions CI (**ci.yml** + **ci-cell.yml**), with install-smoke and MinGW cells;

CMakeLists.txt

@@ -5,7 +5,7 @@
 # Purpose:  Top-level CMake lists file for cstring
 #
 # Created:  21st December 2023
-# Updated:  2nd August 2026
+# Updated:  6th August 2026
 #
 # ######################################################################## #
 
@@ -14,6 +14,9 @@
 # CMake
 
 cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
+if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.31")
+	cmake_policy(SET CMP0177 NEW)
+endif()
 
 # require out-of-source builds
 file(TO_CMAKE_PATH "${CMAKE_CURRENT_BINARY_DIR}/CMakeLists.txt" LOC_PATH)

Doxyfile

@@ -2,7 +2,7 @@
 
 PROJECT_NAME           = "cstring"
 PROJECT_BRIEF          = "Extensible C-style strings and vectors of such, for Unix and Windows"
-PROJECT_NUMBER         = 4.0.13
+PROJECT_NUMBER         = 4.0.14-alpha1
 
 # Prefer SIS_CMAKE_BUILD_DIR-aligned output (same convention as Diagnosticism).
 # ./dox/ remains gitignored for legacy/local runs that override OUTPUT_DIRECTORY.

FAQ.md

@@ -8,9 +8,11 @@ it will be used to create one.
 ## Table of Contents <!-- omit in toc -->
 
 - [Q1: "How do I build cstring?"](#q1-how-do-i-build-cstring)
-- [Q2: "Does cstring have its own unit-tests?"](#q2-does-cstring-have-its-own-unit-tests)
-- [Q3: "How do I build without the C++ examples and tests?"](#q3-how-do-i-build-without-the-c-examples-and-tests)
-- [Q4: "Where are the examples?"](#q4-where-are-the-examples)
+- [Q2: "How do I install cstring?"](#q2-how-do-i-install-cstring)
+- [Q3: "How do I use cstring?"](#q3-how-do-i-use-cstring)
+- [Q4: "Does cstring have its own unit-tests?"](#q4-does-cstring-have-its-own-unit-tests)
+- [Q5: "How do I build without the C++ examples and tests?"](#q5-how-do-i-build-without-the-c-examples-and-tests)
+- [Q6: "Where are the examples?"](#q6-where-are-the-examples)
 
 
 # FAQs: <!-- omit in toc -->
@@ -37,7 +39,48 @@ $ ./prepare_cmake.sh -m
 Execute `$ ./prepare_cmake.sh --help` for the full set of options.
 
 
-## Q2: "Does cstring have its own unit-tests?"
+## Q2: "How do I install cstring?"
+
+See [INSTALL.md](./INSTALL.md) for details of how to install **cstring**.
+
+
+## Q3: "How do I use cstring?"
+
+Include **cstring/cstring.h** (and **cstring/cstring.vector.h** where needed)
+and link against **libcstring** (the **CMake** target is `cstring::core`).
+Create and destroy instances with `cstring_create()` / `cstring_destroy()`,
+and mutate with `cstring_assign()`, `cstring_append()`, and related APIs.
+
+A minimal sketch:
+
+```c
+#include <cstring/cstring.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(void)
+{
+    cstring_t cs;
+    CSTRING_RC rc = cstring_create(&cs, "Hello");
+
+    if (CSTRING_RC_SUCCESS != rc)
+    {
+        return EXIT_FAILURE;
+    }
+
+    printf("%s\n", cs.ptr);
+
+    cstring_destroy(&cs);
+
+    return EXIT_SUCCESS;
+}
+```
+
+See [INSTALL.md](./INSTALL.md) and the examples under **examples/**.
+
+
+## Q4: "Does cstring have its own unit-tests?"
 
 Yes. Automated tests live under:
 
@@ -50,7 +93,7 @@ and run with **run_all_unit_tests.sh** (and **CTest** where configured). Tests
 require **STLSoft** and **xTests** (and may optionally recognise **shwild**).
 
 
-## Q3: "How do I build without the C++ examples and tests?"
+## Q5: "How do I build without the C++ examples and tests?"
 
 Pass `--no-cpp` (or `-C`) to **prepare_cmake.sh**, which sets CMake
 `NO_CSTRING_CPP_API=ON`. That omits C++ examples and remaining C++ tests.
@@ -59,7 +102,7 @@ The **C** unit-tests still require **STLSoft** and **xTests** unless you also
 pass `--disable-testing` / `-T`.
 
 
-## Q4: "Where are the examples?"
+## Q6: "Where are the examples?"
 
 Examples live under **examples/** (`c/` and `cpp/`), each with a short
 **README.md**. They are built when `BUILD_EXAMPLES` is on (the default); omit

HOW_YOU_CAN_HELP.md

@@ -0,0 +1,70 @@
+# cstring - How You Can Help <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+There are several ways in which you can help the **cstring** project:
+
+- [Defect reports](#defect-reports)
+- [Feature requests](#feature-requests)
+- [Submit your own extensions](#submit-your-own-extensions)
+- [Sponsor development](#sponsor-development)
+- [Write articles, blog-posts about your experiences](#write-articles-blog-posts-about-your-experiences)
+
+
+## Defect reports
+
+We're keen to hear of any problems you have in building and, especially, in
+using the library.
+
+Please submit an issue at:
+
+  https://github.com/synesissoftware/cstring/issues
+
+Please help us to help you by submitting as much information about the
+problem as you think is relevant, including:
+
+* the compiler you're using;
+* the architecture and operating system you're targeting;
+* the version of **cstring**;
+* the version of **STLSoft** / **xTests** (when building tests);
+* whether you're building using **CMake** or via an IDE;
+* a section of the build output, including the warnings/errors involved;
+
+
+## Feature requests
+
+If there are features that you think would enhance the library, please feel
+free to share your ideas.
+
+You can either submit an issue:
+
+  https://github.com/synesissoftware/cstring/issues
+
+Or provide your suggested work via a pull-request:
+
+  https://github.com/synesissoftware/cstring/pulls
+
+
+## Submit your own extensions
+
+If you have developed extensions or improvements and wish to contribute them
+back to the project so others can benefit from your work, please open an
+issue or pull request at:
+
+  https://github.com/synesissoftware/cstring
+
+
+## Sponsor development
+
+If you value the diligence and effort that's gone into bringing you this
+production-quality software, please get in contact via
+https://www.synesis.com.au/contact.html
+
+
+## Write articles, blog-posts about your experiences
+
+If you've written articles or blogged about **cstring**, let us know.
+
+
+<!-- ########################### end of file ########################### -->

KNOWN_ISSUES.md

@@ -1,7 +1,12 @@
 # cstring - Known Issues <!-- omit in toc -->
 
 
-## cstring 4 Known Issues
+## cstring 4.0.x Known Issues
+
+* \<none>
+
+
+## cstring 4.0.x Suspected Issues
 
 * \<none>
 

NEWS.md

@@ -1,29 +1,27 @@
 # cstring - News <!-- omit in toc -->
 
 
-| Date                  | News Item                                                     |
-| --------------------- | ------------------------------------------------------------- |
-| 2nd August 2026       | Release of [cstring 4.0.13](https://github.com/synesissoftware/cstring/releases/tag/4.0.13) (modular CI, examples, Doxygen, documentation) |
-| 2nd September 2025    | Release of [cstring 4.0.12](https://github.com/synesissoftware/cstring/releases/tag/4.0.12) |
-| 23rd February 2025    | Release of cstring 4.0.11                                     |
-| 25th October 2024     | Release of cstring 4.0.10                                     |
-| Available from [**cstring** project on GitHub](https://synesissoftware.com/cstring):  |
-| 28th January 2024     | Release of cstring 4.0.9                                      |
-| 12th January 2024     | Release of cstring 4.0.8                                      |
-| Available from **http://synesis.com.au/software/cstring**:                            |
-| 20th February 2012    | Release of 3.6.2                                              |
-| 24th January 2012     | Release of 3.6.1                                              |
-| 22nd January 2012     | Release of 3.5.4                                              |
-| 11th January 2010     | Release of 3.5.3                                              |
-| 11th July 2009        | Release of 3.5.2                                              |
-| 10th July 2009        | Release of 3.5.1                                              |
-| 4th May 2008          | Release of 3.4.4                                              |
-| 26th January 2007     | Release of 3.4.3                                              |
-| 30th April 2006       | Release of 3.4.2                                              |
-| 7th October 2005      | Release of 3.4.1                                              |
-| 8th August 2005       | Release of 3.3.1                                              |
-| 29th July 2005        | Release of 3.2.1                                              |
+| Date               | News Item                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| 7th August 2026    | Release of [cstring 4.0.14-alpha1](https://github.com/synesissoftware/cstring/releases/tag/4.0.14-alpha1) (boilerplate alignment with **b64** / **Pantheios**) |
+| 2nd August 2026    | Release of [cstring 4.0.13](https://github.com/synesissoftware/cstring/releases/tag/4.0.13) (modular CI, examples, Doxygen, documentation) |
+| 2nd September 2025 | Release of [cstring 4.0.12](https://github.com/synesissoftware/cstring/releases/tag/4.0.12)                                     |
+| 23rd February 2025 | Release of cstring 4.0.11 |
+| 25th October 2024  | Release of cstring 4.0.10 |
+| 28th January 2024  | Release of cstring 4.0.9  |
+| 12th January 2024  | Release of cstring 4.0.8  |
+| 20th February 2012 | Release of 3.6.2          |
+| 24th January 2012  | Release of 3.6.1          |
+| 22nd January 2012  | Release of 3.5.4          |
+| 11th January 2010  | Release of 3.5.3          |
+| 11th July 2009     | Release of 3.5.2          |
+| 10th July 2009     | Release of 3.5.1          |
+| 4th May 2008       | Release of 3.4.4          |
+| 26th January 2007  | Release of 3.4.3          |
+| 30th April 2006    | Release of 3.4.2          |
+| 7th October 2005   | Release of 3.4.1          |
+| 8th August 2005    | Release of 3.3.1          |
+| 29th July 2005     | Release of 3.2.1          |
 
 
 <!-- ########################### end of file ########################### -->
-

README.md

@@ -4,23 +4,24 @@
 
 
 ![C](https://img.shields.io/badge/C-00599C?style=flat&logo=c&logoColor=white)
+![C++](https://img.shields.io/badge/C%2B%2B-00599C?style=flat&logo=c%2B%2B&logoColor=white)
 [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![GitHub release](https://img.shields.io/github/v/release/synesissoftware/cstring.svg)](https://github.com/synesissoftware/cstring/releases/latest)
 [![Last Commit](https://img.shields.io/github/last-commit/synesissoftware/cstring)](https://github.com/synesissoftware/cstring/commits/master)
-[![CMake on multiple platforms](https://github.com/synesissoftware/cstring/actions/workflows/ci.yml/badge.svg)](https://github.com/synesissoftware/cstring/actions/workflows/ci.yml)
-
+[![CI](https://github.com/synesissoftware/cstring/actions/workflows/ci.yml/badge.svg)](https://github.com/synesissoftware/cstring/actions/workflows/ci.yml)
 
 
 ## Table of Contents <!-- omit in toc -->
 
+- [Introduction](#introduction)
 - [Installation](#installation)
 - [Components](#components)
   - [Types](#types)
   - [String API](#string-api)
     - [Status and capacity](#status-and-capacity)
     - [Creation/destruction functions](#creationdestruction-functions)
-    - [Modification functions\*\*](#modification-functions)
-    - [File functions\*\*](#file-functions)
+    - [Modification functions](#modification-functions)
+    - [File functions](#file-functions)
   - [Vector API](#vector-api)
 - [Examples](#examples)
 - [Project Information](#project-information)
@@ -31,6 +32,13 @@
   - [License](#license)
 
 
+## Introduction
+
+**cstring** is a small, standalone library that provides extensible C-style string instances and extensible arrays of such, for Unix and Windows.
+
+The **C** API has no non-standard dependencies. Optional C++ examples and remaining C++ tests may be omitted with `--no-cpp` / `NO_CSTRING_CPP_API`. Building tests requires **STLSoft** and **xTests** (and may optionally recognise **shwild**).
+
+
 ## Installation
 
 Detailed instructions - via **CMake**, via bundling - are provided in the accompanying [INSTALL.md](./INSTALL.md) file.
@@ -89,7 +97,7 @@ Defined in **cstring/cstring.h**:
 * `cstring_createLenEx()` — as `cstring_createEx()`, from a fixed number of characters;
 * `cstring_destroy()` — releases resources and resets the instance;
 
-#### Modification functions**
+#### Modification functions
 
 * `cstring_assign()` — assigns a C-style string (may reallocate);
 * `cstring_assignLen()` — assigns a fixed character count (embedded NULs allowed);
@@ -104,7 +112,7 @@ Defined in **cstring/cstring.h**:
 * `cstring_truncate()` — shortens the logical length (capacity unchanged);
 * `cstring_swap()` — swaps the contents of two instances;
 
-#### File functions**
+#### File functions
 
 * `cstring_readline()` — reads a line of text from the given text stream into the instance;
 * `cstring_write()` — writes the string to the given text stream;
@@ -143,13 +151,18 @@ Examples live under **examples/** (`c/` and `cpp/`), each with a short **README.
 
 ### Where to get help
 
-[GitHub Page](https://github.com/synesissoftware/cstring "GitHub Page")
+* [GitHub Page](https://github.com/synesissoftware/cstring)
+* [GitHub Issues](https://github.com/synesissoftware/cstring/issues)
+* [FAQ.md](./FAQ.md)
+* [HOW_YOU_CAN_HELP.md](./HOW_YOU_CAN_HELP.md)
 
 
 ### Contribution guidelines
 
 Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/cstring.
 
+See also [HOW_YOU_CAN_HELP.md](./HOW_YOU_CAN_HELP.md).
+
 
 ### Dependencies