better

# AGENTS.md

Guidance for AI agents contributing content to this repository.

## What this is

An [mdbook](https://rust-lang.github.io/mdBook/) site published at **apunts.jg5.dev**, containing

teaching materials for CS subjects, written in **Catalan**, licensed CC BY-NC-SA 4.0.

- All content lives under `src/`, one Markdown file per page.

- **Every page must be registered in `src/SUMMARY.md`.** A file that is not listed there is not

  built and not reachable.

- `src/hidden/` and `src/m3/` are not referenced from `SUMMARY.md`. Treat them as drafts or

  archived material, not as live pages.

## Build and verify

```shell

mdbook build     # writes to book/html

mdbook serve     # live preview

```

Always run `mdbook build` after editing content. Notes:

- Five preprocessors are configured in `book.toml` and must be installed: `mdbook-plantuml`,

  `mdbook-toc`, `mdbook-langtabs`, `mdbook-mermaid`, `mdbook-last-changed`. A missing binary fails

  the build with an error that can look like a content problem.

- PlantUML needs a `plantuml` script on the PATH wrapping `plantuml.jar`. See `README.md`.

- `WARN search index is very large` is expected. It is not a failure.

## Page anatomy

Follow the shape the existing pages use:

```markdown

# Títol de la pàgina

<!-- toc -->

## Primera secció

...

## Referències

- [Títol de l'enllaç](https://example.com/)

```

- Line 1 is the `#` title, then a blank line, then the `<!-- toc -->` marker.

- Headings descend without skipping levels: `##`, then `###`, then `####`.

- `## Referències` goes last, as a bullet list of external links.

- Images are referenced as `![alt](../images/name.png)`. Each top-level section may have its own

  `images/` directory (`src/images/`, `src/m9/images/`, `src/apren/ba1/images/`, …); put the file in

  the one that `../images/` resolves to from the page you are editing.

- Per-page JavaScript goes right after the TOC marker: `<script src="./nom_pagina.js"></script>`.

- **Keep pages digestible.** The median page here is around 85 lines and a conceptual page reads

  best under ~400. Past ~800 lines, split it into subpages under a section directory and register

  each one in `SUMMARY.md`. The long language references (`basic_java.md`, `basic_python.md`) are a

  deliberate exception, not a precedent.

- MathJax is enabled, and `plotly.min.js` is loaded globally, so pages can render plots.

- Source files for hand-built figures live in `tikz/` and `yed/` at the repo root.

## Diagrams and code

**PlantUML** for UML (class, sequence, component diagrams):

````markdown

```plantuml

@startuml

hide circle

skinparam linetype ortho

...

@enduml

```

````

**Mermaid** for flowcharts and graphs:

````markdown

```mermaid

flowchart LR

...

```

````

**langtabs** renders consecutive code blocks in different languages as tabs. Used mainly for

parallel Java/C# examples. The markers are HTML comments and the blocks between them must be

adjacent:

````markdown

<!-- langtabs-start -->

```java

public class Compte { }

```

```csharp

public class Compte { }

```

<!-- langtabs-end -->

````

## Mathematical content

### Formulas (MathJax)

MathJax is enabled in `book.toml`. mdbook consumes one level of backslash escaping, so the

delimiters carry extra backslashes. Get these exactly right or the formula renders as raw text:

- **Inline**, inside a sentence: `la derivada \\( f'(x) = 2x \\) ens diu la pendent`

- **Display**, as its own paragraph, with the delimiters on their own lines:

````markdown

\\\[

J(w, b) = \frac{1}{2m} \sum_{i=1}^m \bigl(f(x_i) - y_i \bigr)^2

\\\]

````

What you write is not what MathJax receives, because mdbook strips one level of escaping first.

This is the mapping, and getting it wrong **fails silently**: a formula written with the wrong

delimiter renders as literal text instead of raising an error.

| What you write in the `.md` | What reaches the browser | Result |

| --- | --- | --- |

| `\\( f(x) \\)` | `\( f(x) \)` | inline formula |

| `\\\[ … \\\]` | `\[ … \]` | display formula |

| `\[0, 1\]` | `[0, 1]` | literal text, **not** a formula |

| `[0, 1]` | `[0, 1]` | literal text, **not** a formula |

Never write `\[ … \]` expecting maths. It produces square brackets.

- Inside a formula, **LaTeX commands take a single backslash**: `\frac`, `\sum`, `\alpha`,

  `\partial`. A few older pages double them (`\\frac`); follow the single-backslash majority.

- A **line break inside a display block** is four backslashes (`\\\\`) at the end of the line.

- **Literal square brackets** only need escaping when a `(` follows immediately, which markdown

  would otherwise read as a link: `\[0, 1\](tancat)`. Everywhere else `[0, 1]` renders as typed.

  Escaping anyway is the house style here and is harmless.

- **Always unpack the formula.** Below it, list every symbol you introduced

  (`- **m**: nombre d'exemples d'entrenament`) and restate what it does in words ("En paraules

  senzilles: …"). A formula left unexplained teaches nothing to this audience.

### Interactive figures (Plotly)

Plotly is the tool for **plotting functions and data**, especially when the reader benefits from

seeing a shape or moving a parameter. `plotly.min.js` is loaded globally, so no import is needed.

The pattern, as used by `src/apren/ba1/ml_supervised.md` and its `ml_supervised.js`:

1. Page `nom.md` has a sibling `nom.js` in the same directory.

2. The page loads it right after the TOC marker: `<script src="./nom.js"></script>`

3. Where a figure belongs, place an empty container: `<div id="derivative" class="plotly"></div>`.

   The `.plotly` class in `custom.css` sizes it (full width, 60vh tall).

4. In the JS, write one function per figure that takes the container id and ends in

   `Plotly.newPlot(identity, traces, layout, config)`, with `const config = { responsive: true }`.

   Sliders and other controls go in `layout`.

5. Bind every figure at the end of the file, inside a single listener:

```javascript

document.addEventListener('DOMContentLoaded', function () {

  derivativePlot("derivative");

  lossFunctionPlot("lossFunction");

});

```

Adding a figure therefore means editing two files, and the `id` must match on both sides.

Choosing the right visual:

| Need | Tool |

| --- | --- |

| Shape of a function, or a parameter the reader can move | Plotly |

| Class, sequence or component structure | PlantUML |

| Flow, pipeline, state machine | Mermaid |

| Screenshot or a figure produced elsewhere | PNG under the section's `images/` |

## Escaping and special characters

All of the following was verified against the actual build. The first three fail silently.

- **`<Nom>` in prose is parsed as raw HTML** and can swallow the rest of the line: `un <Component>`

  renders as an empty `<component></component>` element. Wrap it in backticks

  (`` `<Component>` ``) or escape it as `\<Component\>`.

- **Smart punctuation is on**: `--` becomes an en dash (–) and `---` an em dash (—). That is

  exactly what the Catalan style rules forbid, so never type them. Straight quotes and apostrophes

  become curly automatically, which is fine in prose.

- **Apostrophes are converted inside formulas too**: `\\( f'(x) \\)` reaches the browser as

  `f’(x)`, which is a curly quote and not the TeX prime. Write `\\( f^{\prime}(x) \\)` when you

  need a derivative.

- **A literal `|` inside a table cell** must be written `\|`, or it is read as a column separator

  and the row loses cells.

These need **no** escaping, so do not clutter the source with backslashes:

| Written | Renders as |

| --- | --- |

| `x_1 i x_2`, `X_train` | unchanged; intraword underscores are not emphasis |

| `si a < b` | `si a < b` |

| `A & B` | `A & B` |

| `costa $100` | `costa $100`; `$` is not a math delimiter here |

| `C:\temp\nou` | unchanged |

## Who you are writing for

Students of the **CFGS in Desenvolupament d'Aplicacions Multiplataforma**, higher vocational

education in software development. Calibrate accordingly:

- Assume programming fundamentals, but no professional experience and no exposure to industry

  jargon. Explain a term the first time it appears.

- The goal is building things correctly, not academic completeness. Prefer the explanation that

  changes what the reader does.

- Depth is welcome, obscurity is not. A concept that needs three paragraphs gets three paragraphs,

  written so that one reading is enough.

## Writing conventions

The content is in Catalan. Match the voice of the surrounding page.

### Language and terminology

- Bold a key term the first time it appears, with the English original in parentheses:

  `la **separació de responsabilitats** (separation of concerns, SoC)`. Bold it once, not on every

  mention.

- **Keep English for terms the field uses in English**: REST, endpoint, framework, thread, commit,

  broker, deploy, test double. Translating an established universal term makes the text harder to

  read, not more Catalan.

- For everything else, check whether **TERMCAT** has a recommended Catalan translation before

  coining a borrowing (*embedded* → "encastat", never "embarcat").

- **No em dashes (—) or en dashes (–)**, and no other English typographic conventions. Use commas,

  colons, parentheses or separate sentences.

- **Neutral vocabulary for the material itself**: "materials", "continguts", "document". Avoid

  calling it a course.

- **Register**: impersonal or *nosaltres* for concepts ("podem", "tenim"), *tu* for practical

  advice ("si necessites", "tria"). Never *vós* ("tingueu"). Stay consistent within a page.

### Readability

- **Short paragraphs**: two to five sentences, one idea each. A paragraph carrying two ideas is two

  paragraphs.

- **Bold to signal, not to decorate**: key terms on definition, and the load-bearing phrase opening

  a bullet. If half a paragraph is bold, nothing stands out any more.

- **Lists for enumerable things**: options, steps, criteria, parallel cases. Reasoning that connects

  ideas stays in prose. A list of bare keywords teaches nothing.

- **Tables** work well for paired columns: symptom and cause, option and trade-off, method and

  response.

- **Example before abstraction**: ground a concept in a concrete instance before naming it.

- Inside a single list, choose infinitive or imperative and keep it uniform.

## Working rules

- **Stay scoped to the file you were asked to edit.** Do not restructure neighbouring pages,

  reorder `SUMMARY.md`, or "improve" content that was not mentioned.

- **Never run git commands** (`add`, `commit`, `push`, `checkout`, …). Read-only inspection

  (`status`, `diff`, `log`) is fine. The repository owner handles version control.

- **Adding a page** means two edits: create the file *and* add its entry to `src/SUMMARY.md` at the

  correct nesting depth.

- **Cross-link instead of duplicating.** If a concept is already explained on another page, link to

  it with a relative path rather than restating it.

- **Currency: your training cutoff is not today.** Establish the current date from the environment

  and verify anything time-sensitive against a current source before writing it: model names and

  prices, library and tool versions, API details, and any claim of the form "the latest X" or

  "currently". If you cannot verify it, do not write it.

- **Cite the canonical reference.** Attribute a concept to its primary or best-known source (the

  original paper, the author who coined the term, the official documentation) rather than to

  whichever blog post happens to explain it well. Verify every URL before adding it to

  `## Referències`; never cite a link from memory.

- **Match the page's altitude.** Do not insert a step-by-step tutorial into a conceptual page, or a

  conceptual essay into a reference page.

## Before finishing

- `mdbook build` completes without errors.

- The page starts with `# Títol` followed by `<!-- toc -->`.

- New pages are listed in `src/SUMMARY.md`.

- Every link under `## Referències` resolves.

- Heading levels are sequential and no dashes slipped into the Catalan text.

- Report what changed and what was deliberately left out.

## Content map

| Directory | Section |

| --- | --- |

| `src/m9/` | Serveis i processos (concurrency, sockets, cryptography, security) |

| `src/m7/` | Desenvolupament d'interfícies (web UI, React, UX, testing) |

| `src/apren/` | IA i Ciència de dades (ML, LLMs, data science) |

| `src/fonaments/` | Fonaments de programació (architecture, OOP, general principles) |

| `src/aitools/` | Eines IA per al desenvolupament |

| `src/java/` | Programació en Java |

| `src/web/` | Programació Web |

| `src/persistencia/` | Persistència de dades |

| `src/empresa/` | Empresa (economics, business planning) |