# Documentation Plan The documentation tree in `Docs/` is treated as a first-class deliverable. This page is the central roadmap, conventions reference, and pending-work tracker for that effort. For finished work, see the two indexes: - [User Index](User/_Index.md) — every end-user-facing guide - [Technical Index](Technical/_Index.md) — every contributor / developer reference --- ## Goals 1. **Two audiences, one source tree.** Anything a lay user might read lives under `Docs/User/`. Anything that assumes you know what a `csproj` is lives under `Docs/Technical/`. The split is enforced by directory location and audience voice, *not* by separate authoring tooling. 2. **Pour on the examples.** Both user and technical docs are example-heavy. A formula without a worked example is a missed teaching opportunity. A UI feature without a screenshot is a description the reader still has to imagine. 3. **Cite everything.** Mathematical facts, algorithms, and historical claims all link to [Resources & Bibliography](Resources-Bibliography.md). 4. **One file, two surfaces.** Each Markdown source renders inside the in-app Help viewer ([HelpMarkdownRenderer in `UI.Avalonia/ViewModels/HelpViewerViewModel.cs`](../UI.Avalonia/ViewModels/HelpViewerViewModel.cs)) *and* gets converted by [`Tools/DocSiteGen`](../Tools/DocSiteGen) into a static HTML site under `Docs/site/`. No content lives in only one of those surfaces. 5. **History preserved.** Older notes are kept in place as archival paragraphs. Errors get corrected with a `[!NOTE]` callout instead of being silently rewritten. --- ## Layout ``` Docs/ ├── Documentation-Plan.md ← this file ├── Resources-Bibliography.md ← shared citation file ├── _Index.md (TBD — top-level landing for both audiences) ├── User/ │ ├── _Index.md ← lay-person hub │ ├── Avalonia-UserGuide.md │ ├── CalcGen-UserGuide.md │ ├── Capture-Guide.md │ ├── ClientServer-UserGuide.md │ ├── ColorGen-UserGuide.md │ ├── ColorThemeEditor-Guide.md │ ├── Keyboard-Shortcuts.md │ ├── FracturingFog-Keyboard-shortcuts.txt │ ├── Regions-Guide.md │ ├── ServerAdmin-Guide.md │ ├── Slideshow-AudioReactive-Guide.md │ └── UserBulb-Guide.md ├── Technical/ │ ├── _Index.md ← developer hub │ ├── Architecture-Overview.md │ ├── CalculatorGen-Architecture.md │ ├── CalculatorGen-Authoring.md │ ├── CalculatorGen-Roadmap.md │ ├── CrossPlatform-Roadmap.md │ ├── FractalEquation-DesignGuide.md │ ├── Performance-DevelopmentPlan.md │ ├── UserBulb3D-DevelopmentPlan.md │ └── UserBulbSandbox-DevPlan.md ├── Images/ ← see Docs/Images/README.md for capture protocol │ ├── _placeholders/ │ ├── diagrams/ │ ├── dialogs/ │ ├── examples/ │ └── fractals/ └── site/ ← generated by Tools/DocSiteGen (not committed by default) ``` --- ## Authoring conventions ### Markdown subset The in-app HelpMarkdownRenderer understands a focused subset of CommonMark plus a couple of GFM extensions. The static-site generator uses Markdig with the full AdvancedExtensions pipeline, so *anything* recognised by the renderer is recognised by the site — but only the renderer's subset ships into the live app. | Construct | In-app | Static site | |----------------------------|:------:|:-----------:| | Headings (`#`, `##`, `###`, `####`) | yes | yes | | Paragraphs | yes | yes | | **Bold** / *italic* | yes | yes | | `inline code` | yes | yes | | ```` ```fenced code``` ```` | yes | yes | | Bullet lists (`-`, `*`) | yes | yes | | Ordered lists (`1.`) | yes | yes | | Pipe tables | yes | yes | | Blockquote (`>`) | yes | yes | | Callouts (`> [!NOTE]`) | yes | yes (rendered as styled blockquote) | | Horizontal rule (`---`) | yes | yes | | Images (`![](path)`) | yes | yes | | Links (`[label](url)`) | yes | yes | | Inline LaTeX (`$x$`) | yes — source rendered styled | yes — KaTeX typeset | | Block LaTeX (`$$x$$`) | yes — source rendered styled | yes — KaTeX typeset | | Footnotes (`[^id]`) | partial — kept as text | yes | | Task lists (`- [ ]`) | partial — kept as text | yes | > [!NOTE] > Anything not in the in-app column degrades gracefully — it still appears as plain text inside the > embedded viewer, just unstyled. The web export is always richer. ### Voice - **User docs:** speak to a curious novice. Define every term the first time it appears. Replace jargon with plain words whenever the meaning survives. *Do not dumb down*; explain. - **Technical docs:** speak to a peer. Assume working knowledge of .NET, C#, Markdown, git. Lean into precision: cite, show full code blocks, prefer truth to brevity. Be verbose. ### Callout types ```markdown > [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] ``` Choose by intent, not severity: - `NOTE` — neutral aside the reader can skip without losing the thread. - `TIP` — friendly shortcut or "did you know" moment. - `IMPORTANT` — load-bearing detail; ignore at your peril. - `WARNING` — destructive or irrecoverable action ahead. > [!WARNING] > The renderer uses **yellow** for warnings — never red. The project owner is red/green colour-blind, > and the yellow `#FFCC00` accent is the canonical alert hue across every dialog and overlay in the > app. Stay consistent. ### LaTeX Block formulas: ```markdown $$ z_{n+1} = z_n^2 + c $$ ``` Inline formulas: `the bailout test $|z| > 2$ follows from …`. The static site runs [KaTeX auto-render](https://katex.org/docs/autorender.html) with `$..$` and `$$..$$` delimiters; the in-app viewer keeps the raw source in a code-styled span so users can copy-paste it. ### Images See [`Docs/Images/README.md`](Images/README.md) for the capture protocol. Always reference relative paths so the static site and the in-app viewer resolve them identically: ```markdown ![Mandelbrot — Seahorse Valley at zoom 1e4](../Images/fractals/mandelbrot-seahorse.png) ``` If the image does not exist yet, use the placeholder + add a row to [Pending Image Captures](#pending-image-captures) below. --- ## Building the static site ```powershell dotnet run --project Tools/DocSiteGen ``` This produces `Docs/site/index.html` and one HTML page per source `.md`. Open `index.html` directly in a browser; no web server required. When the site is published to GitHub Pages the URL is `https://.github.io/FracturingFog/site/` (adjust to the actual deployment). > [!TIP] > The static-site output is **not committed** by default — it is build artefact. If you want to > ship pre-built pages, add `Docs/site/` to source control after a clean run. --- ## Pending work ### Pending User-guide rewrites (Phase B) | Doc | Status | |-------------------------------------------|------------------------------------------------| | User/Avalonia-UserGuide.md | Existing — re-write in lay voice in progress. | | User/Capture-Guide.md | Existing — needs worked examples + visuals. | | User/Regions-Guide.md | Existing — needs worked examples + visuals. | | User/ColorThemeEditor-Guide.md | Existing — needs visual editor walk-through. | | User/ColorGen-UserGuide.md | Existing — needs DSL worked examples. | | User/CalcGen-UserGuide.md | Existing — needs equation worked examples. | | User/Slideshow-AudioReactive-Guide.md | Existing — needs music-source walkthrough. | | User/UserBulb-Guide.md | Existing — needs 3-D rendering visuals. | | User/ClientServer-UserGuide.md | Existing — needs setup screenshot sequence. | | User/ServerAdmin-Guide.md | Existing — minor wording polish only. | | User/Keyboard-Shortcuts.md | Existing — verify against current build. | ### Pending Technical-doc polish (Phase C) | Doc | Status | |-------------------------------------------|------------------------------------------------| | Technical/Architecture-Overview.md | Add LaTeX for QD threshold derivations. | | Technical/CalculatorGen-Architecture.md | Add ILGPU JIT path section. | | Technical/CalculatorGen-Authoring.md | Add full worked example: Tricorn. | | Technical/CalculatorGen-Roadmap.md | Verify dates, mark completed items. | | Technical/FractalEquation-DesignGuide.md | Add User Bulb 3D quat algebra section. | | Technical/Performance-DevelopmentPlan.md | Bring in line with GPU JIT staged feature work. | | Technical/CrossPlatform-Roadmap.md | Refresh after Skia smoke tests are green. | ### Per-dialog help (Phase D — landed 2026-06-11) Every Phase 2 / Phase 3 dialog now exposes a yellow `?` button. The button calls `HelpViewerLauncher.Show(this, docId, anchor, title)` (see [`UI.Avalonia/Views/HelpViewerLauncher.cs`](../UI.Avalonia/Views/HelpViewerLauncher.cs)) which opens `HelpViewerView` modeless on top of the dialog, pre-sliced to the right anchor. Already wired (Phase 2 / Phase 3 baseline): - UserEquationView → `User/CalcGen-UserGuide.md` - SandboxView → `User/Avalonia-UserGuide.md#Sandbox` - UserBulbView → `User/UserBulb-Guide.md` Phase D landed: - [x] AudioSettingsView → `User/Slideshow-AudioReactive-Guide.md#audio-reactive-engine` - [x] SlideshowSettingsView → `User/Slideshow-AudioReactive-Guide.md` - [x] VideoSettingsView → `User/Capture-Guide.md#video-zoom` - [x] ColorThemeEditorView → `User/ColorThemeEditor-Guide.md` - [x] ColorGenEditorView → `User/ColorGen-UserGuide.md` - [x] FFClientView → `User/ClientServer-UserGuide.md#first-time-server-setup` - [x] ServerAdminView → `User/ServerAdmin-Guide.md` - [x] FractalParamsView → `User/Avalonia-UserGuide.md#Params` - [x] WatermarkEditorView → `User/Avalonia-UserGuide.md#Watermark` ### Pending Image Captures Status column key: ✅ landed · 🟡 fractal render scripted (see batch recipe below) · ⬜ needs interactive capture. | Status | Image path | Used by | Capture spec | |--------|-------------------------------------------|-------------------------------------------------|----------------------------------------------| | ✅ | `Images/fractals/mandelbrot.png` | User/Avalonia-UserGuide.md, _Index.md | Home view, HSV palette, 1600×1000 | | ✅ | `Images/fractals/julia-default.png` | User/Avalonia-UserGuide.md | Reset, HSV palette, 1600×1000 | | ✅ | `Images/fractals/burningship.png` | User/Avalonia-UserGuide.md | Reset, HSV palette, 1600×1000 | | ✅ | `Images/fractals/tricorn.png` | User/Avalonia-UserGuide.md | Reset, HSV palette, 1600×1000 | | ✅ | `Images/fractals/newton.png` | User/Avalonia-UserGuide.md | Reset, HSV palette, 1600×1000 | | ✅ | `Images/fractals/mandelbulb.png` | User/UserBulb-Guide.md | Reset, "New 3D" Phong palette, 1600×1000 | | ✅ | `Images/diagrams/render-pipeline.svg` | Technical/Architecture-Overview.md | Toolchain dataflow | | ✅ | `Images/diagrams/precision-promotion.svg` | Technical/Architecture-Overview.md | SP → DD → QD threshold chart | | ✅ | `Images/dialogs/slideshow-settings.png` | User/Slideshow-AudioReactive-Guide.md | Default state, dark theme | | ✅ | `Images/dialogs/audio-settings.png` | User/Slideshow-AudioReactive-Guide.md | Default state | | ✅ | `Images/dialogs/color-theme-editor.png` | User/ColorThemeEditor-Guide.md | New theme, Gradient kind selected | | ✅ | `Images/dialogs/colorgen-editor.png` | User/ColorGen-UserGuide.md | New empty editor | | ✅ | `Images/dialogs/server-admin.png` | User/ServerAdmin-Guide.md | Started server, default limits | | ✅ | `Images/dialogs/ffclient-top.png` | User/ClientServer-UserGuide.md | FFClient panel 1 — vault status + connection list + cert path / password. | | ✅ | `Images/dialogs/ffclient-middle.png` | User/ClientServer-UserGuide.md | FFClient panel 2 — render preset through iteration field. | | ✅ | `Images/dialogs/ffclient-bottom.png` | User/ClientServer-UserGuide.md | FFClient panel 3 — video options through **Close** button. | | ⬜ | `Images/dialogs/scene-editor.png` | User/SceneEngine-UserGuide.md | Scene Editor with a 2-shot timeline + a camera keyframe row expanded. Reach via floating menu → **Edit Scene…**; load built-in "Bulb → Box". | #### Fractal batch-render recipe (reproducible) The six fractal renders above were produced from the headless `--batch` path: ```powershell dotnet build FracturingFogCLD.csproj -c Release dotnet run --project FracturingFogCLD.csproj -c Release --no-build -- ` --batch --mode image --fractal Mandelbrot --x -0.5 --y 0 --zoom 1.0 ` --theme HSV --width 1600 --height 1000 ` --out Docs\Images\fractals\mandelbrot.png ``` Swap `--fractal` / `--x` / `--y` / `--zoom` per row of `FractalViewState.SnapToFractalDefault` ([Abstractions/ViewState/FractalViewState.cs](../Abstractions/ViewState/FractalViewState.cs)). For Mandelbulb pass `--theme "New 3D"` instead of `HSV`. #### Dialog screenshot checklist (interactive) The six remaining captures need the running Avalonia shell. Standard prep for every shot: 1. `dotnet run --project FracturingFogCLD.csproj -c Release` — launches the Avalonia shell. 2. OS theme dark, Windows scaling **100 %**, no DPI virtualisation. 3. Snipping tool → **Window** snip mode crops cleanly to the chrome. 4. Save as PNG into `Docs/Images/dialogs/.png`. Per-dialog launch route: | Filename | How to reach it | |---------------------------|----------------------------------------------------------------------------------------------------------| | `slideshow-settings.png` | Floating menu → **Slideshow** → **Slideshow Settings**. Defaults loaded, no preset modified. | | `audio-settings.png` | Slideshow Settings → top-right **Audio…** button. Default device, beat counters at 0. | | `color-theme-editor.png` | Floating menu → **Theme** → **Edit Theme…** → click **New** → set Kind to *Gradient*. Empty stops list. | | `colorgen-editor.png` | Floating menu → **Theme** → **ColorGen Editor…**. Default seed DSL in the source pane. | | `server-admin.png` | Start the server with `--server --admin`, then capture the admin window after first heartbeat (~3 s). | | `ffclient-top.png` | Floating menu → **Remote** → **Open FFClient…**. Unlock vault, pick a saved connection so all top-half fields populate. Crop from window chrome down to the cert-password row. | | `ffclient-middle.png` | Same dialog instance. Crop from the render-preset row down through the iteration field. Slight overlap with the top crop is fine. | | `ffclient-bottom.png` | Same dialog instance. Crop from the video-options row down through the **Close** button. | ### Citation maintenance Run periodically (every release): - `npx markdown-link-check Docs/**/*.md` — flags dead bibliography links. - Re-check every URL in [Resources-Bibliography.md](Resources-Bibliography.md) once a year. - Verify every historical date claim in `Technical/UserBulb3D-DevelopmentPlan.md` and `Technical/CalculatorGen-Roadmap.md`. --- ## Maintenance log | Date | Change | |------------|---------------------------------------------------------------------| | 2026-06-11 | Initial pass: split User/Technical, added Documentation-Plan + Resources-Bibliography, upgraded HelpMarkdownRenderer (selectable text + images + LaTeX), introduced `Tools/DocSiteGen`. | | 2026-06-11 | Phase B: lay-voice "Friendly tour" prepends on all User guides. | | 2026-06-11 | Phase C: LaTeX derivations + extended worked examples on Architecture-Overview, CalculatorGen-Architecture (+ ILGPU section), CalculatorGen-Authoring (Tricorn walkthrough), FractalEquation-DesignGuide (quaternion algebra). Status banners on roadmaps. | | 2026-06-11 | Phase D: yellow `?` button wired on all 9 modeless dialogs via `HelpViewerLauncher` helper. | | 2026-06-11 | Phase F (partial): 6 fractal family PNGs + 2 architecture SVGs landed; 6 dialog screenshots queued with reproducible recipes. Placeholder refs replaced in `_Index.md`, `UserBulb-Guide.md`, `Avalonia-UserGuide.md`, `Architecture-Overview.md`. | | 2026-06-11 | Phase F (dialogs): 7 dialog screenshots captured (slideshow-settings, audio-settings, color-theme-editor, colorgen-editor, server-admin + FFClient top/middle/bottom). Wired into `Slideshow-AudioReactive-Guide.md`, `ColorThemeEditor-Guide.md`, `ColorGen-UserGuide.md`, `ServerAdmin-Guide.md`, `ClientServer-UserGuide.md`. | | 2026-06-11 | Phase F (worked examples): added `--bulb-power` + `--multibrot-exp` to batch CLI ([Batch/BatchOptions.cs](../Batch/BatchOptions.cs), [Batch/BatchRenderer.cs](../Batch/BatchRenderer.cs)). Rendered 5 examples: `mandelbulb-p4` / `mandelbulb-p12` (UserBulb-Guide triptych using existing `mandelbulb.png` as p=8), `multibrot-cubic` (CalcGen-UserGuide), `seahorse-sunset` (ColorThemeEditor-Guide), `tricorn-handtuned` + `tricorn-calcgen` pair (CalculatorGen-Authoring). Newton domain-colouring example dropped: Newton kernel ignores theme overrides — basin coloring is hard-wired RGB. Quaternion-slice example (FractalEquation-DesignGuide.md:112) deferred: needs UserBulb DSL preset, not batch CLI. | | 2026-06-11 | DocSiteGen: fixed 404s on every intra-doc link. Markdig preserved `.md` in href targets — browsers hit URLs the site never wrote. Two-part fix in `Tools/DocSiteGen/Program.cs`: regex rewrite of all `.md` hrefs → `.html` (preserves `#anchor`), plus a bare-name fallback that emits `../Technical/Foo.html` when a User/ page links bare `Foo.md` (and vice-versa). Mirrors the in-app HelpViewer's User/ ↔ Technical/ fallback so live and embedded views agree. | | 2026-06-11 | `PHASE2_AVALONIA_MIGRATION.md` moved from repo root to `Docs/Technical/` so DocSiteGen sees it and emits the page. Cross-ref in `Architecture-Overview.md` dropped the `../` prefix (same folder now). Code-comment refs in `HelpTextBundle.cs` / `FractalViewState.cs` / `CrossPlatform-Roadmap.md` left as bare filenames — they're prose, not links. Site emits 25 pages (was 24). | | 2026-07-04 | Scene Engine docs (S0–S8 shipped). Added `User/SceneEngine-UserGuide.md` (lay voice: preview-vs-export split, orbit camera, easing, transitions, tone-map, global tracks, export + CLI, troubleshooting) and `Technical/SceneEngine-Architecture.md` (module map, camera-track/spline/easing math, timeline cut model, offline frame plan + motion blur, extension recipes). Added four importable example Scenes under `Docs/Examples/Scenes/` (+ walkthrough `_Index.md`), region-free and JSON-validated. Added a Scene Engine citation block to `Resources-Bibliography.md` (Catmull-Rom, Reyes motion blur, dolly zoom, Reinhard/ACES). Wired all three doc indexes; queued one interactive capture (`scene-editor.png`). | | 2026-07-22 | Feature sweep for #54 (batch `--watermark` inverted to default-on, alias `--no-watermark`) and the GPU-compute / Series-Approximation / DD-BLA toggles (#57, #88). `Capture-Guide.md`: new "Watermark (on by default)" subsection under Batch CLI + cross-ref from §9. `Keyboard-Shortcuts.md`: added "Overlays & Toggles" (G/K/H/Shift+H/X/P/F1) and "Performance & Deep-Zoom Diagnostics" (`Ctrl+G` GPU, `Ctrl+Shift+A/S/D`) sections. `Avalonia-UserGuide.md` §16: new "GPU compute" subsection (Control Center checkbox, `Ctrl+G`, auto-fallback, in-shader SA). `FEATURES.md` §12.2: batch watermark-default note. | | 2026-07-22 | CalcGen / DesignGuide depth pass. Fixed the integer-power bound doc bug (`0..16` → **`0..64`**, matching `EquationParser.cs:151`) in `CalcGen-UserGuide.md` §2/§7 and the `CalculatorGen --help` string. Added a "Cookbook — end-to-end recipes" section to `CalcGen-UserGuide.md` (preview→promote, generate a compiled calculator, headless render of the pre-wired `Generated*` families with the new watermark default, `--bailout` for smooth transcendentals, keeping equations deep-zoomable) and clarified `--bailout` squares the radius. Added an "Author's pre-flight checklist — seeds, guards, and degeneracies" section to `FractalEquation-DesignGuide.md` consolidating the `z₀=0` singularity pitfalls (`1/z`, `log(0)`, linear `i*z`, `(z²+c)/(z+a)`, `conj`/`fold` order) plus a holomorphic "keep DE on" helper table. | | 2026-07-22 | UserBulb Quat + Sandbox wave parity (missed by the earlier sweeps). Source of truth: commit `acf0c52` (quat transcendentals in DSL; Quat math + escape contract) plus the Wave 4.4/4.5/4.6 Sandbox-GPU work in `UserBulbCalculator.cs`. `UserBulb-Guide.md`: **§4 Quat API** rewritten from 4 members to the full surface — constants (`One`/`Pi`/`HalfPi`/`QuatAxis`), `Pow`/`Sqrt`/`Exp`/`Log`/`Inverse`/`Scale`, and the complete trig / hyperbolic / inverse-trig / reciprocal families, with `Pow` algorithm split, the never-throw **escape contract**, and worked snippets. **§7 Backends** corrected — three GPU routes (Sandbox-quat analytic+numerical+Julia, Sandbox-vec analytic, legacy Roslyn triplex-power), KIFS CPU-only note. **§19 Sandbox DSL**: intro table (now Vec3+Quat, CPU+GPU), `.w` member access (§19.2/§19.3 grammar), Hamilton `*` and Quat `^` operator rules (§19.4), the 26 `q*` functions — `qvec`/`qmul`/`qpow`/`qconj` (structural) plus the 22 quaternion-algebra transcendentals `qexp`/`qlog`/`qsqrt`/`qinv` + trig/hyperbolic/inverse/reciprocal families (§19.5), corrected limitations (§19.8 — dropped the false "No Quat"/"No GPU" bullets, flagged the stale Compiler-combo label), decision table (§19.9), and a new **§19.10 quaternion cookbook** (6 GPU-translatable DSL recipes). Gallery example #8 cross-linked to §4/§19.10. `FractalEquation-DesignGuide.md` §0.4: NOTE cross-referencing the transcendental library + escape contract + Sandbox-GPU path. Verified against `Quat.cs`, `SandboxBulbExpression.cs`, `UserBulbSandboxGpuCompiler.cs`, `UserBulbCalculator.cs`, `UserBulbView.axaml`, `UserBulbViewModel.cs`. |