Improve documentation (#730)

- Rework navigation among the multiple Doxygen projects for much easier use.
- Rename new ktx tool man pages from `ktxtools_*` to `ktx_*`
- Add `ktx` tool mainpage based on RELEASE_NOTES info.
- Make minor formatting fix in `ktx` man page.
- Update acknowledgements.
- Remove outdated TODO.md.
- Add script to do `$Date$` keyword smudging. Use it in CI and reference it from
  README.md to avoid repetition of list of files needing smudging.
- Add `$Date$` keywords to some docs.
- Remove `$Date$` and #ident keywords that are no longer needed or used.
- Document the parts of `khr_df.h` relevant to the libktx API.

.gitattributes

@@ -41,19 +41,14 @@ mkversion eol=lf
 GNUmakefile eol=lf
 
 # Keyword expansion
-GNUmakefile ident
-TODO.md filter=keyworder
-lib/*.[ch] ident
-lib/*.cxx ident
-lib/mainpage.md filter=keyworder
+interface/js_binding/ktx_wrapper.cpp filter=keyworder
+lib/libktx_mainpage.md filter=keyworder
 pkgdoc/pages.md filter=keyworder
+tools/ktxtools_mainpage.md filter=keyworder
 tests/loadtests/common/at.[ch] ident
 tests/loadtests/common/egltowgl.c ident
 tests/loadtests/gles1/*.c ident
 tests/loadtests/shader-based/*.c ident
-tools/ktx2ktx2/ktx2ktx2.cpp ident
-tools/ktxinfo/ktxinfo.cpp ident
-tools/toktx/toktx.cpp filter=keyworder ident
 
 # LFS attributes
 *.a filter=lfs -text

.github/workflows/windows.yml

@@ -167,6 +167,12 @@ jobs:
  distribution: 'temurin'
  java-version: '17'
 
+ - name: Smudge embedded dates
+ if: matrix.options.doc == 'ON'
+ run: |
+ ./install-gitconfig.ps1
+ ci_scripts/smudge_date.ps1
+
  - name: Build Windows
  # The installers run as part of "Install Dependencies" add
  # environment variables to the registry and augment $Path there.

.reuse/dep5

@@ -151,7 +151,7 @@ Copyright: 2020 Andreas Atteneder
 License: Apache-2.0
 
 Files: pkgdoc/*
-Copyright: 2018-2020 The Khronos Group Inc.
+Copyright: 2018-2023 The Khronos Group Inc.
 License: Apache-2.0
 
 Files: tests/webgl/libktx-gltf/*

.travis.yml

@@ -232,9 +232,7 @@ before_script:
  esac
  # Make sure embedded dates are correct.
  - ./install-gitconfig.sh
- - rm TODO.md lib/mainpage.md pkgdoc/pages.md tools/toktx/toktx.cc
- - git checkout TODO.md lib/mainpage.md pkgdoc/pages.md tools/toktx/toktx.cc
- - git status
+ - ci_scripts/smudge_date.sh
 
 script:
 - |

BUILDING.md

@@ -303,7 +303,7 @@ The CMake generators for Visual Studio 2017 and earlier generate projects whose
 ```bash
 # -G shown for completeness. Not needed if you are happy
 # with the CMake's default selection.
-cmake -G "Visual Studio 15 2017" -B build -A x64 .
+cmake -G "Visual Studio 17 2022" -B build -A x64 .
 ```
 
 When using a more recent Visual Studio you simply need
@@ -431,14 +431,18 @@ Conformance Test Suite
 The submodule of [CTS Repository](https://github.com/KhronosGroup/KTX-Software-CTS/) is optional and
 only required for running the CTS tests during KTX development. If the CTS test suit is desired it
 can be fetched during cloning with the additional `--recurse-submodules` git clone flag:
+
 ```bash
 git clone --recurse-submodules git@github.com:KhronosGroup/KTX-Software.git
 ```
+
 If the repository was already cloned or whenever the submodule ref changes the submodule has to be
 updated with:
+
 ```bash
 git submodule update --init --recursive tests/cts
 ```
+
 (For more information on submodules see the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules).)
 
 Once the submodule is fetched the CTS tests can be enabled with the `KTX_FEATURE_TOOLS_CTS`
@@ -448,6 +452,7 @@ The CTS integrates into `ctest` so running `ctest` will also execute the CTS tes
 The test cases can be limited to the CTS tests with `ctest -R ktxToolTests`.
 
 Example for development workflow with CTS testing:
+
 ```bash
 # Git clone and submodule fetch 
 git clone git@github.com:KhronosGroup/KTX-Software.git

README.md

@@ -6,9 +6,9 @@
 The Official Khronos KTX Software Repository
 ---
 
-| GNU/Linux, iOS, macOS & wasm | Windows | Android | Mingw | Documentation |
-| :--------------------------: | :-----: | :-----: | :---: | :-----------: | 
-| ![Build Status](https://travis-ci.com/KhronosGroup/KTX-Software.svg?branch=main) | ![Build status](https://github.com/KhronosGroup/KTX-Software/actions/workflows/windows.yml/badge.svg) | ![KTX-Software CI](https://github.com/KhronosGroup/KTX-Software/actions/workflows/android.yml/badge.svg) | ![KTX-Software CI](https://github.com/KhronosGroup/KTX-Software/actions/workflows/mingw.yml/badge.svg) | ![Build status](https://codedocs.xyz/KhronosGroup/KTX-Software.svg)|
+| GNU/Linux, iOS, macOS & wasm | Windows | Android | Mingw |
+| :--------------------------: | :-----: | :-----: | :---: |
+| ![Build Status](https://travis-ci.com/KhronosGroup/KTX-Software.svg?branch=main) | ![Build status](https://github.com/KhronosGroup/KTX-Software/actions/workflows/windows.yml/badge.svg) | ![KTX-Software CI](https://github.com/KhronosGroup/KTX-Software/actions/workflows/android.yml/badge.svg) | ![KTX-Software CI](https://github.com/KhronosGroup/KTX-Software/actions/workflows/mingw.yml/badge.svg) |
 
 This is the official home of the source code for the Khronos KTX library and tools.
 
@@ -100,22 +100,21 @@ Windows' Git Bash or Cygwin's bash terminal:
 
 ```bash
 ./install-gitconfig.sh
-rm TODO.md lib/mainpage.md pkgdoc/pages.md tools/toktx/toktx.cc
-git checkout TODO.md lib/mainpage.md pkgdoc/pages.md tools/toktx/toktx.cc
+./ci_scripts/smudge_date.sh
 
 ```
 
-On Windows with the Command Prompt (requires `git.exe` in a directory
+On Windows PowerShell (requires `git.exe` in a directory
 on your %PATH%):
 
-```cmd
-install-gitconfig.bat
-del TODO.md TODO.md lib\mainpage.md pkgdoc\pages.md tools\toktx\toktx.cc
-git checkout TODO.md lib\mainpage.md pkgdoc\pages.md tools\toktx\toktx.cc
+```ps1
+install-gitconfig.ps1
+./ci_scripts/smudge_date.ps1
 ```
 
 The first command adds an [include] of the repo's `.gitconfig` to the
 local git config file `.git/config`, i.e. the one in your clone of the repo.
-`.gitconfig` contains the config of the "keyworder" filter. The remaining
-commands force a new checkout of the affected files to smudge them with the
-date. These two are unnecessary if you plan to edit these files.
+`.gitconfig` contains the config of the "keyworder" filter. The script in
+the second command forces a new checkout of the affected files to smudge them
+with their last modified date. This is unnecessary if you plan to edit
+these files.

ci_scripts/smudge_date.ps1

@@ -0,0 +1,24 @@
+# Copyright 2023 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# Smudge all files with proper $Date$ values.
+
+# Make sure we're in the repo root
+$path=(split-path $MyInvocation.MyCommand.Path -Parent)
+echo $path
+cd $path/..
+
+$target_files = @(
+ 'pkgdoc/pages.md'
+ 'lib/libktx_mainpage.md'
+ 'tools/ktxtools_mainpage.md'
+ 'interface/js_binding/ktx_wrapper.cpp'
+)
+
+#foreach ($file in $target_files) {
+# rm $file
+# git checkout $file
+#}
+rm $target_files
+git checkout $target_files
+

ci_scripts/smudge_date.sh

@@ -0,0 +1,26 @@
+#! /usr/bin/env bash
+# Copyright 2023 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# Smudge all files with proper $Date$ values.
+
+# Exit if any command fails.
+set -e
+
+# Make sure we're in the repo root
+cd $(dirname $0)/..
+
+
+target_files=(pkgdoc/pages.md
+ lib/libktx_mainpage.md
+ tools/ktxtools_mainpage.md
+ interface/js_binding/ktx_wrapper.cpp
+)
+
+#for file in "${target_files[@]}"; do
+# rm $file
+# git checkout $file
+#done
+rm "${target_files[@]}"
+git checkout "${target_files[@]}"
+