{"id":34668121,"url":"https://github.com/marco0560/fontshow","last_synced_at":"2026-05-17T20:13:05.645Z","repository":{"id":330493360,"uuid":"1115920540","full_name":"marco0560/Fontshow","owner":"marco0560","description":"CLI toolkit for font discovery, metadata analysis, inventory validation, and PDF catalog generation from installed system fonts","archived":false,"fork":false,"pushed_at":"2026-04-18T22:46:08.000Z","size":4836,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T23:38:30.468Z","etag":null,"topics":["cli","cross-platform","font-analysis","font-catalog","font-discovery","font-inventory","font-validation","fonts","fonttools","latex","opentype","pdf-generation","python","typography","unicode"],"latest_commit_sha":null,"homepage":"https://marco0560.github.io/Fontshow/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marco0560.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-and-release-policy.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-13T20:31:08.000Z","updated_at":"2026-04-18T22:46:10.000Z","dependencies_parsed_at":"2026-02-18T12:03:31.333Z","dependency_job_id":null,"html_url":"https://github.com/marco0560/Fontshow","commit_stats":null,"previous_names":["marco0560/fontshow"],"tags_count":180,"template":false,"template_full_name":null,"purl":"pkg:github/marco0560/Fontshow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marco0560%2FFontshow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marco0560%2FFontshow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marco0560%2FFontshow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marco0560%2FFontshow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marco0560","download_url":"https://codeload.github.com/marco0560/Fontshow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marco0560%2FFontshow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32203362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T20:19:26.138Z","status":"ssl_error","status_checked_at":"2026-04-23T20:19:23.520Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cross-platform","font-analysis","font-catalog","font-discovery","font-inventory","font-validation","fonts","fonttools","latex","opentype","pdf-generation","python","typography","unicode"],"created_at":"2025-12-24T19:32:29.285Z","updated_at":"2026-05-10T15:17:49.930Z","avatar_url":"https://github.com/marco0560.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fontshow\n\n[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://marco0560.github.io/Fontshow/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![CI](https://github.com/marco0560/fontshow/actions/workflows/ci.yml/badge.svg)](https://github.com/marco0560/fontshow/actions/workflows/ci.yml)\n\n## What is Fontshow\n\nFontshow is a command-line toolkit for **font discovery, analysis, validation,\nand catalog generation**.\n\nIt provides a structured pipeline to:\n\n- inspect the local font environment\n- extract a raw inventory of installed fonts\n- enrich the inventory with Unicode, script, and language metadata\n- validate the resulting data against a formal schema\n- generate human-readable artifacts (e.g. PDF catalogs)\n\nFontshow is designed to be:\n\n- reproducible\n- testable\n- schema-driven\n- explicit about its execution model and return codes\n\nIt generates .tex files that should be compiled with LuaLaTeX to produce PDF catalogs.\n\n## Quick start\n\nFontshow exposes a unified command-line interface through a dispatcher.\n\nThe recommended entrypoint is:\n\n```bash\nfontshow \u003ccommand\u003e [options]\n```\n\nA typical end-to-end workflow is:\n\n```bash\nfontshow preflight\nfontshow dump-fonts\nfontshow parse-inventory\nfontshow create-catalog\n```\n\nEach step consumes the output of the previous one and produces a well-defined\nartifact for the next stage.\n\n## Features\n\n- Cross-platform font discovery (Linux and Windows)\n- Deep font metadata extraction using fontTools\n- Script and language inference based on Unicode coverage\n- Structured JSON font inventory\n- LaTeX catalog generation (LuaLaTeX)\n- Reproducible, inventory-driven workflow\n\n## CLI design notes\n\nFontshow commands follow a strict execution contract:\n\n```python\ndef main(args) -\u003e int\n```\n\n- Argument parsing is handled by the dispatcher\n- Command logic never calls `sys.exit()`\n- Each command returns an explicit exit code\n- The dispatcher is responsible for process termination\n\nThis guarantees consistent behavior across all commands and simplifies\ntesting and automation.\n\nFor the decision history behind these conventions, see\n`docs/decisions/index.md`.\n\n## Notes on direct module execution\n\nCommands can also be executed directly via Python, for example:\n\n```bash\npython -m fontshow.cli.dump_fonts --help\n```\n\nThis mode is supported primarily for development and debugging.\n\nThe unified dispatcher (`fontshow \u003ccommand\u003e`) is the authoritative and\ndocumented user interface.\n\n## Pipeline overview\n\n```text\ndump_fonts → parse_font_inventory → create_catalog\n```\n\nEach stage consumes structured data produced by the previous one and\ndoes not re-inspect font binaries unnecessarily.\n\n## Developer documentation\n\nFor contributors and maintainers:\n\n- [Repository architecture](docs/architecture.md)\n- [Codebase map](docs/codebase-map.md)\n\n---\n\u003c!-- cheatsheet:start --\u003e\n\n## Installation\n\nClone the repository and create a virtual environment:\n\n```bash\ngit clone https://github.com/marco0560/Fontshow.git\ncd Fontshow\npython3 scripts/bootstrap_dev_environment.py\n```\n\nThis bootstrap path creates `.venv`, upgrades packaging tools, installs\nFontshow in editable mode with the repository development dependencies,\napplies repo-local Git configuration, and runs the standard validation\nsurface.\n\nIf you want the documentation toolchain as well, use:\n\n```bash\npython3 scripts/bootstrap_dev_environment.py --with-docs\n```\n\nThe source package uses the standard `src/` layout under\n`src/fontshow/`.\n\n\u003c!-- cheatsheet:end --\u003e\n\n\u003c!-- cheatsheet:start --\u003e\n\n## Repository cleanup utility\n\nThe repository includes a helper script to remove generated artifacts and\ntemporary files while keeping the working tree clean:\n\n```bash\npython scripts/clean_repo.py\n```\n\u003c!-- cheatsheet:end --\u003e\n\nThe script removes **only files ignored by Git** (according to `.gitignore`)\nand never deletes tracked files.\n\nA dry-run mode is available to safely preview the cleanup:\n\n\u003c!-- cheatsheet:start --\u003e\n```bash\npython scripts/clean_repo.py --dry-run\n```\n\u003c!-- cheatsheet:end --\u003e\n\n### Safety guarantees\n\nSome paths are explicitly protected and will **never be removed**, even if\nignored by Git. In particular:\n\n- `.venv` (Python virtual environment)\n- `.vscode` (Virtual Studio Code configuration)\n- `node_modules` (Nodejs modules)\n\nThis ensures that the cleanup process is safe to run during development\nwithout risking the local working environment.\n\n---\n\u003c!-- cheatsheet:start --\u003e\n\n## Available commands\n\n| Command                    | Description                                 |\n|----------------------------|---------------------------------------------|\n| `fontshow preflight`       | Run environment and dependency checks       |\n| `fontshow dump-fonts`      | Extract a raw font inventory                |\n| `fontshow parse-inventory` | Enrich and validate a font inventory        |\n| `fontshow create-catalog`  | Generate output artifacts from an inventory |\n\nUse `--help` on any command to see available options:\n\n```bash\nfontshow dump-fonts --help\n```\n\u003c!-- cheatsheet:end --\u003e\n\nDirect execution of files such as:\n\n```bash\npython src/fontshow/cli/dump_fonts.py\n```\n\nis not supported and may produce inconsistent behavior.\n\nUse the unified dispatcher instead:\n\n```bash\nfontshow dump-fonts --help\nfontshow parse-inventory --help\nfontshow create-catalog --help\n```\n\nDirect module execution via `python -m` is supported primarily for development\nand debugging:\n\n```bash\npython -m fontshow.cli.dump_fonts --help\npython -m fontshow.cli.parse_inventory --help\npython -m fontshow.cli.create_catalog --help\n```\n\nThe authoritative, user-facing interface is always `fontshow \u003ccommand\u003e`.\n\n---\n\n\u003c!-- cheatsheet:start --\u003e\n\n## Available tools\n\n### Dump system fonts\n\nGenerate a JSON inventory of installed fonts:\n\n```bash\nfontshow dump-fonts \\\n  --output font_inventory.json\n```\n\u003c!-- cheatsheet:end --\u003e\n\nThis command produces a versioned inventory including:\n\n- font metadata\n- coverage information\n- environment and system context\n\n---\n\n\u003c!-- cheatsheet:start --\u003e\n### Parse and normalize inventory\n\nNormalize and enrich a previously generated inventory:\n\n```bash\nfontshow parse-inventory \\\n  --output font_inventory_enriched.json\n```\n\u003c!-- cheatsheet:end --\u003e\n\n\u003c!-- cheatsheet:start --\u003e\nAn optional soft validation of the inventory structure can be performed with:\n\n```bash\nfontshow parse-inventory \\\n  --validate-inventory\n```\n\u003c!-- cheatsheet:end --\u003e\n\n---\n\n\u003c!-- cheatsheet:start --\u003e\n### Generate LaTeX catalog\n\nGenerate a LaTeX catalog from a parsed inventory:\n\n```bash\nfontshow create-catalog\n```\n\u003c!-- cheatsheet:end --\u003e\n\nAdditional options are available for:\n\n- test font selection\n- script selection\n- language selection\n- debug output\n- LaTeX generation control\n\nSee:\n\n```bash\nfontshow create-catalog --help\n```\n\n---\n\n## Versioning\n\nFontshow follows semantic versioning:\n\n- **MAJOR**: breaking changes\n- **MINOR**: new features, backward-compatible\n- **PATCH**: bug fixes\n\nThe current version is exposed via:\n\n```python\nfontshow.__version__\n```\n\nEach generated inventory records:\n\n- the schema version\n- the tool version\n- the execution environment\n\n---\n\n## Documentation\n\n- `cli.md` — command-line interface reference\n- `decisions.md` — architectural and design decisions\n- Inventory schema documentation: `docs/schema/index.md`\n- `data_dictionary.md` — meaning of inventory fields\n\nThe documentation is intentionally split between **what the tool does**\nand **why it is designed this way**.\n\n## Engineering Notes\n\nDevelopment notes and lessons learned are tracked in:\n\n- `docs/engineering/lessons-learned.md`\n\nThese notes are non-normative and intended for maintainers.\n\n## License\n\nFontshow is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarco0560%2Ffontshow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarco0560%2Ffontshow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarco0560%2Ffontshow/lists"}