491 lines
14 KiB
Markdown
491 lines
14 KiB
Markdown
# 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
|