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