Converter collection

Feel free to file an issue if you are looking for help implementing a migration adapter for your pre-existing terminology data.

convert.paneron.org

Development

NOTE: This started to aid in migration to Glossarist, but being expanded to cover other data models. The repository may soon be renamed and moved to a more appropriate place.

This is a TypeScript monorepo.

The packages include:

• Core logic for converting from different formats to Glossarist
• Common interfaces and tools
• Web GUI and in future CLI for invoking those adapters/convertors

Right now, packages are not published separately. Some packages may be published separately in future, while other packages (e.g., webgui or cli) may only be deployed or distributed.

Known issue: compile scripts fail

gr-sheet convertor package’s compile script, and by extension the top-level compile-all script, fail due to the way Paneron’s GR extension is packaged.

This only causes typechecking errors due to “missing” dependencies (which are not to be included and are supposed to be supplied by the host), and does not cause the failure of the build command.

To be fixed.

Pre-requisites

Below instructions will expect you to either use NodeJS 18.18 (there is an incompatibility with newer Node versions) with Yarn on your host machine (no-Docker approach is labeled “host” below) or to have Docker (e.g., as Docker Desktop).

TODO: ways to invoke through Docker are a bit long, perhaps there could be a Makefile or something.

Preparing a Docker image

Project includes a simple tsls.Dockerfile, by default it runs TypeScript language server but the command can be overridden (see examples below).

Build it like this, executed in repository root:

docker build -f tsls.Dockerfile --build-arg "project_path=$(pwd)" -t "<your-image-label>" .

Configuring LSP in your editor

Host: hopefully your IDE will understand how it works?

Docker: configure your editor to run the container. This will mount project root in read-only mode at the same path, so that LSP hints work seamlessly:

docker container run --interactive --rm --network=none \
   --workdir="$(pwd)" \
   --volume="$(pwd):$(pwd):ro" \
   "<your-image-label>"

Building Web GUI

These examples supply --debug flag, but you can remove it to suppress unnecessary logging if build process is sufficiently stable.

Host: yarn workspace webgui build --debug

Docker:

docker container run --interactive --network=none \
   --workdir="$(pwd)" \
   --volume="$(pwd):$(pwd):ro" \
   --volume="$(pwd)/webgui-dist:/tmp/dist" \
   "<your-image-label>" \
   yarn workspace webgui build --distdir "/tmp/dist" --debug

This will output Web GUI files, ready to serve, in webgui-dist directory under repository root.

Serving Web GUI locally

Same as above, but add --serve flag in addition to --debug. It will be served at localhost:8080.

Watching while serving

This should be run from repo root, not from webgui package:

yarn workspace webgui build --serve --watch $(pwd)/packages/gr-sheet/src

TODO: complete this section.

Compiling all

Host: to compile all packages, run yarn compile-all; to compile a single package, run yarn workspace <package> compile (it may fail if local dependencies were not compiled).

Docker: to compile all, run:

docker container run --interactive --network=none \
   --workdir="$(pwd)" \
   --volume="$(pwd):$(pwd)" \
   "<your-image-label>" \
   yarn compile-all

NOTE: This command mounts the volume in read-write mode, because the way scripts work currently requires tsc to be able to write to each package’s compiled directory. Entry points in each package.json are specified as compiled/....

Making TS see changes across packages

Say you’re working on two packages in this repo, and need package A to see changes in package B without publishing anything on NPM. Run the compile command against package B’s workspace, or just compile all packages.

Working with Yarn monorepo

Running a command against a subpackage works like this:

.../migration-adapters$ yarn workspace @riboseinc/glossarist-x3duom compile

This also applies to commands like yarn add, yarn remove, etc.

TODO: This example assumes NodeJS is installed on your machine. It’s probably possible to do this using the same container as above.

Creating a new package

1. Create corresponding directory under packages/.

2. Create a tsconfig.json, using an existing package as an example.

   • You will almost certainly extent the repo-wide tsconfig.json.
   • You need to provide the include option.
   • You will often find it necessary to override compilerOptions.lib.

3. Create a package.json, using an existing package as an example.

   • If you publish the package, its name would have to follow <org namespace>/package-name. This full name will become the workspace idnetifier you specify when executing yarn workspace <workspace ID> <some command>.

   • Otherwise you can use any short name.

Building for distribution

TBD.

Release flow

TBD.