JuliaKurs23/AGENTS.md

AGENTS.md - Guidelines for JuliaKurs23

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 translated to English. The English needs improvement—focus on making the prose professional, concise, and suitable for mathematicians.

Project Overview

• 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
• License: CC BY-NC-SA 4.0

---

Current Task: English Translation Improvement

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

# Build HTML website
quarto render

# Build only HTML
quarto render --to julia-color-html

# Build only PDF
quarto render --to julia-color-pdf

# Preview locally
quarto preview

# Render a specific chapter
quarto render chapters/first_contact.qmd

# Run in daemon mode (faster rebuilds)
quarto render --execute-daemon 3600

Deployment

./deploy.sh

---

Code Style Guidelines

Quarto Structure (.qmd files)

• 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:

using Statistics, LinearAlgebra, Plots  # many exports
import Base: convert, show               # specific exports

Naming:

• Variables/functions: lowercase with underscores (my_variable)
• Types: CamelCase (MyType, AbstractMatrix)
• Constants: ALL_UPPERCASE (MAX_ITER)
• Modules: PascalCase (Statistics)

Formatting:

• 4 spaces indentation
• ~92 character line limit
• Spaces around operators: a + b
• No spaces before commas: f(a, b)

Types:

• Explicit types for performance/clarity
• Parameterize: Vector{Float64}, Dict{Symbol, Int}
• Concrete types for struct fields

Error Handling:

try
    parse(Int, user_input)
catch e
    println("Invalid input: $e")
end

@assert x >= 0 "x must be non-negative"

---

File Organization

/
├── _quarto.yml          # Quarto configuration
├── Project.toml         # Julia dependencies
├── index.qmd            # Book index
├── chapters/            # Chapter .qmd files
├── notebooks/           # Jupyter notebooks (.ipynb)
├── css/                 # Custom styles
├── images/              # Images and logos
├── fonts/               # Custom fonts
└── _book/               # Built output (generated)

---

Important Notes

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