Appearance

Migration Guide: extract_ttc → fontisan ​

Overview ​

fontisan now fully supersedes extract_ttc with superior functionality and a better user experience. All extract_ttc features are available in fontisan, plus many more.

Quick Command Translation ​

extract_ttc Commandfontisan EquivalentNotes
extract_ttc ls file.ttcfontisan ls file.ttc✅ Identical output, better formatting
extract_ttc info file.ttcfontisan info file.ttc✅ Plus table sharing statistics
extract_ttc extract file.ttcfontisan unpack file.ttc --output-dir .✅ More powerful with format conversion

Feature Comparison ​

Featureextract_ttcfontisanAdvantage
List fonts in TTC✓✓Equal
Show TTC metadata✓✓Equal
Extract TTC fonts✓✓Equal
Table sharing stats✗✓🎯 fontisan
Auto-detection✗✓🎯 fontisan
Works on TTF/OTF✗✓🎯 fontisan
Format conversion✗✓🎯 fontisan
Output formatsText onlyText, YAML, JSON🎯 fontisan
Font analysis✗✓ (17 commands)🎯 fontisan
Variable fonts✗✓🎯 fontisan
Font subsetting✗✓🎯 fontisan
Font validation✗✓🎯 fontisan
Create collections✗✓🎯 fontisan

Migration Examples ​

Listing Fonts ​

extract_ttc:

bash
extract_ttc ls fonts.ttc

fontisan:

bash
fontisan ls fonts.ttc

Output is cleaner and shows more info:

Collection: fonts.ttc
Fonts: 2

0. Helvetica Regular
   PostScript: Helvetica-Regular
   Format: TrueType
   Glyphs: 268, Tables: 14

1. Helvetica Bold
   PostScript: Helvetica-Bold
   Format: TrueType
   Glyphs: 268, Tables: 14

Collection Information ​

extract_ttc:

bash
extract_ttc info fonts.ttc

fontisan:

bash
fontisan info fonts.ttc

fontisan shows MORE information:

=== Collection Information ===
File: fonts.ttc
Format: TTC
Size: 2.55 KB

=== Header ===
Tag: ttcf
Version: 1.0
Number of fonts: 2

=== Font Offsets ===
  0. Offset:       20
  1. Offset:      272

=== Table Sharing ===      ← NEW!
Shared tables: 17          ← NEW!
Unique tables: 13          ← NEW!
Sharing: 56.67%           ← NEW!
Space saved: 2.02 KB      ← NEW!

Extracting Fonts ​

extract_ttc:

bash
extract_ttc extract fonts.ttc -o output/

fontisan:

bash
fontisan unpack fonts.ttc --output-dir output/

fontisan can also convert during extraction:

bash
# Extract as WOFF2 for web use
fontisan unpack fonts.ttc --output-dir web/ --format woff2

# Extract specific font only
fontisan unpack fonts.ttc --output-dir . --font-index 0

Why Switch to fontisan? ​

1. Universal Commands ​

fontisan commands work on all font formats:

bash
# Works on collections
fontisan ls fonts.ttc
fontisan info fonts.ttc

# Also works on individual fonts
fontisan ls font.ttf
fontisan info font.otf

2. Comprehensive Font Analysis ​

Beyond extract_ttc, fontisan provides:

bash
# Analyze font features
fontisan features font.ttf --script latn

# Check variable font axes
fontisan variable VariableFont.ttf

# Validate font integrity
fontisan validate font.ttf

# Subset to specific characters
fontisan subset font.ttf --text "Hello" --output hello.ttf

# Convert formats
fontisan convert font.ttf --to woff2 --output font.woff2

# Create collections
fontisan pack Regular.ttf Bold.ttf --output Family.ttc

3. Modern Output Formats ​

bash
# Human-readable text (default)
fontisan info fonts.ttc

# Machine-readable YAML
fontisan info fonts.ttc --format yaml

# Machine-readable JSON
fontisan info fonts.ttc --format json

4. Better Error Messages ​

fontisan provides clear, actionable error messages:

Error: Font index 5 out of range (collection has 2 fonts)

vs extract_ttc generic Ruby errors.

Installation ​

Remove extract_ttc (optional) ​

bash
gem uninstall extract_ttc

Install fontisan ​

bash
gem install fontisan

Or add to Gemfile:

ruby
gem 'fontisan'

API Usage ​

extract_ttc API ​

ruby
require 'extract_ttc'

# List fonts
output_files = ExtractTtc.extract("fonts.ttc")

fontisan API (More Powerful) ​

