mirror of
https://github.com/TheRealOwenRees/pgn_to_tex.git
synced 2026-11-18 04:42:07 +00:00
317 lines
9.3 KiB
Markdown
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).
|