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

Fontshow exposes a unified command-line interface through a dispatcher.

The recommended entrypoint is:

fontshow <command> [options]

A typical end-to-end workflow is:

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.

• 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 (XeLaTeX / LuaLaTeX)
• Reproducible, inventory-driven workflow

Fontshow commands follow a strict execution contract:

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.

Commands can also be executed directly via Python, for example:

python -m fontshow.cli.dump_fonts --help

This mode is supported primarily for development and debugging.

The unified dispatcher (fontshow <command>) is the authoritative and documented user interface.

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.

For contributors and maintainers:

• Repository architecture
• Codebase map

Clone the repository and create a virtual environment:

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:

python3 scripts/bootstrap_dev_environment.py --with-docs

The source package uses the standard src/ layout under src/fontshow/.

The repository includes a helper script to remove generated artifacts and temporary files while keeping the working tree clean:

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:

python scripts/clean_repo.py --dry-run

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.

Use --help on any command to see available options:

fontshow dump-fonts --help

Direct execution of files such as:

python src/fontshow/cli/dump_fonts.py

is not supported and may produce inconsistent behavior.

Use the unified dispatcher instead:

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:

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 <command>.

Generate a JSON inventory of installed fonts:

fontshow dump-fonts \
  --output font_inventory.json

This command produces a versioned inventory including:

• font metadata
• coverage information
• environment and system context

Normalize and enrich a previously generated inventory:

fontshow parse-inventory \
  --output font_inventory_enriched.json

An optional soft validation of the inventory structure can be performed with:

fontshow parse-inventory \
  --validate-inventory

Generate a LaTeX catalog from a parsed inventory:

fontshow create-catalog

Additional options are available for:

• test font selection
• debug output
• LaTeX generation control

See:

fontshow create-catalog --help

Fontshow follows semantic versioning:

• MAJOR: breaking changes
• MINOR: new features, backward-compatible
• PATCH: bug fixes

The current version is exposed via:

fontshow.__version__

Each generated inventory records:

• the schema version
• the tool version
• the execution environment

• 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.

Development notes and lessons learned are tracked in:

• docs/engineering/lessons-learned.md

These notes are non-normative and intended for maintainers.

Fontshow is released under the MIT License.