ruby
require 'fontisan'

# List fonts in collection
collection = Fontisan::FontLoader.load_collection("fonts.ttc")
File.open("fonts.ttc", "rb") do |io|
  list = collection.list_fonts(io)
  list.fonts.each { |f| puts "#{f.index}: #{f.family_name}" }
end

# Get collection metadata
File.open("fonts.ttc", "rb") do |io|
  info = collection.collection_info(io, "fonts.ttc")
  puts "Fonts: #{info.num_fonts}"
  puts "Sharing: #{info.table_sharing.sharing_percentage}%"
end

# Extract fonts with more control
File.open("fonts.ttc", "rb") do |io|
  fonts = collection.extract_fonts(io)
  fonts.each_with_index do |font, i|
    font.to_file("output/font_#{i}.ttf")
  end
end

Backward Compatibility ​

fontisan maintains 100% backward compatibility:

  • All existing fontisan commands continue to work
  • No breaking changes to existing functionality
  • New commands add features without removing anything

#=========================================================================

= ExtractTTC to Fontisan Migration Guide

This guide helps users migrate from https://github.com/fontist/extract_ttc[ExtractTTC] to Fontisan.

Fontisan provides complete compatibility with all ExtractTTC functionality while adding comprehensive font analysis, subsetting, validation, and format conversion capabilities.

== Command Mapping Reference

[cols="2,2,3"] |=== |ExtractTTC Command |Fontisan Equivalent |Description

|extract_ttc --list FONT.ttc |fontisan ls FONT.ttc |List fonts in collection with index, family, and style

|extract_ttc --info FONT.ttc |fontisan info FONT.ttc |Show detailed font information for collection

|extract_ttc --unpack FONT.ttc OUTPUT_DIR |fontisan unpack FONT.ttc OUTPUT_DIR |Extract all fonts from collection to directory

|extract_ttc --font-index INDEX FONT.ttc OUTPUT.ttf |fontisan unpack FONT.ttc --font-index INDEX OUTPUT.ttf |Extract specific font by index

|extract_ttc --validate FONT.ttc |fontisan validate FONT.ttc |Validate font/collection structure and checksums |===

== Enhanced Collection Management

Fontisan provides additional collection features beyond ExtractTTC:

=== List Collection Contents

[source,shell] ​

List all fonts in a TTC with detailed info ​

$ fontisan ls spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc

Font 0: Noto Serif CJK JP Family: Noto Serif CJK JP Subfamily: Regular PostScript: NotoSerifCJKJP-Regular

Font 1: Noto Serif CJK KR Family: Noto Serif CJK KR Subfamily: Regular PostScript: NotoSerifCJKKR-Regular

Font 2: Noto Serif CJK SC Family: Noto Serif CJK SC Subfamily: Regular PostScript: NotoSerifCJKSC-Regular

Font 3: Noto Serif CJK TC Family: Noto Serif CJK TC Subfamily: Regular PostScript: NotoSerifCJKTC-Regular ​

=== Extract with Validation

[source,shell] ​

Extract and validate simultaneously ​

$ fontisan unpack spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc extracted_fonts/ --validate

Extracting font 0: Noto Serif CJK JP → extracted_fonts/NotoSerifCJKJP-Regular.ttf Extracting font 1: Noto Serif CJK KR → extracted_fonts/NotoSerifCJKKR-Regular.ttf Extracting font 2: Noto Serif CJK SC → extracted_fonts/NotoSerifCJKSC-Regular.ttf Extracting font 3: Noto Serif CJK TC → extracted_fonts/NotoSerifCJKTC-Regular.ttf

Validation: All fonts extracted successfully ​

=== Get Collection Information

[source,shell] ​

Detailed collection analysis ​

$ fontisan info spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc --format yaml

collection_type: ttc font_count: 4 fonts:

  • index: 0 family_name: Noto Serif CJK JP subfamily_name: Regular postscript_name: NotoSerifCJKJP-Regular font_format: opentype
  • index: 1 family_name: Noto Serif CJK KR subfamily_name: Regular postscript_name: NotoSerifCJKKR-Regular font_format: opentype
  • index: 2 family_name: Noto Serif CJK SC subfamily_name: Regular postscript_name: NotoSerifCJKSC-Regular font_format: opentype
  • index: 3 family_name: Noto Serif CJK TC subfamily_name: Regular postscript_name: NotoSerifCJKTC-Regular font_format: opentype

== Advanced Features Beyond ExtractTTC

Fontisan provides capabilities that ExtractTTC never had:

=== Collection Creation

