# integramme 0.9.0 - frozen release-candidate API

Version 0.9.0 freezes the long-form command API for the planned 1.0 release.
The preset surface and the built-in `einstein` data set remain part of that
public contract. No public command or rendering key is renamed. Changes after
this point should be limited to serious defects or strictly backward-compatible
clarifications.

## Frozen public entry points

```latex
\usepackage{integramme}
\integrammeset{<keys>}

\begin{integramme}[<keys>]
  \IntegrammeCategory{<category-id>}{<printed title>}{<items>}
  \IntegrammeYes{<category=item>}{<category=item>}
  \IntegrammeNo{<category=item>}{<category=item>}
  \IntegrammeSolutionRow{<category=item,...>}
  \IntegrammeIndices{<\item list>}
\end{integramme}
```

## Canonical category syntax

```latex
\IntegrammeCategory{prenom}{Prénom}{
  alice={Alice},
  irene={Irène},
  kelly={Kelly},
  lisa={Lisa}
}
```

The left-hand identifier is internal. The braced value is the printed label.
Printed labels may contain ordinary LaTeX material, commas and slashes.
Surrounding spaces in category identifiers are ignored. Empty category
identifiers are invalid.

## Canonical manual-mark syntax

```latex
\IntegrammeNo {prenom=alice}{ville=annecy}
\IntegrammeYes{prenom=alice}{age=a26}
```

## Canonical solution syntax

```latex
\IntegrammeSolutionRow{
  prenom=alice,
  ville=calais,
  age=a26,
  heure=h1430,
  etablissement=doucet
}
```

The order of assignments inside a solution row is irrelevant.

## Compatibility syntax

The following forms remain supported but are not the recommended API:

```latex
\IntegrammeCategory{prenom}{Prénom}{Alice,Irène,Kelly,Lisa}
\IntegrammeNo{prenom/alice}{ville/annecy}
\IntegrammeSolutionRow{alice,calais,a26,h1430,doucet}
\IntegrammeSolution{...}
```

Short aliases (`\IntCategory`, `\IntYes`, `\IntNo`, `\IntSolutionRow`,
`\IntIndices`, `\IntSolution`) remain available, but the long commands are the
documented contract.

## Public configuration keys and defaults

### Geometry and rules

| Key | Default |
| --- | --- |
| `cell-size` | `6mm` |
| `rule-width` | `0.3pt` |
| `block-rule-width` | `1pt` |
| `side-title-width` | `7mm` |
| `side-label-width` | `0pt` (automatic) |
| `side-label-min-width` | `26mm` |
| `side-padding` | `1.5mm` |
| `top-padding` | `1mm` |
| `top-label-min-height` | `7mm` |
| `title-height` | `7mm` |
| `indices-sep` | `3mm` |
| `guide-stem-height` | `0pt` (automatic) |

### Header behaviour

| Key | Default |
| --- | --- |
| `column-labels` | `auto` |
| `top-angle` | `45` |
| `guides` | `true` |
| `guide-length` | `1.15` |
| `guide-opacity` | `0.45` |

`column-labels` accepts `auto`, `horizontal` or `slanted`.

### Typography and marks

| Key | Default |
| --- | --- |
| `font` | `\sffamily` |
| `title-font` | `\sffamily\bfseries` |
| `indices-font` | `\normalfont` |
| `mark-font` | `\sffamily` |
| `yes-mark` | `\ensuremath{\bullet}` |
| `no-mark` | `\ensuremath{\times}` |
| `grid-color` | `black` |
| `text-color` | `black` |

### Behaviour

| Key | Default |
| --- | --- |
| `mode` | `blank` |
| `preset` | `none` |
| `preset-language` | `en` |
| `overflow-warning` | `true` |

`mode` accepts `blank`, `manual` or `solution`. `preset` accepts `none` or
`einstein`. `preset-language` accepts `en` or `fr`.

## Built-in preset

```latex
\begin{integramme}[preset=einstein,preset-language=fr]
\end{integramme}
```

The preset preloads six categories, fifteen clues, the final question and the
complete keyed solution. In `blank` mode only the grid and clues are printed;
`mode=solution` uses the preloaded solution. Users may also add manual marks in
`mode=manual`.

## Scope

`\integrammeset{...}` changes package defaults from that point onward.
Environment options are local to the current `integramme` environment and take
precedence over the current global settings.

## Compatibility promise before 1.0

The project intends to preserve the long-form API listed above throughout the
remaining pre-1.0 releases unless a serious design or correctness issue requires
an incompatible change. Any such change must be documented prominently in the
changelog. Compatibility-only commands and syntaxes may be deprecated before
1.0, but they will not be removed without an explicit release note.