Modernise realpath tooling and documentation for 0.1.1

.gitattributes

@@ -1,17 +1,99 @@
-*.c linguist-language=C
-*.cmake linguist-vendored
-*.cmd linguist-detectable=false
-*.cpp linguist-language=C++
-*.cxx linguist-language=C++
-*.dsp linguist-detectable=false
-*.dsw linguist-detectable=false
-*.h linguist-language=C
-*.hpp linguist-language=C++
-*.html linguist-detectable=false
-*.hxx linguist-language=C++
-*.sh linguist-detectable=false
-*.sln linguist-detectable=false
-*.vcxproj linguist-detectable=false
-*.vimrc linguist-detectable=false
-CMakeLists.txt linguist-vendored
-makefile linguist-detectable=false
+# .gitattributes — C++ (GitHub-hosted)
+#
+# Sources: GitHub Docs (line endings), git-scm gitattributes (diff=cpp),
+# gitattributes/gitattributes C++.gitattributes + Common.gitattributes,
+# github-linguist overrides.
+
+# Default: detect text, normalize to LF in the repository
+* text=auto
+
+# --- Source ---
+*.c text diff=cpp
+*.c++ text diff=cpp
+*.cc text diff=cpp
+*.cpp text diff=cpp
+*.cxx text diff=cpp
+*.h text diff=cpp
+*.h++ text diff=cpp
+*.hh text diff=cpp
+*.hpp text diff=cpp
+*.hxx text diff=cpp
+*.inc text
+*.inl text
+*.ipp text
+*.tcc text
+*.tpp text
+
+# --- Build / config ---
+*.am text
+*.cmake text
+*.m4 text
+*.mak text
+*.mk text
+*akefile text
+CMakeLists.txt text
+configure text eol=lf
+configure.ac text
+
+# --- Scripts ---
+*.bash text eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+*.sh text eol=lf
+*.zsh text eol=lf
+
+# --- Docs / meta ---
+*.adoc text
+*.markdown text diff=markdown
+*.md text diff=markdown
+*.txt text
+AUTHORS text
+CHANGELOG text
+CHANGES text
+CONTRIBUTING text
+COPYING text
+LICENSE text
+NEWS text
+README text
+TODO text
+.gitattributes text
+.gitignore text
+
+# --- Serialisation ---
+*.json text
+*.toml text
+*.xml text
+*.yaml text
+*.yml text
+
+# --- Compiled / binary artefacts ---
+*.a binary
+*.dll binary
+*.dylib binary
+*.exe binary
+*.gch binary
+*.la binary
+*.lai binary
+*.lib binary
+*.lo binary
+*.o binary
+*.obj binary
+*.out binary
+*.pch binary
+*.slo binary
+*.so binary
+
+# --- Archives / images (common) ---
+*.gif binary
+*.gz binary
+*.ico binary
+*.jpeg binary
+*.jpg binary
+*.png binary
+*.tar binary
+*.zip binary
+
+# --- GitHub Linguist ---
+**/build/** linguist-generated
+**/cmake-build-*/** linguist-generated

.github/workflows/ci.yml

@@ -6,8 +6,10 @@ on:
       - master
       - dev
       - boilerplate
-      - update
-      - version
+      - idiomatic
+      - rc1
+      - rc2
+      - rc3
   pull_request:
 
 concurrency:

.vimrc

@@ -43,27 +43,27 @@ autocmd BufWritePre * %s/\s\+$//e
 augroup sis_c_cxx
   autocmd!
 
+  " [bat]
+  autocmd FileType bat,dosbatch setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76
+
   " [c] / [cpp]
   autocmd FileType c,cpp setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,64,68,72,76
 
-  " [rust]
-  autocmd FileType rs setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=76
-
   " [cmake]
   autocmd FileType cmake setlocal noexpandtab tabstop=4 shiftwidth=4 softtabstop=4
 
-  " [shellscript]
-  autocmd FileType sh,bash,zsh setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2 colorcolumn=60,76
-
-  " [bat]
-  autocmd FileType bat,dosbatch setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76
-
   " [json] / [markdown] / [yaml] / [ruby]
   autocmd FileType json,markdown,yaml,ruby setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2
 
   " [python]
   autocmd FileType python setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76
 
+  " [rust]
+  autocmd FileType rs setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=76
+
+  " [shellscript]
+  autocmd FileType sh,bash,zsh setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2 colorcolumn=60,76
+
   " [toml]
   autocmd FileType toml setlocal noexpandtab tabstop=2 shiftwidth=2 softtabstop=2
 augroup END

.vscode/settings.json

@@ -5,6 +5,8 @@
 		"editor.tabSize": 4,
 	},
 	"[c]": {
+		"editor.defaultFormatter": "ms-vscode.cpptools",
+		"editor.formatOnSave": true,
 		"editor.insertSpaces": true,
 		"editor.rulers": [ 60, 64, 68, 72, 76 ],
 		"editor.tabSize": 4,
@@ -14,6 +16,8 @@
 		"editor.tabSize": 4,
 	},
 	"[cpp]": {
+		"editor.defaultFormatter": "ms-vscode.cpptools",
+		"editor.formatOnSave": true,
 		"editor.insertSpaces": true,
 		"editor.rulers": [ 60, 64, 68, 72, 76 ],
 		"editor.tabSize": 4,
@@ -49,7 +53,17 @@
 		"editor.insertSpaces": true,
 		"editor.tabSize": 2,
 	},
+	"C_Cpp.autocompleteAddParentheses": true,
+	"C_Cpp.clang_format_fallbackStyle": "none",
+	"C_Cpp.clang_format_style": "file",
+	"C_Cpp.default.cStandard": "c17",
+	"C_Cpp.default.cppStandard": "c++17",
+	"C_Cpp.enhancedColorization": "enabled",
+	"C_Cpp.errorSquiggles": "enabled",
+	"C_Cpp.formatting": "clangFormat",
+	"C_Cpp.intelliSenseEngine": "default",
 	"cmake.configureOnOpen": false,
+	"debug.allowBreakpointsEverywhere": true,
 	"editor.detectIndentation": false,
 	"editor.insertSpaces": false,
 	"editor.renderWhitespace": "all",
@@ -128,6 +142,7 @@
 		"numeric": "cpp",
 		"optional": "cpp",
 		"ostream": "cpp",
+		"print": "cpp",
 		"queue": "cpp",
 		"random": "cpp",
 		"ranges": "cpp",

CHANGES.md

@@ -1,4 +1,17 @@
-# **realpath** Changes <!-- omit in toc -->
+# realpath - Changes <!-- omit in toc -->
+
+
+## 0.1.1 - 23rd August 2026
+
+* Documented the Windows-only program, its **STLSoft** dependency, and its CMake build, installation, and testing workflows in **README.md** and **INSTALL.md**;
+* Added **REQUISITES.md** documenting required build tools, **STLSoft** configuration, Windows toolchains, and optional **Doxygen** support;
+* Clarified the Windows-only scope in **README.md**, including a usage example, project information, and a Windows badge;
+* Modernised source-control metadata in **.gitattributes** and editor configuration in **.vimrc** and **.vscode/settings.json**;
+* Updated **CMakeLists.txt** to preserve caller-selected C and C++ standards and report the configured build type;
+* Improved CMake helper scripts with safer path handling, project-aware diagnostics, configurable C standards, and coloured status messages;
+* Replaced the POSIX Doxygen helper with the Windows **generate_doxygen.cmd** script;
+* Updated GitHub Actions push-branch coverage by removing the obsolete `version` branch and retaining the standard development and release branches;
+* Corrected release information in **NEWS.md** and updated the outstanding work in **TODO.md**;
 
 
 ## 0.1.0 - 16th August 2026

CMakeLists.txt

@@ -56,10 +56,16 @@ set(PROJECT_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT
 
 # adhere strictly to C and C++ standards plus extensions. These are actually
 # useless since we do not compile anything; they merely state our intention.
-set(CMAKE_C_STANDARD 17)
+if(NOT CMAKE_C_STANDARD)
+
+	set(CMAKE_C_STANDARD 17)
+endif()
 set(CMAKE_C_STANDARD_REQUIRED ON)
 set(CMAKE_C_EXTENSIONS ON) # GNU extensions and POSIX standard
-set(CMAKE_CXX_STANDARD 17)
+if(NOT CMAKE_CXX_STANDARD)
+
+	set(CMAKE_CXX_STANDARD 17)
+endif()
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS ON)
 
@@ -227,7 +233,7 @@ endif(BUILD_TESTING)
 # ##########################################################
 # completion
 
-message(NOTICE "Generating CMake build scripts for ${PROJECT_NAME} ${PROJECT_VERSION}, for C${CMAKE_C_STANDARD} C++${CMAKE_CXX_STANDARD}")
+message(NOTICE "Generating CMake build scripts for ${PROJECT_NAME} ${PROJECT_VERSION}, for C${CMAKE_C_STANDARD} C++${CMAKE_CXX_STANDARD}, with build type ${CMAKE_BUILD_TYPE}")
 
 
 # ############################## end of file ############################# #

INSTALL.md

@@ -1,6 +1,118 @@
 # realpath - Installation and Use <!-- omit in toc -->
 
 
+- [Requisites](#requisites)
+- [Building](#building)
+  - [via CMake](#via-cmake)
+- [Requisites](#requisites-1)
+- [Building](#building-1)
+- [Installing](#installing)
+- [Testing](#testing)
 
-<!-- ########################### end of file ########################### -->
 
+## Requisites
+
+**realpath** is a **Windows-only** program (implemented in [**realpath.cpp**](./realpath.cpp)) and depends on:
+
+* [**STLSoft**](https://github.com/synesissoftware/STLSoft) (1.11+) - **WinSTL** absolute-path and error-description components;
+
+
+## Building
+
+
+### via CMake
+
+The primary choice for installation is by use of **CMake** on Windows.
+
+1. Obtain the latest distribution of **realpath**, from
+   https://github.com/sistools/realpath/, e.g.
+
+    ```bash
+    $ mkdir -p ~/open-source
+    $ cd ~/open-source
+    $ git clone https://github.com/sistools/realpath/
+    ```
+
+2. Prepare the CMake configuration, via the **prepare_cmake.sh** script, as
+   in:
+
+    ```bash
+    $ cd ~/open-source/realpath
+    $ ./prepare_cmake.sh
+    ```
+
+   (**NOTE**: configuring on a non-Windows host fails: the tool targets
+   Windows only.)
+
+3. Run a build of the generated **CMake**-derived build files via the
+   **build_cmake.sh** script, as in:
+
+    ```bash
+    $ cd ~/open-source/realpath
+    $ ./build_cmake.sh
+    ```
+
+   (**NOTE**: if you provide the flag `--run-make` (=== `-m`) in step 2 then you do
+   not need this step.)
+
+4. As a check, execute the built program, as in:
+
+    ```bash
+    $ cd ~/open-source/realpath
+    $ ./_build/realpath --help
+    ```
+
+5. Finally, if you wish to do so, you can install the tool on the host, via `cmake`, as in:
+
+    ```bash
+    $ cd ~/open-source/realpath
+    $ cmake --install ./_build --config Release
+    ```
+
+
+## Requisites
+
+**realpath** requires:
+
+* [**STLSoft**](https://github.com/synesissoftware/STLSoft), version 1.11.1
+  or later;
+* CMake 3.20 or later;
+* a Windows C/C++ toolchain supported by CMake.
+
+
+## Building
+
+The primary build method is CMake. From PowerShell:
+
+```powershell
+git clone https://github.com/sistools/realpath.git
+Set-Location realpath
+cmake -S . -B _build
+cmake --build _build --config Release
+```
+
+The resulting executable is `_build/Release/realpath.exe`.
+
+
+## Installing
+
+To install into a user-local directory:
+
+```powershell
+cmake --install _build --config Release --prefix "$env:LOCALAPPDATA\Programs\realpath"
+```
+
+The installed executable is placed in the `bin` directory beneath the
+selected prefix.
+
+
+## Testing
+
+Configure the project with `-DBUILD_TESTING=ON` to build its tests, then run:
+
+```powershell
+ctest --test-dir _build -C Release --output-on-failure
+```
+
+
+<!-- ########################### end of file ########################### -->

NEWS.md

@@ -3,7 +3,8 @@
 
 | Date                 | News Item        |
 | -------------------- | ---------------- |
-| 16ht August 2026     | [0.1.0 released](https://github.com/sistools/realpath/releases/tag/0.0.3) |
+| 23rd August 2026     | [0.1.1 released](https://github.com/sistools/realpath/releases/tag/0.1.1) |
+| 16th August 2026     | [0.1.0 released](https://github.com/sistools/realpath/releases/tag/0.1.0) |
 | 3rd August 2026      | 0.0.3 released   |
 | 4th May 2025         | 0.0.2 released   |