Create new TTC/OTC files from individual fonts with automatic table sharing optimization:

[source,shell] ​

Pack fonts into TTC with table sharing optimization ​

$ fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc --analyze

Collection Analysis: Total fonts: 3 Shared tables: 12 Potential space savings: 45.2 KB Table sharing: 68.5%

Collection created successfully: Output: family.ttc Format: TTC Fonts: 3 Size: 245.8 KB Space saved: 45.2 KB Sharing: 68.5% ​

=== Format Conversion and Subsetting

Convert between font formats and create optimized subsets:

[source,shell] ​

Convert TTF to WOFF2 for web usage ​

$ fontisan convert font.ttf --to woff2 --output font.woff2

Create PDF-optimized subset ​

$ fontisan subset font.ttf --text "Hello World" --output subset.ttf --profile pdf ​

=== Font Analysis and Inspection

Comprehensive font analysis capabilities:

[source,shell] ​

Extract OpenType tables with details ​

$ fontisan tables font.ttf --format yaml

Display variable font information ​

$ fontisan variable font.ttf

Show supported scripts and features ​

$ fontisan scripts font.ttf $ fontisan features font.ttf --script latn

Dump raw table data for analysis ​

$ fontisan dump-table font.ttf name > name_table.bin ​

=== Font Validation

Multiple validation levels with detailed reporting:

[source,shell] ​

Standard validation (allows warnings) ​

$ fontisan validate font.ttf

Strict validation (no warnings allowed) ​

$ fontisan validate font.ttf --level strict

Detailed validation report ​

$ fontisan validate font.ttf --format yaml ​

== Migration Examples

=== Basic Collection Operations

[source,shell]

ExtractTTC style operations ​

extract_ttc --list collection.ttc fontisan ls collection.ttc

extract_ttc --info collection.ttc fontisan info collection.ttc

extract_ttc --unpack collection.ttc output_dir/ fontisan unpack collection.ttc output_dir/

extract_ttc --font-index 0 collection.ttc font0.ttf fontisan unpack collection.ttc --font-index 0 font0.ttf ​

=== Enhanced Operations (Fontisan Only)

[source,shell]

Create collections (not possible with ExtractTTC) ​

fontisan pack font1.ttf font2.ttf --output new_collection.ttc

Convert formats ​

fontisan convert font.ttf --to woff2 --output font.woff2

Create subsets ​

fontisan subset font.ttf --unicode "U+0041-U+005A" --output latin.ttf

Validate fonts ​

fontisan validate font.ttf --level strict

Analyze fonts ​

fontisan scripts font.ttf fontisan features font.ttf --script latn fontisan variable font.ttf ​

== Configuration and Options

Fontisan provides extensive configuration options:

=== Global Options All commands support these options:

  • --format FORMAT: Output format (text, json, yaml)
  • --font-index INDEX: Font index for TTC files (default: 0)
  • --verbose: Enable verbose output
  • --quiet: Suppress non-error output

=== Collection-Specific Options

  • --analyze: Show space analysis for pack operations
  • --optimize: Enable table sharing optimization (default: true)
  • --format {ttc|otc}: Collection format for pack operations

=== Conversion Options

  • --to FORMAT: Target format for conversion
  • --quality LEVEL: Compression quality (0-11)
  • --profile PROFILE: Subsetting profile (pdf, web, minimal)

== Error Handling

Fontisan provides improved error handling compared to ExtractTTC:

[source,shell] ​

Clear error messages ​

$ fontisan convert font.ttf --to unsupported Error: Unsupported conversion from ttf to unsupported Available targets: ttf, otf, woff2, svg

Helpful validation errors ​

$ fontisan validate corrupted.ttf Validation failed: Invalid checksum in head table ​

== Performance

Fontisan is optimized for performance:

  • Collection Operations: Sub-second for typical collections
  • Format Conversion: <1 second for most conversions
  • Font Analysis: <100ms for table inspection
  • Memory Efficient: Streaming processing for large fonts

== Backward Compatibility

Fontisan maintains full backward compatibility:

  • All ExtractTTC commands work identically
  • Same exit codes and error handling
  • Compatible with existing scripts and workflows
  • Enhanced with additional features

== Getting Help

[source,shell] ​

General help ​

$ fontisan --help

Command-specific help ​

$ fontisan pack --help $ fontisan convert --help $ fontisan subset --help

Version information ​

$ fontisan version ​

Fontisan is a [Ribose](https://open.ribose.com/) project

Copyright © 2026 Ribose Group Inc. All rights reserved.