# Typst Documentation Authoring Guidelines

This document provides comprehensive authoring guidelines for the EID Wireless documentation written in Typst.

---

## 1. Voice and Tone

### General Approach
- **Technical but approachable**: Explain complex technical concepts clearly without oversimplifying
- **Use examples and analogies**: Concrete examples help readers understand abstract concepts
- **Direct and conversational**: Use second-person perspective and active voice when appropriate
- **Confident and authoritative**: The documentation presents established facts and proven principles

### Voice Characteristics
```typ
// Example of technical but approachable tone (from core.typ:25-27)
#callout(kind: "tip", label: "Key Point")[
  Stationary items only begin to fall when their $"age" + "id"$ is a multiple of $4$.
]
```

The documentation explains technical details clearly:
- Uses precise terminology ("stationary items," "mod 4 cycle")
- Provides context and explanation for why things work
- Avoids jargon without explanation

### Examples from the Documentation
The documentation frequently uses:
1. **Direct explanation**: "Recall that *any* entity spawning will increment the ID counter"
2. **Examples with concrete scenarios**: Step-by-step walkthroughs of entity spawning
3. **Mathematical reasoning**: Clear derivation of relationships with mod arithmetic
4. **Practical implications**: "Therefore $B$ falls at time $t=2$"

---

## 2. Formatting Conventions

### Mathematical Notation
- Use `$...$` for inline math: `$"age"_(A, 1) = "age"_(A, 0) + 1$`
- Use `&` for alignment in multi-line equations
- Use `(mod N)` notation for modular arithmetic: `$... equiv 0 &(mod 4)$`

**Important**: The documentation uses a specific notation for modular arithmetic:
```typ
$ "age"_(A, 0) + 1 + "id"_A & equiv 0 (mod 4) $
```

### Code Blocks
- Use triple backticks with language specifier: ```` ```mc-diorama` ``
- The documentation defines a custom diorama format for Minecraft diagrams
- Java code blocks use: ```` ```java ````

**Example from core.typ:41-67**:
```java
public class ItemEntity extends Entity {
  public void tick() {
    ...
    if (this.onGround() && !(this.getDeltaMovement().horizontalDistanceSqr() > (double)1.0E-5F) && (this.tickCount + this.getId()) % 4 != 0) {
      ...
    } else {
      this.move(MoverType.SELF, this.getDeltaMovement());
      ...
    }
    ...
  }
}
```

### Block References
- Use `@symbol` syntax to reference sections: `@singleplayer`, `@paper`, `@tilesets`
- Use `@block-priority`, `@block-delay`, `@observer-bug` for subsections

### Section Headers
- Use `=` for level 1 headings (chapters): `= Core Mechanics`
- Use `==` for level 2 headings (sections): `== Entity IDs`
- Use `===` for level 3 headings (subsections): `=== Daylight Detector`

**Example from core.typ:3**:
```typ
= Core Mechanics <core>
== Entity IDs
```

The `<core>` syntax creates an anchor/ID for the section.

---

## 3. Interactive Elements (Dioramas)

### What is a Diorama?
A diorama is an interactive visualization of Minecraft redstone mechanisms. The documentation uses custom `mc-diorama` blocks that render as interactive HTML elements.

### Integration Syntax
Dioramas are integrated using the `#show` directive in `lib.typ`:

```typ
#show raw.where(lang: "mc-diorama"): it => diorama(
  autoplay: true,
  loop: true,
  radius: 5,
  theta: 25,
  phi: 25,
  it.text,
)
```

This directive tells Typst to:
1. Find all blocks with language `mc-diorama`
2. Wrap them in the `diorama()` function
3. Pass the block content as `it.text`

### Diorama Parameters
Common parameters include:
- `autoplay: true` - Start animation automatically
- `loop: true` - Repeat animation when finished
- `orbit: true` - Enable orbit camera controls
- `pan: true` - Enable pan camera controls
- `zoom: true` - Enable zoom controls
- `radius`, `theta`, `phi` - Camera position
- `speed` - Animation speed

**Example from tilesets.typ:15-23**:
```typ
#show raw.where(lang: "mc-diorama"): it => diorama(
  orbit: true,
  pan: true,
  zoom: true,
  autoplay: true,
  theta: 160,
  phi: 20,
  it.text,
)
```

### Diorama Content Format
Diorama content uses a custom format:
```
p x y z block_type properties
t time
```

Where:
- `p` = place/modify a block at coordinates
- `t` = advance time to specified tick
- Properties are space-separated key=value pairs

**Example from design.typ:17-49**:
```
p 0 0 0 smooth_stone_slab type=top
p 0 1 0 daylight_detector inverted=true power=1
p 0 2 0 piston facing=east extended=false
t 0
p 0 2 0 extended=true
t 1
p 0.5 2 0 piston_head facing=east short=true type=normal
```

