docs: prepare 0.1.0 release metadata and migration

This commit is contained in:
2026-10-23 16:38:24 +02:00
committed by owenrees
parent 2bf11e92a8
commit 4f50ff020e
6 changed files with 365 additions and 107 deletions
+64
View File
@@ -1,3 +1,67 @@
## 0.1.0
### Breaking changes
- Renamed the public entry point from `Pgn_logic` / `Pgn2tex` to
`Pgn_to_tex`. The old modules are removed with no compatibility aliases.
- `Pgn_to_tex.to_tex` takes optional `~diagram_data` and `~clock` arguments
before the PGN string, and defaults to no diagrams and no clock output.
- Removed the internal parser, AST, LaTeX, and NAG modules from the public
surface. `diagram_data` is now an abstract type.
- Renamed the optional JavaScript artifact from `main.bc.js` to
`pgn_to_tex_js.bc.js`.
### Added
- New public API: `Pgn_to_tex.to_tex`, `Pgn_to_tex.parse_diagrams_json`,
`Pgn_to_tex.empty_diagrams`, and the abstract `diagram_data` type.
- Diagram JSON accepts `path`, `ply`, or both. Paths identify mainline and
variation positions; path lookup takes precedence over the legacy ply
fallback, and path-only variation entries are supported.
- Diagrams inside variations render inline at the smaller `smallboard` size.
- Generated odoc API documentation, a package landing page, and a GitHub Pages
deployment workflow.
- GitHub Actions CI covering formatting, build, tests, docs, the JavaScript
build, the Node smoke test, and opam lint.
- A self-contained README covering installation, the API, diagram JSON,
clocks, variations, headers, NAGs, errors, the LaTeX preamble, and JavaScript
usage.
- `js_of_ocaml` and `js_of_ocaml-ppx` are declared as test-only dependencies.
### Fixed
- A mixed `Author` and player header no longer produces an empty author line.
- A `Title` without a `Subtitle` no longer emits an empty subtitle block.
- Empty `Date` and `Site` headers no longer produce comma-only date lines.
### Changed
- The package version is now `0.1.0`.
- Documentation now points at
<https://therealowenrees.github.io/pgn_to_tex/>.
- Removed stale CI-acceptance metadata for unsupported OCaml versions.
### Migration from 0.0.x
Replace the old import and module prefix:
```ocaml
(* 0.0.x *)
open Pgn_logic
let diagrams = Pgn2tex.parse_diagrams_json json
let tex = Pgn2tex.to_tex pgn ~diagram_data:diagrams ~clock:false
(* 0.1.0 *)
let diagrams = Pgn_to_tex.parse_diagrams_json json
let tex = Pgn_to_tex.to_tex ~diagram_data:diagrams ~clock:false pgn
```
Use `Pgn_to_tex.empty_diagrams` when a game has no diagrams. Diagram data is
now abstract, so replace any hand-built `MoveMap.t` with
`Pgn_to_tex.parse_diagrams_json`. The JavaScript `to_tex` function keeps the
same three arguments; only the artifact name changed.
## 0.0.2
- support diagrams in variations. Diagram data now carries an optional `path` (the SAN move sequence from the root) alongside the legacy `ply`; diagrams whose `path` resolves inside a variation are rendered inline within the variation. `parse_diagrams_json` returns a `diagram_data` record with `by_ply` and `by_path` maps.
+59 -4
View File
@@ -1,13 +1,68 @@
# Contributing
When contributing to this repository, please first discuss the change you wish to make via the repository's issues.
When contributing to this repository, please first discuss the change you wish
to make via the repository's issues.
If you are wanting to tackle one of the pre-existing issues, please comment on that issue so that you can be assigned to it.
If you are wanting to tackle one of the pre-existing issues, please comment on
that issue so that you can be assigned to it.
Alternatively, just send a PR and I will check it asap. Please bear in mind that I may not be reactive if I was not expecting a PR.
Alternatively, just send a PR and I will check it asap. Please bear in mind that
I may not be reactive if I was not expecting a PR.
## Guidelines
- We use the [GitHub Flow](https://www.gitkraken.com/learn/git/best-practices/git-branch-strategy#github-flow-considerations) branching strategy. Add your code into a feature branch such as `feature/feature-name`.
- Write good commit messages. 'Fix bug' is not a good commit message. 'Fix bug with comments before moves' is a good commit message.
- Explain the changes in the PR comments
- Explain the changes in the PR comments.
## Development setup
The package requires OCaml 5.4 or newer. From a checkout, install all build,
test, documentation, and development dependencies:
```sh
opam install . --deps-only --with-test --with-doc --with-dev-setup
```
The JavaScript build is an optional target. Its dependencies are part of the
`--with-test` set (`js_of_ocaml` and `js_of_ocaml-ppx`), so the command above
also prepares the Node smoke test.
## Verification commands
Run these before opening or updating a pull request.
Check formatting, build the package, run the test suite, and build the API
documentation:
```sh
dune build @fmt @install @runtest @doc
```
`@fmt` checks formatting with `ocamlformat` 0.29.0. If it reports a diff, apply
the formatting with `dune fmt` (or `dune build @fmt --auto-promote`).
Build the optional JavaScript artifact:
```sh
dune build bin/pgn_to_tex_js.bc.js
```
Run the Node smoke test against that artifact:
```sh
node test/js/smoke.js
```
Lint the generated opam metadata:
```sh
opam lint pgn_to_tex.opam
```
The opam file is generated from `dune-project`, so change dependencies and
package metadata there rather than editing `pgn_to_tex.opam` by hand.
The test suite has one OUnit runner, `test/test_suite.ml`. Add a suite to that
runner instead of starting a second test executable. Bundled PGN fixtures live
in `test/pgn_examples/` and are exercised by the real-world tests.
+217 -68
View File
@@ -1,71 +1,149 @@
# Pgn to Tex
# Pgn_to_tex
## Install
`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.
- Install the Opam package with:
`opam install pgn_to_tex`
- Reference `pgn_to_tex` in the libraries stanza in the relevant dune file
- [API documentation](https://therealowenrees.github.io/pgn_to_tex/)
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
## Usage
## Requirements
```ocaml
open Pgn_to_tex
- OCaml 5.4 or newer
- dune
- A LaTeX installation with `xskak` and `multicol` (see
[LaTeX setup](#latex-setup))
let diagrams_json_stringified =
{| [
{"ply":1,"fen":"rnbqkbnr/pppppppp/8/8/3P4/8/PPP1PPPP/RNBQKBNR b KQkq - 0 1","path":["d4"]},
{"ply":2,"fen":"rnbqkbnr/ppp1pppp/8/3p4/3P4/8/PPP1PPPP/RNBQKBNR w KQkq - 0 2","path":["d4","d5"]},
{"ply":4,"fen":"rnbqkbnr/ppp1pppp/3p4/8/3PP3/8/PPP2PPP/RNBQKBNR b KQkq - 0 3","path":["d4","d5","e4","d6"]}
] |}
## Installation
let diagram_data = parse_diagrams_json diagrams_json_stringified
Install the released package with opam:
let game_tex = to_tex ~diagram_data ~clock:false pgn
```sh
opam install pgn_to_tex
```
This will return a LaTex markdown representation of the PGN file along with chess board diagrams at the specified positions. Clock times can be rendered for both sides if you pass `~clock:true` to the `to_tex` function.
To use the current repository instead, clone it and pin the checkout:
### Diagram JSON schema
```sh
git clone https://github.com/TheRealOwenRees/pgn_to_tex.git
cd pgn_to_tex
opam install .
```
`parse_diagrams_json` accepts a JSON array of objects:
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": "...", "path": ["d4", "d5", "e4", "d6"]},
{"fen": "...", "ply": 5},
{"fen": "...", "ply": 9, "path": ["e4", "e5", "Nf3", "Nc6"]}
{"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 | SAN move sequence from the start of the game (e.g. `["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). Used for mainline positions. |
| `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.
- When a rendered position has a matching `path`, that diagram takes precedence.
- 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.
- Malformed diagram JSON yields empty diagram data instead of raising.
- 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 inside a variation are rendered inline within that variation and at a slightly smaller size (`smallboard`) so they don't dominate the subline.
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 rendered as the document title. When `Subtitle` is also present it
is rendered below the title; a title without a subtitle renders no subtitle
- `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 rendered as the author line when present. Otherwise the author
line is built from `White` and `Black`, including `WhiteElo` and `BlackElo`
when supplied.
- `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 renders an empty date.
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.
@@ -75,7 +153,7 @@ All other headers are ignored.
The following Numeric Annotation Glyphs are rendered:
| NAG | LaTeX |
| --- | --- |
| ------ | ----------------------- |
| `$1` | `!` |
| `$2` | `?` |
| `$3` | `!!` |
@@ -86,8 +164,8 @@ The following Numeric Annotation Glyphs are rendered:
| `$13` | `\infty` |
| `$14` | `\wbetter` |
| `$15` | `\bbetter` |
| `$16` | `\pm` |
| `$17` | `\mp` |
| `$16` | `\ensuremath{\pm}` |
| `$17` | `\ensuremath{\mp}` |
| `$18` | `+-` |
| `$19` | `-+` |
| `$22` | `\zugzwang` |
@@ -99,47 +177,74 @@ The following Numeric Annotation Glyphs are rendered:
Unmapped NAGs are ignored.
Latex preample and document setup markdown is not included in the output. You will need to add something similar to below around the `game_tex` output to create a valid document:
## 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}
game_tex goes here
% Paste the string returned by Pgn_to_tex.to_tex here.
\end{multicols}
\end{document}
```
## Compile a JavaScript version of the library
The relevant packages are:
The JavaScript build is an optional target. Dune skips it when the JavaScript dependencies are not installed. Install them with:
- `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
```
Then compile the code to JavaScript by running:
Build the artifact with:
```
make build
```
or build just the artifact:
```
```sh
dune build bin/pgn_to_tex_js.bc.js
```
This generates the JavaScript file at `_build/default/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.
This JavaScript file is minified and in CJS format, working in both Node and the browser.
A single global `to_tex` function is exposed, accepting the same three arguments as the main library:
The build exposes a single global function with the same three inputs as the
JavaScript entry point:
```js
to_tex(pgnString, diagramJsonString, displayClock);
```
For example:
- `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");
@@ -147,21 +252,65 @@ require("./_build/default/bin/pgn_to_tex_js.bc.js");
const gameTex = globalThis.to_tex("1. e4 e5 2. Nf3", "{}", false);
```
Pass `"{}"` (or an empty string) when there are no diagrams, and `false` to omit clock times. In the browser, the function is available as `window.to_tex` after loading the artifact.
In the browser, the function is available as `window.to_tex` after the
artifact is loaded.
After building the artifact, you can run the Node smoke test with:
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
- dune
- sedlex
- menhir
- yojson
- js_of_ocaml-compiler
- ocamlformat
- ocaml-lsp-server
- ounit2
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).
+2 -2
View File
@@ -16,9 +16,9 @@
(license AGPL-3.0-or-later)
(documentation
https://github.com/therealowenrees/pgn_to_tex/blob/main/README.md)
https://therealowenrees.github.io/pgn_to_tex/)
(version 0.0.2)
(version 0.1.0)
(package
(name pgn_to_tex)
+2 -7
View File
@@ -1,6 +1,6 @@
# This file is generated by dune, edit dune-project instead
opam-version: "2.0"
version: "0.0.2"
version: "0.1.0"
synopsis: "A chess PGN to TeX conversion tool"
description:
"Convert PGN files to LaTeX markdown, including rendered images of selected positions"
@@ -9,7 +9,7 @@ authors: ["Owen Rees <owenrees.dev@gmail.com>"]
license: "AGPL-3.0-or-later"
tags: ["pgn" "latex" "chess" "parser"]
homepage: "https://github.com/therealowenrees/pgn_to_tex"
doc: "https://github.com/therealowenrees/pgn_to_tex/blob/main/README.md"
doc: "https://therealowenrees.github.io/pgn_to_tex/"
bug-reports: "https://github.com/therealowenrees/pgn_to_tex/issues"
depends: [
"dune" {>= "3.21"}
@@ -39,8 +39,3 @@ build: [
]
dev-repo: "git+https://github.com/therealowenrees/pgn_to_tex.git"
x-maintenance-intent: ["(latest)"]
x-ci-accept-failures: [
"ocaml-base-compiler < 5.1.0"
"ocaml-system < 5.1.0"
"ocaml-variants < 5.1.0"
]
-5
View File
@@ -1,5 +0,0 @@
x-ci-accept-failures: [
"ocaml-base-compiler < 5.1.0"
"ocaml-system < 5.1.0"
"ocaml-variants < 5.1.0"
]