You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Fix @eq- to @sec- prefix for section cross-references
- Convert alignat to aligned environments for proper equation labeling
- Replace invalid characters (= and .) in figure labels
- Add blank lines before headings after math blocks
- Update CLAUDE.md for Quarto build system
- Clean up markdown formatting
-`{{< include file.qmd >}}` - Include another file
60
+
-`{=latex}` blocks for raw LaTeX when needed
66
61
67
62
### Code Organization Pattern
68
63
69
-
Each chapter's Python code lives in `src/CHAPTER/` and is referenced by documentation in `doc/.src/chapters/CHAPTER/`. The `@@@CODE` directive pulls code snippets directly from source files into the documentation, keeping code and docs in sync.
64
+
Each chapter's Python code lives in `src/CHAPTER/` and can be included in QMD files using fenced code blocks or Quarto includes.
70
65
71
66
## Pre-commit Hooks
72
67
@@ -80,11 +75,78 @@ Pre-commit hooks run automatically on commit:
80
75
81
76
## Key Dependencies
82
77
83
-
-**doconce** - Document generation from .do.txt files
78
+
-**quarto** - Document generation from .qmd files
84
79
-**numpy, scipy, matplotlib, sympy** - Scientific Python stack for examples
85
80
-**pdflatex** - LaTeX compilation (requires TeX Live installation)
86
81
87
82
## Build Output
88
83
89
-
-`doc/.src/book/book.pdf` - Generated book PDF
90
-
-`doc/pub/book/pdf/fdm-book.pdf` - Published copy of book PDF
84
+
-`_book/Finite-Difference-Computing-with-PDEs.pdf` - Generated book PDF
85
+
86
+
## Quarto Equation Labeling Guidelines
87
+
88
+
**Known Bug (GitHub Issue #2275)**: Quarto's `{#eq-label}` syntax cannot label individual lines within `\begin{align}` environments. This causes "macro parameter character #" LaTeX errors.
89
+
90
+
### What Fails
91
+
92
+
```markdown
93
+
$$
94
+
\begin{align}
95
+
a &= 0+1 {#eq-first} <!-- causes LaTeX error -->
96
+
b &= 2+3 {#eq-second}
97
+
\end{align}
98
+
$$
99
+
```
100
+
101
+
### Working Patterns
102
+
103
+
**Single equation or whole block label** - place label AFTER closing `$$`:
104
+
```markdown
105
+
$$
106
+
\begin{split}
107
+
a &= 0+1 \\
108
+
b &= 2+3
109
+
\end{split}
110
+
$$ {#eq-block}
111
+
```
112
+
113
+
**Multiple separate equations** - use separate `$$` blocks:
114
+
```markdown
115
+
$$
116
+
a = 0+1
117
+
$$ {#eq-first}
118
+
$$
119
+
b = 2+3
120
+
$$ {#eq-second}
121
+
```
122
+
123
+
**Individual line labels in align** - use pure AMS LaTeX syntax:
124
+
```latex
125
+
\begin{align}
126
+
a &= 0+1 \label{eq:first} \\
127
+
b &= 2+3 \label{eq:second}
128
+
\end{align}
129
+
130
+
See Equation \eqref{eq:first} for details.
131
+
```
132
+
133
+
### Best Practices
134
+
135
+
- **Never mix Quarto `{#eq-}` and AMS `\label{}` syntax** in the same equation
136
+
- Use `\begin{equation}...\end{equation}` for single numbered equations
137
+
- Use `\begin{align}...\end{align}` with `\label{}` for multiple aligned, individually-numbered equations
138
+
- Use `\begin{aligned}...\end{aligned}` inside `\begin{equation}` for aligned equations sharing one number
139
+
- Add `*` (e.g., `\begin{align*}`) to suppress all numbering
140
+
- Reference with `\eqref{label}` for parenthesized numbers, `\ref{label}` for plain numbers
141
+
- For Quarto cross-refs, use `@eq-label` syntax with label placed after `$$`
142
+
143
+
### Cross-Reference Prefixes
144
+
145
+
| Type | Prefix | Example |
146
+
|------|--------|---------|
147
+
| Section | `@sec-` | `@sec-vib-ode1` |
148
+
| Equation | `@eq-` | `@eq-vib-ode1-step4` |
149
+
| Figure | `@fig-` | `@fig-vib-phase` |
150
+
| Table | `@tbl-` | `@tbl-trunc-fd1` |
151
+
152
+
Reference: [NMFS-OpenSci Quarto-AMS Math Guide](https://nmfs-opensci.github.io/quarto-amsmath)
0 commit comments