From 002ab9094f638c46d5db95d478e71c10933aceb2 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 9 Feb 2026 18:37:38 +0100
Subject: docs: Condense HOWTO.md, move details to technical docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- HOWTO.md: 184→97 lines (quick reference only)
- BUILD.md: Add build modes, header organization, dependency tracking
- ASSET_SYSTEM.md: Add developer workflow section
- TRACKER.md: Add AudioEngine API documentation

Net: -147 lines in HOWTO.md
---
 doc/HOWTO.md | 184 ++++++++++++-----------------------------------------------
 1 file changed, 37 insertions(+), 147 deletions(-)

(limited to 'doc/HOWTO.md')

diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index fa3395a..9e32a86 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -1,6 +1,6 @@
 # How To
 
-Common commands for building and testing.
+Quick reference for common tasks.
 
 ---
 
@@ -12,195 +12,85 @@ cmake -S . -B build
 cmake --build build -j4
 ./build/demo64k
 ```
+Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload`
 
-Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload` (debug only)
-
-Keyboard: `Esc` (exit), `F` (toggle fullscreen)
-
-**Hot-Reload Mode:**
+### Production Builds
 ```bash
-./build/demo64k --hot-reload
-```
-Watches config files and notifies when changes detected. See `doc/HOT_RELOAD.md`.
+# Size-optimized (development)
+cmake -B build -DDEMO_SIZE_OPT=ON && cmake --build build -j4
 
-### Size-Optimized Build
-```bash
-cmake -S . -B build -DDEMO_SIZE_OPT=ON
-cmake --build build -j4
-```
-
-### Strip Build (64k Target)
-```bash
-cmake -S . -B build -DDEMO_STRIP_ALL=ON
-cmake --build build -j4
-```
-Always starts in fullscreen. Full error checking enabled.
+# 64k target (full checks, no debug)
+cmake -B build -DDEMO_STRIP_ALL=ON && cmake --build build -j4
 
-### Final Build (Maximum Stripping)
-```bash
+# Final release (no checks, absolute minimum)
 ./scripts/build_final.sh
-# or
-cmake -S . -B build_final -DDEMO_FINAL_STRIP=ON
-cmake --build build_final -j4
 ```
-⚠️ Removes ALL error checking. Use only for final release.
-
-**Build Hierarchy:**
-- Debug: Full checks + debug features
-- STRIP_ALL: Full checks, no debug (~64k target)
-- FINAL_STRIP: No checks, no debug (absolute minimum)
 
-### Developer Build (Tests + Tools)
+### Developer Build
 ```bash
-cmake -S . -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
+cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
 cmake --build build -j4
 ```
 
-**Note:** `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`, which removes debug-only code. Use selective flags for debugging.
-
-### Size Measurement Build
+### Size Measurement
 ```bash
 ./scripts/measure_size.sh
 ```
-Measures demo code size by stubbing external libraries (wgpu/GLFW/miniaudio). Binary compiles but **does NOT run**.
-
-**Manual:**
-```bash
-cmake -S . -B build_size -DDEMO_STRIP_EXTERNAL_LIBS=ON
-cmake --build build_size -j4
-strip build_size/demo64k
-ls -lh build_size/demo64k
-```
-
-**Typical results:** Demo=4.4MB (69%), External=2.0MB (31%)
-
-See `doc/SIZE_MEASUREMENT.md` for details.
+Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`.
 
 ---
 
-## Build System
-
-**Dependency Tracking:** CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild.
+## Testing
 
-**Header Organization:**
-- `asset_manager_dcl.h`: Forward declarations
-- `asset_manager.h`: Core API (GetAsset/DropAsset)
-- `asset_manager_utils.h`: Typed helpers
+```bash
+cmake -B build -DDEMO_BUILD_TESTS=ON
+cmake --build build -j4
+cd build && ctest
+```
 
 ---
 
