document

# Document Rules Documentation style varies by type. Follow these principles for consistency. ## Specification Documents (`docs/specification/`) **Purpose:** Formal mathematical reference for constitutions, geometries, and core concepts. **Rules:** - Use LaTeX math (`$$` for display, `$` for inline) extensively - Define all variables after formulas - Prefer math over code examples - Structure: Definition → State Variables → Formulations → Energy Functions - Use numbered sections: `## #12 Hookean Spring` - Reference academic papers when applicable - Include parameter ranges: "$100MPa \le \kappa \le 100GPa$" - Explain notation: "where $\|\cdot\|_F$ is the Frobenius norm" - Cross-reference: `[link text](./file.md)` - Include diagrams (SVG): `` **Example:** ```markdown # Hookean Spring **Hookean Spring** is a constitutive model for simulating linear elastic springs. ## #12 Hookean Spring $$ E = \frac{\kappa}{2} \epsilon^2 = \frac{\kappa}{2} \left(\frac{L - L_0}{L_0}\right)^2 $$ where: - $\kappa$ is the spring constant - $L_0$ is the rest length ``` ## Tutorial Documents (`docs/tutorial/`) **Purpose:** User-friendly guides with code examples. **Rules:** - Always provide both C++ and Python using tabs: ```markdown === "C++" \`\`\`cpp // code \`\`\` === "Python" \`\`\`python # code \`\`\` ``` - Include complete, runnable examples with imports - Start high-level, progress to details - Use diagrams: `` - Include step-by-step workflows - Use tables for structured data **Example:** ```markdown === "C++" \`\`\`cpp using namespace uipc::core; Scene scene; \`\`\` === "Python" \`\`\`python from uipc.core import * scene = Scene() \`\`\` ``` ## Reference Documents (`docs/specification/*_uid.md`) **Purpose:** Technical reference for identifiers and ranges. **Rules:** - Define identifier ranges clearly - Distinguish official vs. user-defined ranges - List all official identifiers - Cross-reference to detailed specs **Example:** ```markdown # Constitution UID 64-bit unsigned integer. Official range: $[0, 2^{32}-1]$. User-defined: $[2^{32}, 2^{64}-1]$. ``` ## Build/Install Documents (`docs/build_install/`) **Purpose:** Step-by-step build instructions. **Rules:** - Use prerequisites table with versions and links - Number steps clearly - Include verification commands - Use shell tags: `shell`, `bash`, `powershell` - Show copy-pasteable commands **Example:** ```markdown | Name | Version | Usage | Import | |------|---------|-------|--------| | [CMake](https://cmake.org/) | >=3.26 | build system | system install | \`\`\`shell git clone https://github.com/microsoft/vcpkg.git \`\`\` ``` ## General Rules - **Math:** `$$` for display, `$` for inline. Define variables after formulas. Use bold for vectors: $\mathbf{x}$ - **Code:** Appropriate language tags. Complete, runnable examples. C++/Python tabs in tutorials - **Links:** Relative paths `[text](./file.md)`. Link to related docs and external resources - **Media:** Store in `media/` subdirectories. Use SVG. Reference: `` - **Tables:** Markdown tables with headers for structured data - **Headers:** `#` title, `##` sections, `###` subsections ## Checklist - [ ] Formulas use LaTeX, variables defined - [ ] Code examples complete and runnable - [ ] Cross-references use relative paths - [ ] Images exist and are referenced - [ ] Tables formatted correctly - [ ] Document type principles followed - [ ] No ambiguity in technical descriptions