From 4f50ff020eb0633ce04ad10c62b4e5b9b724327c Mon Sep 17 00:00:00 2001 From: Owen Date: Fri, 23 Oct 2026 15:10:00 +0200 Subject: [PATCH] docs: prepare 0.1.0 release metadata and migration --- CHANGELOG.md | 64 ++++++++ CONTRIBUTING.md | 63 +++++++- README.md | 327 ++++++++++++++++++++++++++++----------- dune-project | 4 +- pgn_to_tex.opam | 9 +- pgn_to_tex.opam.template | 5 - 6 files changed, 365 insertions(+), 107 deletions(-) delete mode 100644 pgn_to_tex.opam.template 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