https://github.com/marco0560/fontshow
CLI toolkit for font discovery, metadata analysis, inventory validation, and PDF catalog generation from installed system fonts
https://github.com/marco0560/fontshow
cli cross-platform font-analysis font-catalog font-discovery font-inventory font-validation fonts fonttools latex opentype pdf-generation python typography unicode
Last synced: 2 months ago
JSON representation
CLI toolkit for font discovery, metadata analysis, inventory validation, and PDF catalog generation from installed system fonts
- Host: GitHub
- URL: https://github.com/marco0560/fontshow
- Owner: marco0560
- License: mit
- Created: 2025-12-13T20:31:08.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-04-18T22:46:08.000Z (3 months ago)
- Last Synced: 2026-04-18T23:38:30.468Z (3 months ago)
- Topics: cli, cross-platform, font-analysis, font-catalog, font-discovery, font-inventory, font-validation, fonts, fonttools, latex, opentype, pdf-generation, python, typography, unicode
- Language: Python
- Homepage: https://marco0560.github.io/Fontshow/
- Size: 4.61 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Security: docs/security-and-release-policy.md
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Fontshow
[](https://marco0560.github.io/Fontshow/)
[](LICENSE)
[](https://github.com/marco0560/fontshow/actions/workflows/ci.yml)
## What is Fontshow
Fontshow is a command-line toolkit for **font discovery, analysis, validation,
and catalog generation**.
It provides a structured pipeline to:
- inspect the local font environment
- extract a raw inventory of installed fonts
- enrich the inventory with Unicode, script, and language metadata
- validate the resulting data against a formal schema
- generate human-readable artifacts (e.g. PDF catalogs)
Fontshow is designed to be:
- reproducible
- testable
- schema-driven
- explicit about its execution model and return codes
It generates .tex files that should be compiled with LuaLaTeX to produce PDF catalogs.
## Quick start
Fontshow exposes a unified command-line interface through a dispatcher.
The recommended entrypoint is:
```bash
fontshow [options]
```
A typical end-to-end workflow is:
```bash
fontshow preflight
fontshow dump-fonts
fontshow parse-inventory
fontshow create-catalog
```
Each step consumes the output of the previous one and produces a well-defined
artifact for the next stage.
## Features
- Cross-platform font discovery (Linux and Windows)
- Deep font metadata extraction using fontTools
- Script and language inference based on Unicode coverage
- Structured JSON font inventory
- LaTeX catalog generation (LuaLaTeX)
- Reproducible, inventory-driven workflow
## CLI design notes
Fontshow commands follow a strict execution contract:
```python
def main(args) -> int
```
- Argument parsing is handled by the dispatcher
- Command logic never calls `sys.exit()`
- Each command returns an explicit exit code
- The dispatcher is responsible for process termination
This guarantees consistent behavior across all commands and simplifies
testing and automation.
For the decision history behind these conventions, see
`docs/decisions/index.md`.
## Notes on direct module execution
Commands can also be executed directly via Python, for example:
```bash
python -m fontshow.cli.dump_fonts --help
```
This mode is supported primarily for development and debugging.
The unified dispatcher (`fontshow `) is the authoritative and
documented user interface.
## Pipeline overview
```text
dump_fonts → parse_font_inventory → create_catalog
```
Each stage consumes structured data produced by the previous one and
does not re-inspect font binaries unnecessarily.
## Developer documentation
For contributors and maintainers:
- [Repository architecture](docs/architecture.md)
- [Codebase map](docs/codebase-map.md)
---
## Installation
Clone the repository and create a virtual environment:
```bash
git clone https://github.com/marco0560/Fontshow.git
cd Fontshow
python3 scripts/bootstrap_dev_environment.py
```
This bootstrap path creates `.venv`, upgrades packaging tools, installs
Fontshow in editable mode with the repository development dependencies,
applies repo-local Git configuration, and runs the standard validation
surface.
If you want the documentation toolchain as well, use:
```bash
python3 scripts/bootstrap_dev_environment.py --with-docs
```
The source package uses the standard `src/` layout under
`src/fontshow/`.
## Repository cleanup utility
The repository includes a helper script to remove generated artifacts and
temporary files while keeping the working tree clean:
```bash
python scripts/clean_repo.py
```
The script removes **only files ignored by Git** (according to `.gitignore`)
and never deletes tracked files.
A dry-run mode is available to safely preview the cleanup:
```bash
python scripts/clean_repo.py --dry-run
```
### Safety guarantees
Some paths are explicitly protected and will **never be removed**, even if
ignored by Git. In particular:
- `.venv` (Python virtual environment)
- `.vscode` (Virtual Studio Code configuration)
- `node_modules` (Nodejs modules)
This ensures that the cleanup process is safe to run during development
without risking the local working environment.
---
## Available commands
| Command | Description |
|----------------------------|---------------------------------------------|
| `fontshow preflight` | Run environment and dependency checks |
| `fontshow dump-fonts` | Extract a raw font inventory |
| `fontshow parse-inventory` | Enrich and validate a font inventory |
| `fontshow create-catalog` | Generate output artifacts from an inventory |
Use `--help` on any command to see available options:
```bash
fontshow dump-fonts --help
```
Direct execution of files such as:
```bash
python src/fontshow/cli/dump_fonts.py
```
is not supported and may produce inconsistent behavior.
Use the unified dispatcher instead:
```bash
fontshow dump-fonts --help
fontshow parse-inventory --help
fontshow create-catalog --help
```
Direct module execution via `python -m` is supported primarily for development
and debugging:
```bash
python -m fontshow.cli.dump_fonts --help
python -m fontshow.cli.parse_inventory --help
python -m fontshow.cli.create_catalog --help
```
The authoritative, user-facing interface is always `fontshow `.
---
## Available tools
### Dump system fonts
Generate a JSON inventory of installed fonts:
```bash
fontshow dump-fonts \
--output font_inventory.json
```
This command produces a versioned inventory including:
- font metadata
- coverage information
- environment and system context
---
### Parse and normalize inventory
Normalize and enrich a previously generated inventory:
```bash
fontshow parse-inventory \
--output font_inventory_enriched.json
```
An optional soft validation of the inventory structure can be performed with:
```bash
fontshow parse-inventory \
--validate-inventory
```
---
### Generate LaTeX catalog
Generate a LaTeX catalog from a parsed inventory:
```bash
fontshow create-catalog
```
Additional options are available for:
- test font selection
- script selection
- language selection
- debug output
- LaTeX generation control
See:
```bash
fontshow create-catalog --help
```
---
## Versioning
Fontshow follows semantic versioning:
- **MAJOR**: breaking changes
- **MINOR**: new features, backward-compatible
- **PATCH**: bug fixes
The current version is exposed via:
```python
fontshow.__version__
```
Each generated inventory records:
- the schema version
- the tool version
- the execution environment
---
## Documentation
- `cli.md` — command-line interface reference
- `decisions.md` — architectural and design decisions
- Inventory schema documentation: `docs/schema/index.md`
- `data_dictionary.md` — meaning of inventory fields
The documentation is intentionally split between **what the tool does**
and **why it is designed this way**.
## Engineering Notes
Development notes and lessons learned are tracked in:
- `docs/engineering/lessons-learned.md`
These notes are non-normative and intended for maintainers.
## License
Fontshow is released under the MIT License.