mirror of
https://github.com/TheRealOwenRees/pgn_to_tex.git
synced 2026-11-18 12:52:06 +00:00
docs: prepare 0.1.0 release metadata and migration
This commit is contained in:
@@ -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
|
## 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.
|
- 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
@@ -1,13 +1,68 @@
|
|||||||
# Contributing
|
# 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
|
## 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`.
|
- 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.
|
- 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.
|
||||||
|
|||||||
@@ -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:
|
- [API documentation](https://therealowenrees.github.io/pgn_to_tex/)
|
||||||
`opam install pgn_to_tex`
|
- [Changelog](CHANGELOG.md)
|
||||||
- Reference `pgn_to_tex` in the libraries stanza in the relevant dune file
|
- [Contributing](CONTRIBUTING.md)
|
||||||
|
|
||||||
## Usage
|
## Requirements
|
||||||
|
|
||||||
```ocaml
|
- OCaml 5.4 or newer
|
||||||
open Pgn_to_tex
|
- dune
|
||||||
|
- A LaTeX installation with `xskak` and `multicol` (see
|
||||||
|
[LaTeX setup](#latex-setup))
|
||||||
|
|
||||||
let diagrams_json_stringified =
|
## Installation
|
||||||
{| [
|
|
||||||
{"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"]}
|
|
||||||
] |}
|
|
||||||
|
|
||||||
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
|
```json
|
||||||
[
|
[
|
||||||
{"fen": "...", "path": ["d4", "d5", "e4", "d6"]},
|
{"fen": "8/8/8/8/8/8/4K3/7k w - - 0 1", "path": ["d4", "d5", "e4", "d6"]},
|
||||||
{"fen": "...", "ply": 5},
|
{"fen": "8/8/8/8/8/8/4K3/7k w - - 0 1", "ply": 5},
|
||||||
{"fen": "...", "ply": 9, "path": ["e4", "e5", "Nf3", "Nc6"]}
|
{"fen": "8/8/8/8/8/8/4K3/7k w - - 0 1", "ply": 9, "path": ["e4", "e5", "Nf3", "Nc6"]}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
| Field | Type | Required | Description |
|
| Field | Type | Required | Description |
|
||||||
| ------ | --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
| ------ | --------------- | --------------- | ----------- |
|
||||||
| `fen` | string | yes | The board position to render. |
|
| `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. |
|
| `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). Used for mainline 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:
|
Resolution rules:
|
||||||
|
|
||||||
- An entry may carry `path`, `ply`, or both.
|
- 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`.
|
- 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.
|
- Variation diagrams require `path`; a `ply`-only entry only matches mainline
|
||||||
- Malformed diagram JSON yields empty diagram data instead of raising.
|
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
|
## Supported headers
|
||||||
|
|
||||||
The following PGN headers are rendered:
|
The following PGN headers are rendered:
|
||||||
|
|
||||||
- `Event` is used as the title when `Title` is absent.
|
- `Event` is used as the title when `Title` is absent.
|
||||||
- `Title` is rendered as the document title. When `Subtitle` is also present it
|
- `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
|
is rendered below the title. A title without a subtitle renders no subtitle
|
||||||
block.
|
block.
|
||||||
- `Author` is rendered as the author line when present. Otherwise the author
|
- `Author` is the author line when present. Otherwise the author line is built
|
||||||
line is built from `White` and `Black`, including `WhiteElo` and `BlackElo`
|
from `White` and `Black`, including `WhiteElo` and `BlackElo` when supplied.
|
||||||
when supplied.
|
|
||||||
- `Date` and `Site` are combined into the date line. An empty date with a site
|
- `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.
|
- `Result` is rendered in bold at the end of the game.
|
||||||
|
|
||||||
All other headers are ignored.
|
All other headers are ignored.
|
||||||
@@ -74,72 +152,99 @@ All other headers are ignored.
|
|||||||
|
|
||||||
The following Numeric Annotation Glyphs are rendered:
|
The following Numeric Annotation Glyphs are rendered:
|
||||||
|
|
||||||
| NAG | LaTeX |
|
| NAG | LaTeX |
|
||||||
| --- | --- |
|
| ------ | ----------------------- |
|
||||||
| `$1` | `!` |
|
| `$1` | `!` |
|
||||||
| `$2` | `?` |
|
| `$2` | `?` |
|
||||||
| `$3` | `!!` |
|
| `$3` | `!!` |
|
||||||
| `$4` | `??` |
|
| `$4` | `??` |
|
||||||
| `$5` | `!?` |
|
| `$5` | `!?` |
|
||||||
| `$6` | `?!` |
|
| `$6` | `?!` |
|
||||||
| `$10` | `=` |
|
| `$10` | `=` |
|
||||||
| `$13` | `\infty` |
|
| `$13` | `\infty` |
|
||||||
| `$14` | `\wbetter` |
|
| `$14` | `\wbetter` |
|
||||||
| `$15` | `\bbetter` |
|
| `$15` | `\bbetter` |
|
||||||
| `$16` | `\pm` |
|
| `$16` | `\ensuremath{\pm}` |
|
||||||
| `$17` | `\mp` |
|
| `$17` | `\ensuremath{\mp}` |
|
||||||
| `$18` | `+-` |
|
| `$18` | `+-` |
|
||||||
| `$19` | `-+` |
|
| `$19` | `-+` |
|
||||||
| `$22` | `\zugzwang` |
|
| `$22` | `\zugzwang` |
|
||||||
| `$32` | `\development` |
|
| `$32` | `\development` |
|
||||||
| `$36` | `\initiative` |
|
| `$36` | `\initiative` |
|
||||||
| `$40` | `\attack` |
|
| `$40` | `\attack` |
|
||||||
| `$44` | `\compensation` |
|
| `$44` | `\compensation` |
|
||||||
| `$132` | `\counterplay` |
|
| `$132` | `\counterplay` |
|
||||||
|
|
||||||
Unmapped NAGs are ignored.
|
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{document}
|
||||||
\begin{multicols}{2}
|
\begin{multicols}{2}
|
||||||
game_tex goes here
|
% Paste the string returned by Pgn_to_tex.to_tex here.
|
||||||
\end{multicols}
|
\end{multicols}
|
||||||
\end{document}
|
\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
|
opam install js_of_ocaml js_of_ocaml-ppx
|
||||||
```
|
```
|
||||||
|
|
||||||
Then compile the code to JavaScript by running:
|
Build the artifact with:
|
||||||
|
|
||||||
```
|
```sh
|
||||||
make build
|
|
||||||
```
|
|
||||||
|
|
||||||
or build just the artifact:
|
|
||||||
|
|
||||||
```
|
|
||||||
dune build bin/pgn_to_tex_js.bc.js
|
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.
|
The build exposes a single global function with the same three inputs as the
|
||||||
|
JavaScript entry point:
|
||||||
A single global `to_tex` function is exposed, accepting the same three arguments as the main library:
|
|
||||||
|
|
||||||
```js
|
```js
|
||||||
to_tex(pgnString, diagramJsonString, displayClock);
|
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
|
```js
|
||||||
require("./_build/default/bin/pgn_to_tex_js.bc.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);
|
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
|
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
|
## Dependencies
|
||||||
|
|
||||||
- dune
|
Runtime and build dependencies:
|
||||||
- sedlex
|
|
||||||
- menhir
|
- `ocaml` >= 5.4
|
||||||
- yojson
|
- `dune` >= 3.21
|
||||||
- js_of_ocaml-compiler
|
- `sedlex` >= 3.7
|
||||||
- ocamlformat
|
- `menhir` >= 20260209
|
||||||
- ocaml-lsp-server
|
- `yojson` >= 3.0
|
||||||
- ounit2
|
|
||||||
|
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
@@ -16,9 +16,9 @@
|
|||||||
(license AGPL-3.0-or-later)
|
(license AGPL-3.0-or-later)
|
||||||
|
|
||||||
(documentation
|
(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
|
(package
|
||||||
(name pgn_to_tex)
|
(name pgn_to_tex)
|
||||||
|
|||||||
+2
-7
@@ -1,6 +1,6 @@
|
|||||||
# This file is generated by dune, edit dune-project instead
|
# This file is generated by dune, edit dune-project instead
|
||||||
opam-version: "2.0"
|
opam-version: "2.0"
|
||||||
version: "0.0.2"
|
version: "0.1.0"
|
||||||
synopsis: "A chess PGN to TeX conversion tool"
|
synopsis: "A chess PGN to TeX conversion tool"
|
||||||
description:
|
description:
|
||||||
"Convert PGN files to LaTeX markdown, including rendered images of selected positions"
|
"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"
|
license: "AGPL-3.0-or-later"
|
||||||
tags: ["pgn" "latex" "chess" "parser"]
|
tags: ["pgn" "latex" "chess" "parser"]
|
||||||
homepage: "https://github.com/therealowenrees/pgn_to_tex"
|
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"
|
bug-reports: "https://github.com/therealowenrees/pgn_to_tex/issues"
|
||||||
depends: [
|
depends: [
|
||||||
"dune" {>= "3.21"}
|
"dune" {>= "3.21"}
|
||||||
@@ -39,8 +39,3 @@ build: [
|
|||||||
]
|
]
|
||||||
dev-repo: "git+https://github.com/therealowenrees/pgn_to_tex.git"
|
dev-repo: "git+https://github.com/therealowenrees/pgn_to_tex.git"
|
||||||
x-maintenance-intent: ["(latest)"]
|
x-maintenance-intent: ["(latest)"]
|
||||||
x-ci-accept-failures: [
|
|
||||||
"ocaml-base-compiler < 5.1.0"
|
|
||||||
"ocaml-system < 5.1.0"
|
|
||||||
"ocaml-variants < 5.1.0"
|
|
||||||
]
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
x-ci-accept-failures: [
|
|
||||||
"ocaml-base-compiler < 5.1.0"
|
|
||||||
"ocaml-system < 5.1.0"
|
|
||||||
"ocaml-variants < 5.1.0"
|
|
||||||
]
|
|
||||||
Reference in New Issue
Block a user