### Timeline Format
The diorama uses a timeline-based animation system:
- `t N` advances the timeline to tick N
- Changes between ticks are interpolated
- Multiple changes can be made at the same tick

---

## 4. Stylistic Patterns

### Callouts
Callouts are defined in `lib.typ:1-10` and used extensively throughout the documentation:

```typ
#let callout(body, kind: none, label: none, outlined: false) = {
  html.section(
    class: ("callout", kind),
    context {
      let level = counter(heading).get().len() + 1
      heading(label + ":", level: level, numbering: none, outlined: outlined)
      body
    },
  )
}
```

#### Types of Callouts
1. **Tip**: `#tip[Content]` - Helpful suggestions or insights
2. **Note**: `#note[Content]` - Important information or clarifications
3. **Warning**: `#warn[Content]` - Critical warnings or cautions
4. **Todo**: `#todo[label, body]` - Notes for future work

### Example and Solution Blocks
These are currently implemented as TODO callouts but are planned to be proper elements:

```typ
#let example(body) = todo("example", body)
#let solution(body) = todo("solution", body)
```

**Example from core.typ:83-116**:
```typ
#example[
  For example, suppose we spawn an item $A$, then 2 game ticks later we spawn an item $B$...
  
  #solution[
    To simplify the arithmetic, orient everything around $t=0$...
  ]
]
```

### Details Block
The `details` function is defined but commented out, suggesting it's planned for expansion:

```typ
#let details(body, label: none) = {
  todo(label, body)
  // html.details({
  //   if label != none {
  //     html.summary(label)
  //   }
  //   body
  // })
}
```

### HTML Integration
The documentation uses HTML elements for interactive components:

**From design.typ:128-135**:
```typ
#html.div(id: "atlas-container", style: "position: fixed; left: 0; top: 0; border 1px solid white;")
#html.script(
  "
document.onreadystatechange = () => {
document.getElementById('atlas-container')?.appendChild(window.mcEngine.atlas.canvas)
}
",
)
```

---

## 5. Structuring Technical Explanations

### Problem → Solution Format
The documentation frequently follows this pattern:
1. Present the problem or phenomenon
2. Explain the underlying mechanism
3. Show the mathematical reasoning
4. Provide concrete examples
5. Draw conclusions

**Example from core.typ:77-227**:
```
== Observable Drop Delay
[Problem] We can't control absolute entity ID but can compare them
[Explanation] Use reference items to predict behavior
[Example 1] Simple two-item comparison with math derivation
[Example 2] Four-item scenario showing pattern recognition
[Example 3] Broken pattern analysis to determine entity spawns
```

### Mathematical Explanations
When explaining mathematics, the documentation uses:

1. **State the relation**: "$"age"_(A, 0) + 1 + "id"_A equiv 0 (mod 4)$"
2. **Substitute known values**: "Item $A$ has ID before $B$, so $"id"_A = "id"_B - 1$"
3. **Show derivation**: Multi-line equation with alignment
4. **State conclusion**: "*$A$ must fall at $t=0$.*"

**Example from core.typ:107-116**:
```
So take the relation for $A$ and substitute in these values for $B$.

$
          "age"_(A, 0) + 1 + "id"_A & equiv 0 (mod 4) \
  "age"_(B, 0) + 2 + 1 + "id"_B - 1 & equiv 0 (mod 4) \
          "age"_(B, 0) + 2 + "id"_B & equiv 0 (mod 4) \
$

Compare with the relation for $B$ and we see that $x=2$.

#callout(kind: "tip", label: "Therefore:")[$B$ falls at time $t=2$.
]
```

### Java Code Documentation
When showing Java code:

1. **Include only relevant sections**: Don't show entire classes, just the important parts
2. **Add context with notes**: Use `#note[]` to explain what code does
3. **Highlight key lines**: The documentation shows full code but focuses reader attention

**Example from core.typ:38-52**:
```typ
#note[ `onGround` is only ever updated via `move`, and this branch is the *only* place that
  `ItemEntity.move` is called. `tickCount` is the item's age. ]

```java
public class ItemEntity extends Entity {
  public void tick() {
    ...
    if (this.onGround() && !(this.getDeltaMovement().horizontalDistanceSqr() > (double)1.0E-5F) && (this.tickCount + this.getId()) % 4 != 0) {
      ...
    } else {
      this.move(MoverType.SELF, this.getDeltaMovement());
      ...
    }
    ...
  }
}
```
```

---

## 6. Relationship Between Text and Interactive Visualizations

### Dioramas as Explanatory Tools
Dioramas are not just decorative—they are integral to understanding:

1. **Before reading, see the phenomenon**: Dioramas show what happens first
2. **Then read the explanation**: Text explains why it happens
3. **Then verify understanding**: Readers can manipulate the diorama

