Skip to content

create-catalog

This module generates a printable LaTeX catalog from a normalized Fontshow font inventory.

It is the final stage of the pipeline and focuses exclusively on rendering and layout.

Responsibilities

  • Group fonts by family
  • Select representative samples
  • Render LaTeX blocks
  • Generate a complete XeLaTeX/LuaLaTeX document

Scope and non-responsibilities

The create-catalog stage is responsible for transforming a validated inventory into final output artifacts.

It operates exclusively on already validated input and does not perform:

  • font discovery
  • metadata extraction
  • inventory normalization
  • semantic or structural validation
  • error recovery for upstream stages

In particular:

  • all validation errors must be resolved before this stage
  • input data is assumed to be consistent and complete
  • failures at this stage indicate output or rendering issues, not data errors

This separation ensures that:

  • validation logic remains centralized
  • output generation remains deterministic
  • failures are easy to attribute to their correct stage

Inventory Diagnostics

During catalog generation, Fontshow may emit lightweight diagnostics about the input inventory before rendering begins.

These diagnostics are informational and help identify inventories with poor language coverage, but they do not introduce a separate strict-mode CLI contract for create-catalog.

Validation of inventory structure and semantics remains the responsibility of upstream stages such as parse-inventory and validate-inventory.

Effective filtering behavior

create-catalog now distinguishes clearly between normal execution and test-subset execution.

  • Plain fontshow create-catalog uses the full inventory.
  • fontshow create-catalog --test uses the platform-specific DEFAULT_TEST_FONTS subset.
  • fontshow create-catalog --test-font NAME restricts rendering to the explicitly requested family names.
  • fontshow create-catalog --test --test-font NAME combines the default test subset with additional explicit families.
  • fontshow create-catalog --list-test-fonts reports the effective test subset and exits without generating a catalog.

Inventory diagnostics are emitted for the effective render set after filtering, not for the full loaded inventory.

Loadability Validation

create-catalog now uses persisted LuaLaTeX loadability from the inventory by default.

Behavior:

  • When persisted loadability is present and the runtime fingerprint matches the current environment, create-catalog trusts the persisted per-font loadability.lualatex state.
  • When persisted loadability is missing, incomplete, or stale, create-catalog falls back to best-effort runtime LuaLaTeX probing for the affected fonts only.
  • Fonts proven unloadable are skipped deterministically and reported in the generated .tex output under an unloadable-font section.

Notes:

  • The normal fast path is to reuse persisted loadability produced by dump-fonts.
  • Runtime fallback remains slower because it still uses per-font probes in the catalog stage.
  • The fallback path uses the same render policy as catalog generation so fontspec script options remain aligned between probing and final rendering.
  • There is no longer a --validate-loadability flag on create-catalog.

API reference

fontshow.cli.create_catalog

Fontshow create-catalog CLI command.

This module implements the catalog generation stage of the Fontshow pipeline and provides the CLI entry point for the create-catalog command.

Responsibilities

  • Load and strictly validate the current inventory schema.
  • Run semantic and platform validation checks before catalog generation.
  • Orchestrate catalog preparation steps (filtering, grouping, diagnostics).
  • Invoke catalog helpers that transform normalized font descriptors into deterministic LaTeX output.

Design principles

The module acts as the orchestration layer for catalog generation. Rendering logic lives in the fontshow.catalog domain modules, while inventory analysis and validation belong to the fontshow.inventory subsystem. This separation keeps the CLI entry point focused on workflow coordination.

Architectural role

This module belongs to the CLI interface layer and coordinates the catalog generation workflow between the inventory subsystem and the catalog rendering helpers.

build_parser 

build_parser(parser: ArgumentParser) -> None

Register create-catalog CLI arguments on an existing parser.

Parameters

parser : argparse.ArgumentParser Argument parser to be configured with create-catalog options.

Returns

None

Notes

This command supports diagnostic modes (--test, --list-test-fonts) in addition to the normal catalog-generation path.

main 

main(args) -> int

CLI entrypoint for create-catalog.

Parameters

args : argparse.Namespace Parsed CLI arguments controlling catalog execution.

Returns

int Process exit code returned by the catalog workflow.

Notes

Handles user-facing output and delegates execution to the core implementation. Unexpected exceptions are converted to exit code 2.

register_cli 

register_cli(parser) -> None

Register create-catalog CLI arguments.

Parameters

parser : argparse.ArgumentParser Argument parser to be configured for the create-catalog command.

Returns

None

Notes

Used by the top-level Fontshow dispatcher.

run_create_catalog 

run_create_catalog(args) -> int

Execute the create-catalog workflow.

Parameters

args : argparse.Namespace Parsed CLI arguments controlling catalog generation.

Returns

int Process exit code: - 0 on success - non-zero on failure

Raises

Exception Unexpected exceptions from downstream helpers are allowed to propagate to main, which converts them into exit code 2.

Notes

Workflow: - Configure TEST_FONTS. - Handle --list-test-fonts early exit. - Prepare output filename. - Resolve inventory source. - Run diagnostics (inventory mode only). - Filter and prepare fonts. - Generate and write LaTeX output.

Behavior is identical to the pre-refactor implementation. I/O failures during final output writing are caught and converted to exit code 1.