hellmund/JuliaKurs23
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Activity

english improved

Browse Source
This commit is contained in:
Meik Hellmund
2026-03-05 20:09:16 +01:00
parent c6609d15f5
commit 733fe8c290
21 changed files with 954 additions and 1042 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
AGENTS.md
View File

@@ -1,23 +1,51 @@
# AGENTS.md - Guidelines for Agentic Coding in JuliaKurs23
# AGENTS.md - Guidelines for JuliaKurs23
This is a **Quarto-based Julia programming course book** in English. The book teaches scientific computing with Julia using interactive Jupyter notebooks rendered with Quarto.
This is a **Quarto-based Julia programming course book**. The book teaches scientific computing with Julia using interactive Jupyter notebooks rendered with Quarto.
**Translation Note:** The book was originally written in German and has been translated to professional, concise English suitable for mathematicians. All code, LaTeX equations, and formatting have been preserved during translation. Only text descriptions and code comments were translated to English.
**Translation Note:** The book was originally written in German and translated to English. The English needs improvement—focus on making the prose professional, concise, and suitable for mathematicians.
## Project Overview
- **Type**: Educational book website/PDF generated from Quarto (.qmd) files
- **Type**: Educational book (HTML website + PDF) generated from Quarto (.qmd) files
- **Language**: English (all content)
- **Build System**: Quarto with Julia Jupyter kernel
- **Julia Version**: 1.10
- **Output**: HTML website and PDF
- **License**: CC BY-NC-SA 4.0
---
## Build Commands
## Current Task: English Translation Improvement
### Build the Book
The English text in this book was translated from German and needs refinement for quality.
### Workflow (one change at a time)
For each chapter file in `chapters/`:
1. I read the file and identify English improvements
2. I present ONE improvement at a time showing:
- The current text
- The proposed improvement
- Explanation of why the change is needed
3. You reply **yes** or **no**
4. If yes, I apply the change; if no, I skip it
5. Repeat until all improvements for that file are done
6. Move to the next chapter file
### What to improve:
- English prose, grammar, word choice
- Clarity and flow for mathematical audience
- Professional tone suitable for mathematicians/scientists
### What NOT to change:
- Julia code
- LaTeX equations
- Markdown formatting
- Quarto cell options (`#| eval:`, etc.)
---
## Build Commands
```bash
# Build HTML website
@@ -31,17 +59,10 @@ quarto render --to julia-color-pdf
# Preview locally
quarto preview
```
### Development Commands
```bash
# Render a specific chapter
quarto render chapters/first_contact.qmd
# Build with specific output directory
quarto render --output-dir _book
# Run in daemon mode (faster rebuilds)
quarto render --execute-daemon 3600
```
@@ -49,135 +70,55 @@ quarto render --execute-daemon 3600
### Deployment
```bash
# Deploy to web server (rsync _book/)
./deploy.sh
```
### Testing Individual Code Blocks
Quarto executes Julia code in Jupyter notebooks. To test individual code blocks:
1. Open the `.qmd` file in VS Code with Julia extension
2. Use Julia REPL to execute code blocks interactively
3. Or use IJulia/Jupyter to run specific cells
```julia
# In Julia REPL, test code from a cell:
include("path/to/notebook.jl")
```
### Julia Package Management
```bash
# Install dependencies (from Project.toml)
julia -e 'using Pkg; Pkg.instantiate()'
# Add a new package
julia -e 'using Pkg; Pkg.add("PackageName")'
```
---
## Code Style Guidelines
### General Structure (.qmd files)
### Quarto Structure (.qmd files)
- All `.qmd` files start with YAML front matter specifying `engine: julia`
- Code blocks use triple backticks with `julia` language identifier
- Use Quarto cell options in comments like `#| option: value`
- Common options: `eval:`, `echo:`, `output:`, `error:`, `hide_line:`
Example:
```markdown
---
engine: julia
---
```{julia}
#| eval: true
#| echo: true
#| output: true
using Statistics
mean([1, 2, 3])
```
```
- All `.qmd` files start with YAML front matter: `engine: julia`
- Code blocks use triple backticks with `julia` identifier
- Cell options in comments: `#| option: value`
### Julia Code Conventions
#### Imports
**Imports:**
```julia
# Prefer using for packages with many exports
using Statistics, LinearAlgebra, Plots
# Use import when you need specific exports or module name
import Base: convert, show
using Statistics, LinearAlgebra, Plots # many exports
import Base: convert, show # specific exports
```
#### Naming Conventions
**Naming:**
- Variables/functions: lowercase with underscores (`my_variable`)
- Types: CamelCase (`MyType`, `AbstractMatrix`)
- Constants: ALL_UPPERCASE (`MAX_ITER`)
- Modules: PascalCase (`Statistics`)
- **Variables/functions**: lowercase with underscores (`my_variable`, `calculate_mean`)
- **Types**: CamelCase (`MyType`, `AbstractMatrix`)
- **Constants**: ALL_UPPERCASE (`MAX_ITER`, `PI`)
- **Modules**: PascalCase (`Statistics`, `LinearAlgebra`)
**Formatting:**
- 4 spaces indentation
- ~92 character line limit
- Spaces around operators: `a + b`
- No spaces before commas: `f(a, b)`
#### Formatting
- Use 4 spaces for indentation (Julia default)
- Limit lines to ~92 characters when practical
- Use spaces around operators: `a + b`, not `a+b`
- No spaces before commas: `f(a, b)`, not `f(a , b)`
#### Types
- Use explicit types when needed for performance or clarity
- Parameterize types when useful: `Vector{Float64}`, `Dict{Symbol, Int}`
- Prefer concrete types for fields in structs
#### Error Handling
**Types:**
- Explicit types for performance/clarity
- Parameterize: `Vector{Float64}`, `Dict{Symbol, Int}`
- Concrete types for struct fields
**Error Handling:**
```julia
# Use try-catch for expected errors
try
parse(Int, user_input)
catch e
println("Invalid input: $e")
end
# Use assertions for internal checks
@assert x >= 0 "x must be non-negative"
```
### Quarto-Specific Guidelines
#### Cell Options
Use these in code block comments:
- `#| eval: true/false` - whether to execute
- `#| echo: true/false` - show source code
- `#| output: true/false` - show output
- `#| error: true/false` - show errors
- `#| hide_line: true` - hide this line from output
- `#| fig-cap: "Caption"` - figure caption
#### Embedding Notebooks
```markdown
{{< embed notebooks/nb-types.ipynb#nb1 >}}
```
#### Conditional Content
```markdown
::: {.content-visible when-format="html"}
... HTML only content
:::
::: {.content-visible when-format="pdf"}
... PDF only content
:::
```
---
## File Organization
@@ -197,20 +138,10 @@ Use these in code block comments:
---
## VS Code Settings
The project uses VS Code with:
- Julia environment: `/home/hellmund/Julia/23`
- LTEx for spell checking (disabled for code blocks)
- Auto-exclude: `.ipynb`, `.md`, `.quarto_ipynb` files
---
## Important Notes
1. **All content is in English** - Comments, documentation, variable names in examples should be English (professional, concise, suitable for mathematicians)
2. **Code comments were translated** - German text and code comments were translated to English; all Julia code, LaTeX equations, and Quarto formatting were preserved
3. **Code execution is cached** - Use `#| eval: true` to execute cells
4. **ansi color codes** - The `julia-color` extension handles ANSI escape sequences in output
5. **Freeze mode** - Set to `auto` in _quarto.yml; use `freeze: false` to re-run all code
6. **Keep intermediate files** - `keep-ipynb`, `keep-tex`, `keep-md` are all true
1. **All content is in English** — professional, concise, suitable for mathematicians
2. **Code, LaTeX, formatting preserved** — only improve English prose
3. **Code execution cached** — use `#| eval: true` to execute cells
4. **Freeze mode** — set to `auto` in _quarto.yml; use `freeze: false` to re-run all code
5. **Keep intermediates** — `keep-ipynb`, `keep-tex`, `keep-md` are all true