**Pattern from tilesets.typ:15-56**:
```typ
#show raw.where(lang: "mc-diorama"): it => diorama(...)

```mc-diorama
p 0 -1 0 smooth_stone_slab type=top
p 1 -1 0 smooth_stone_slab type=top
... (animation showing tile sequence)
t 20
p 0 0 0
```
```

The diorama appears *before* the textual explanation, allowing readers to observe first.

### Text Supporting Visualization
Text always complements the diorama by:

1. **Explaining what to look for**: "Note how the redstone signal propagates in order"
2. **Providing context**: "This 4gt tileset demonstrates binary encoding"
3. **Giving the mathematical basis**: "We identify higher priority with 0, lower with 1"

### Multiple Perspectives
Complex concepts are shown from multiple angles:

**Example: Tilesets in tilesets.typ**
1. **Full diorama** showing the complete system (lines 15-56)
2. **Numeric representation** showing the encoding (lines 254-263)
3. **Abstract diagram** showing the bit pattern (line 268)
4. **Another diorama** showing arbitrary values (lines 270-297)

This multi-modal approach helps different learning styles.

### Interactive vs. Static
The documentation uses:
- **Autoplay loops** for demonstrating processes: `autoplay: true, loop: true`
- **Manual control** for exploration: `orbit: true, pan: true, zoom: true`
- **Static cameras** for focused attention: `orbit: false`

---

## 7. Additional Conventions

### File Organization
- Content files are in `/content/` directory
- Library definitions in `/lib.typ`
- Main document in `/main.typ`
- Each content file corresponds to a web page

### Linking
External links use `#link("URL")[text]`:
```typ
#link("https://youtu.be/81OV1BltMQ8")[iPlayGames's Wireless Masterclass]
#link("https://minecraft.wiki/w/Entity#Types_of_entities")[The Minecraft Wiki]
```

### Cross-References
Use `@symbol` for internal references:
```typ
See @singleplayer for details.
See @paper for details.
See @tilesets for details.
```

### TODO System
The documentation uses `#todo[label, body]` for planning:
```typ
#todo["Network Protocol" is inaccurate]
#todo[Singleplayer patch links][figure out exact version compatibility list.]
```

### Block References
Special section anchors use `<name>` syntax:
```typ
== Entity IDs <core>
== Stationary Item Optimization <singleplayer>
== Paper Servers <paper>
= Tilesets <tilesets>
```

---

## 8. Best Practices for Authors

### When Writing New Content
1. **Start with a diorama** showing the phenomenon or system
2. **Explain the mechanism** with clear, concise language
3. **Provide mathematical justification** when appropriate
4. **Give concrete examples** with step-by-step reasoning
5. **Use callouts** for key takeaways and warnings
6. **Reference existing sections** rather than repeating information

### When Creating Dioramas
1. **Use autoplay for demonstrations** of recurring patterns
2. **Enable orbit/pan/zoom for complex systems** readers should explore
3. **Keep timelines explicit** with clear `t N` markers
4. **Show before/after states** to demonstrate changes
5. **Use appropriate scaling**—don't overcrowd the view

### Mathematical Writing
1. **Define all variables** before using them
2. **Show derivation steps** clearly with alignment
3. **Use consistent notation** throughout
4. **Explain the mod arithmetic** thoroughly
5. **Connect math to implementation** with code examples

---

## 9. Template for New Sections

Here's a recommended template for new documentation sections:

```typ
#show raw.where(lang: "mc-diorama"): it => diorama(
  autoplay: true,
  loop: true,
  radius: 5,
  theta: 25,
  phi: 25,
  it.text,
)

= Section Title <section-name>

== subsection

```mc-diorama
p 0 0 0 block_type
p 0 1 0 another_block
t 0
p 0 0 0 changed_block
t 10
p 0 0 0
```

Explanation of what's happening, why it matters, and how it works.

#example[
  Concrete example with step-by-step walkthrough.
  
  #solution[
    Solution or explanation of the example.
  ]
]

#callout(kind: "tip", label: "Key Insight")[
  Important takeaway or rule of thumb.
]
```

---

## 10. References

These guidelines are based on analysis of the following files:
- `/content/core.typ` - Core mechanics with examples
- `/content/interference.typ` - Interference sources and solutions
- `/content/tilesets.typ` - Tileset patterns and examples
- `/content/block-event-delay.typ` - BED mechanisms
- `/content/design.typ` - Design tips and dioramas
- `/content/channels.typ` - Channel management (outline only)
- `/content/network.typ` - Network protocols (outline only)
- `/content/bulk.typ` - Bulk transport (outline only)
- `/content/data-protocols.typ` - Data protocols (outline only)
- `/lib.typ` - Library functions and callout definitions
- `/main.typ` - Main document structure