Files
pgn_to_tex/README.md
T

317 lines
9.3 KiB
Markdown

# Pgn_to_tex
`Pgn_to_tex` converts chess games written in PGN to LaTeX. It renders move
numbers, moves, comments, variations, NAG annotations, clock times, and
optional chessboard diagrams of selected positions.
- [API documentation](https://therealowenrees.github.io/pgn_to_tex/)
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
## Requirements
- OCaml 5.4 or newer
- dune
- A LaTeX installation with `xskak` and `multicol` (see
[LaTeX setup](#latex-setup))
## Installation
Install the released package with opam:
```sh
opam install pgn_to_tex
```
To use the current repository instead, clone it and pin the checkout:
```sh
git clone https://github.com/TheRealOwenRees/pgn_to_tex.git
cd pgn_to_tex
opam install .
```
Then add the library to the relevant `dune` file:
```lisp
(libraries pgn_to_tex)
```
## Quick start
Open `Pgn_to_tex` and call `to_tex` with a PGN string:
```ocaml
let pgn = "1. e4 e5 2. Nf3 Nc6 3. Bb5"
let tex = Pgn_to_tex.to_tex pgn
```
`to_tex` returns a LaTeX fragment without a preamble or `\begin{document}`.
`~diagram_data` defaults to no diagrams and `~clock` defaults to `false`, so
this basic call needs no other arguments.
To render diagrams, describe the selected positions as JSON and parse it with
`parse_diagrams_json`:
```ocaml
let diagrams =
Pgn_to_tex.parse_diagrams_json
{| [
{"fen": "rnbqkbnr/pppppppp/8/8/3P4/8/PPP1PPPP/RNBQKBNR b KQkq - 0 1",
"path": ["d4"]},
{"fen": "rnbqkbnr/ppp1pppp/8/3p4/3P4/8/PPP1PPPP/RNBQKBNR w KQkq - 0 2",
"ply": 2}
] |}
let tex = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn
```
To explicitly request a game with no diagrams, pass
`~diagram_data:Pgn_to_tex.empty_diagrams`.
`diagram_data` is abstract. Construct it with `parse_diagrams_json` or
`empty_diagrams` instead of building the internal representation directly.
## Diagram JSON schema
`parse_diagrams_json` accepts a JSON array. Each entry is an object:
```json
[
{"fen": "8/8/8/8/8/8/4K3/7k w - - 0 1", "path": ["d4", "d5", "e4", "d6"]},
{"fen": "8/8/8/8/8/8/4K3/7k w - - 0 1", "ply": 5},
{"fen": "8/8/8/8/8/8/4K3/7k w - - 0 1", "ply": 9, "path": ["e4", "e5", "Nf3", "Nc6"]}
]
```
| Field | Type | Required | Description |
| ------ | --------------- | --------------- | ----------- |
| `fen` | string | yes | The board position to render. |
| `path` | array of string | one of path/ply | The SAN move sequence from the start of the game, including moves inside a variation (for example `["d4","d5","e4","d6"]`). It uniquely identifies mainline and variation positions. |
| `ply` | integer | one of path/ply | Legacy half-move count from the start of the game: 1 after White's first move. It is used for mainline positions. |
Resolution rules:
- An entry may carry `path`, `ply`, or both.
- A matching `path` takes precedence over a matching `ply`.
- If no `path` matches, mainline positions fall back to a matching legacy `ply`.
- Variation diagrams require `path`; a `ply`-only entry only matches mainline
positions.
- Missing both `path` and `ply` leaves the entry with no position to match.
Diagrams on the mainline use the default board size. Diagrams inside a
variation are rendered inline and use the smaller `smallboard` size.
### Malformed diagram JSON
If the JSON is invalid, or any entry is malformed, `parse_diagrams_json`
returns empty diagram data instead of raising. Conversion then proceeds
without diagrams.
## Clocks
Clock annotations are opt-in:
```ocaml
let tex = Pgn_to_tex.to_tex ~clock:true ~diagram_data:diagrams pgn
```
With `~clock:true`, the most recent clock values for both players are shown
above and below each rendered diagram. Clock values come from PGN clock
annotations such as `{[%clk 0:10:00]}` or an inline `[%clk 0:10:00]`.
Clocks are displayed as part of diagram output. When no diagram is selected
for a position, its clock values are not emitted.
## Variations
Parenthesised variations are rendered inline inside the mainline, for example
`( 2... d6 )`. Mainline moves and move numbers are bold; variation moves are
not. Comments and NAGs inside a variation are rendered there too. Variation
diagrams are looked up by their full `path` and use `smallboard` so they do not
dominate the subline.
## Supported headers
The following PGN headers are rendered:
- `Event` is used as the title when `Title` is absent.
- `Title` is the document title. When `Subtitle` is also present, the subtitle
is rendered below the title. A title without a subtitle renders no subtitle
block.
- `Author` is the author line when present. Otherwise the author line is built
from `White` and `Black`, including `WhiteElo` and `BlackElo` when supplied.
- `Date` and `Site` are combined into the date line. An empty date with a site
renders the site; an empty date and site render an empty date.
- `Result` is rendered in bold at the end of the game.
All other headers are ignored.
## NAG annotations
The following Numeric Annotation Glyphs are rendered:
| NAG | LaTeX |
| ------ | ----------------------- |
| `$1` | `!` |
| `$2` | `?` |
| `$3` | `!!` |
| `$4` | `??` |
| `$5` | `!?` |
| `$6` | `?!` |
| `$10` | `=` |
| `$13` | `\infty` |
| `$14` | `\wbetter` |
| `$15` | `\bbetter` |
| `$16` | `\ensuremath{\pm}` |
| `$17` | `\ensuremath{\mp}` |
| `$18` | `+-` |
| `$19` | `-+` |
| `$22` | `\zugzwang` |
| `$32` | `\development` |
| `$36` | `\initiative` |
| `$40` | `\attack` |
| `$44` | `\compensation` |
| `$132` | `\counterplay` |
Unmapped NAGs are ignored.
## Error behavior
- `to_tex` raises `Failure "Parse error"` when the PGN cannot be parsed.
- `parse_diagrams_json` never raises for malformed JSON; it returns empty
diagram data, as described above.
## LaTeX setup
The generated string is a fragment: it does not include a document class,
preamble, or `\begin{document}`. A complete document using `xskak` (which
loads `chessboard`, `skak`, and the chess symbol fonts), `multicol` for the
column layout, and the default diagram commands looks like this:
```latex
\documentclass{article}
\usepackage{xskak}
\usepackage{multicol}
\usepackage{amsmath,amssymb}
% NAG $13 renders \infty, a math-mode symbol, in text mode.
\let\pgninfinity\infty
\renewcommand{\infty}{\ensuremath{\pgninfinity}}
\begin{document}
\begin{multicols}{2}
% Paste the string returned by Pgn_to_tex.to_tex here.
\end{multicols}
\end{document}
```
The relevant packages are:
- `xskak` for `\newchessgame`, `\chessboard`, and the NAG symbol commands.
- `multicol` for the two-column environment shown above.
- `amsmath` and `amssymb` for math symbols.
## JavaScript build
The JavaScript target is optional. Dune skips it when the JavaScript
dependencies are not installed. Install them with:
```sh
opam install js_of_ocaml js_of_ocaml-ppx
```
Build the artifact with:
```sh
dune build bin/pgn_to_tex_js.bc.js
```
The generated CommonJS file is
`_build/default/bin/pgn_to_tex_js.bc.js`. It works in Node and in the browser.
The build exposes a single global function with the same three inputs as the
JavaScript entry point:
```js
to_tex(pgnString, diagramJsonString, displayClock);
```
- `pgnString` is the PGN text.
- `diagramJsonString` is the diagram JSON. Pass `""` or `"{}"` when there are
no diagrams.
- `displayClock` is a boolean controlling clock rendering.
- The return value is the LaTeX fragment as a string.
Node example:
```js
require("./_build/default/bin/pgn_to_tex_js.bc.js");
const gameTex = globalThis.to_tex("1. e4 e5 2. Nf3", "{}", false);
```
In the browser, the function is available as `window.to_tex` after the
artifact is loaded.
Run the Node smoke test after building the artifact:
```sh
node test/js/smoke.js
```
## Migration from 0.0.x
Version `0.1.0` is a breaking release. The old `Pgn_logic` library name and the
`Pgn2tex` module are gone.
| 0.0.x | 0.1.0 |
| ----- | ----- |
| `open Pgn_logic` | `open Pgn_to_tex` or use `Pgn_to_tex.` |
| `Pgn2tex.to_tex` | `Pgn_to_tex.to_tex` |
| `Pgn2tex.parse_diagrams_json` | `Pgn_to_tex.parse_diagrams_json` |
| Exposed `MoveMap.t` diagram data | Abstract `Pgn_to_tex.diagram_data` |
| `_build/default/bin/main.bc.js` | `_build/default/bin/pgn_to_tex_js.bc.js` |
The optional arguments now come before the PGN string:
```ocaml
(* 0.0.x *)
let tex = Pgn2tex.to_tex pgn ~diagram_data ~clock:false
(* 0.1.0 *)
let tex = Pgn_to_tex.to_tex ~diagram_data ~clock:false pgn
```
Replace a hand-built diagram map with `parse_diagrams_json`, or use
`empty_diagrams` for a game without diagrams. Path-only diagram entries are
supported; see [Diagram JSON schema](#diagram-json-schema). The JavaScript
`to_tex(pgn, diagramJson, displayClock)` contract is unchanged apart from the
artifact name.
## Dependencies
Runtime and build dependencies:
- `ocaml` >= 5.4
- `dune` >= 3.21
- `sedlex` >= 3.7
- `menhir` >= 20260209
- `yojson` >= 3.0
Test-only dependencies:
- `ounit2` >= 2.2.7
- `js_of_ocaml`
- `js_of_ocaml-ppx`
Development and documentation dependencies:
- `ocamlformat` 0.29.0 (development setup)
- `odoc` (documentation build)
## License
AGPL-3.0-or-later. See [LICENSE](LICENSE).