-## Git Clone
-```bash
-git clone ssh://git@51.38.51.127/~/demo.git
+## Timeline
+
+Edit `assets/demo.seq`:
+```text
+SEQUENCE 0.0 0
+  EFFECT HeptagonEffect 0.0 60.0 0
 ```
+Rebuild to apply. See `doc/SEQUENCE.md`.
 
 ---
 
-## Audio System
+## Audio
 
-### AudioEngine API
 ```cpp
 #include "audio/audio_engine.h"
 
 audio_init();
 static AudioEngine g_audio_engine;
 g_audio_engine.init();
-
-// Main loop
 g_audio_engine.update(music_time);
-
 g_audio_engine.shutdown();
 audio_shutdown();
 ```
-
-**Methods:**
-- `init()`: Initialize synth + tracker
-- `update(music_time)`: Update music state
-- `shutdown()`: Cleanup
-- `seek(time)`: Jump to timestamp (debug only)
-
-**Direct Synth APIs** (performance-critical):
-- `synth_register_spectrogram()`, `synth_trigger_voice()`, `synth_get_output_peak()`, `synth_render()`
-
-**Testing:**
-```cpp
-AudioEngine engine;
-engine.init();
-engine.update(1.0f);
-engine.shutdown();
-```
-
----
-
-## Auxiliary Texture Masking
-
-Share textures between effects:
-```cpp
-// Generator effect
-demo->register_auxiliary_texture("mask_name", width, height);
-WGPUTextureView view = demo_->get_auxiliary_view("mask_name");
-
-// Consumer effect
-WGPUTextureView view = demo_->get_auxiliary_view("mask_name");
-```
-See `doc/MASKING_SYSTEM.md` for details.
-
----
-
-## Demo Timeline
-
-Edit `assets/demo.seq`:
-```text
-SEQUENCE 0.0 0
-  EFFECT HeptagonEffect 0.0 60.0 0
-```
-Rebuild to update timeline.
-
----
-
-## Testing
-
-**Run all tests:**
-```bash
-cmake -S . -B build -DDEMO_BUILD_TESTS=ON
-cmake --build build -j4
-cd build && ctest
-```
-
-**Key tests:**
-- `HammingWindowTest`: Window function properties
-- `MathUtilsTest`: Math utilities
-- `SynthEngineTest`: Audio synthesis
-- `SequenceSystemTest`: Timeline logic
+See `doc/TRACKER.md` for music system.
 
 ---
 
-## Asset Management
+## Assets
 
-### Define Assets
-Edit `assets/final/demo_assets.txt`:
-```
-KICK_1, kick1.spec, NONE, "Drum kick"
-```
-
-### Regenerate
+Edit `assets/final/demo_assets.txt`, then:
 ```bash
 ./scripts/gen_assets.sh
 ```
-Converts WAV → .spec, packs into C++ arrays.
-
-### Use Assets
-```cpp
-#include "assets.h"
-
-size_t size;
-const uint8_t* data = GetAsset(AssetId::KICK_1, &size);
-// Use data...
-// DropAsset(AssetId::KICK_1, data);  // For compressed assets only
-```
-
-Build system auto-runs `asset_packer` when asset lists change.
+See `doc/ASSET_SYSTEM.md`.
 
 ---
 
-For developer tools reference (spectool, Windows cross-compilation, code coverage), see `doc/TOOLS_REFERENCE.md`.
+## Additional Documentation
+
+- **Build System:** `doc/BUILD.md` - Multi-platform, size optimization
+- **Tools:** `doc/TOOLS_REFERENCE.md` - spectool, coverage, Windows cross-compile
+- **Shaders:** `doc/SEQUENCE.md` - Timeline format, shader parameters
+- **3D:** `doc/3D.md` - Hybrid rendering, scene format
+- **Hot Reload:** `doc/HOT_RELOAD.md` - Debug file watching
-- 
cgit v1.2.3