diff --git a/CHANGELOG.md b/CHANGELOG.md
index b0c5168..4a11f19 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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
+ .
+- 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.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f8bfd00..b608bbf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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.
diff --git a/README.md b/README.md
index f2ba197..57ee7e2 100644
--- a/README.md
+++ b/README.md
@@ -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. |
+| 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.
-- 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.
@@ -74,72 +152,99 @@ All other headers are ignored.
The following Numeric Annotation Glyphs are rendered:
-| NAG | LaTeX |
-| --- | --- |
-| `$1` | `!` |
-| `$2` | `?` |
-| `$3` | `!!` |
-| `$4` | `??` |
-| `$5` | `!?` |
-| `$6` | `?!` |
-| `$10` | `=` |
-| `$13` | `\infty` |
-| `$14` | `\wbetter` |
-| `$15` | `\bbetter` |
-| `$16` | `\pm` |
-| `$17` | `\mp` |
-| `$18` | `+-` |
-| `$19` | `-+` |
-| `$22` | `\zugzwang` |
-| `$32` | `\development` |
-| `$36` | `\initiative` |
-| `$40` | `\attack` |
-| `$44` | `\compensation` |
-| `$132` | `\counterplay` |
+| 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.
-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).
diff --git a/dune-project b/dune-project
index 1d54260..8076767 100644
--- a/dune-project
+++ b/dune-project
@@ -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)
diff --git a/pgn_to_tex.opam b/pgn_to_tex.opam
index 1e89511..ee230a3 100644
--- a/pgn_to_tex.opam
+++ b/pgn_to_tex.opam
@@ -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 "]
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"
-]
\ No newline at end of file
diff --git a/pgn_to_tex.opam.template b/pgn_to_tex.opam.template
deleted file mode 100644
index 8ac53ac..0000000
--- a/pgn_to_tex.opam.template
+++ /dev/null
@@ -1,5 +0,0 @@
-x-ci-accept-failures: [
- "ocaml-base-compiler < 5.1.0"
- "ocaml-system < 5.1.0"
- "ocaml-variants < 5.1.0"
-]
\ No newline at end of file