fontisan 0.4.49-aarch64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (792) hide show
  1. checksums.yaml +7 -0
  2. data/.rspec +3 -0
  3. data/.rubocop.yml +141 -0
  4. data/.rubocop_todo.yml +433 -0
  5. data/BENCHMARKS.md +56 -0
  6. data/BUG-stitcher-drops-isolated-cps.md +58 -0
  7. data/BUG-stitcher-drops-plane1-codepoints.md +310 -0
  8. data/BUG-stitcher-gid-cap-65535.md +110 -0
  9. data/CHANGELOG.md +293 -0
  10. data/Gemfile +40 -0
  11. data/LICENSE +28 -0
  12. data/README.adoc +2811 -0
  13. data/Rakefile +156 -0
  14. data/TODO.bug-fixes/01-cff-expert-charsets.md +27 -0
  15. data/TODO.bug-fixes/02-cff2-subroutine-stubs.md +32 -0
  16. data/TODO.bug-fixes/03-variation-subsetter-placeholders.md +42 -0
  17. data/TODO.bug-fixes/04-ufo-image-compile-roundtrip.md +28 -0
  18. data/TODO.bug-fixes/05-stale-cff-comment.md +18 -0
  19. data/TODO.bug-fixes/06-instance-woff2-output.md +24 -0
  20. data/TODO.bug-fixes/07-encapsulation-violations.md +38 -0
  21. data/TODO.bug-fixes/08-respond-to-violations.md +25 -0
  22. data/TODO.bug-fixes/09-type1-cff-seac-expansion.md +22 -0
  23. data/TODO.bug-fixes/10-ttf-type1-composite-glyphs.md +23 -0
  24. data/TODO.bug-fixes/11-remaining-respond-to.md +25 -0
  25. data/TODO.bug-fixes/12-type1-generators-duck-typing.md +80 -0
  26. data/TODO.bug-fixes/13-hint-extractor-duck-typing.md +30 -0
  27. data/TODO.bug-fixes/14-font-interface-type-checks.md +82 -0
  28. data/TODO.bug-fixes/15-glyph-type-checks-and-simple-glyph-points-bug.md +49 -0
  29. data/TODO.bug-fixes/16-variation-table-checks.md +31 -0
  30. data/TODO.bug-fixes/17-ufo-and-stitcher-cleanup.md +32 -0
  31. data/TODO.bug-fixes/18-generic-value-and-io-checks.md +56 -0
  32. data/TODO.bug-fixes/19-serialization-migration.md +52 -0
  33. data/TODO.bug-fixes/20-variation-validator-type-checks.md +29 -0
  34. data/TODO.bug-fixes/21-xml-builder-send.md +24 -0
  35. data/TODO.bug-fixes/22-type1-converter-font-info.md +25 -0
  36. data/TODO.bug-fixes/23-boundary-type-checks.md +31 -0
  37. data/TODO.bug-fixes/24-validator-dynamic-field-key.md +25 -0
  38. data/TODO.bug-fixes/25-serialization-migration.md +49 -0
  39. data/TODO.bug-fixes/26-variation-preserver-spec-migration.md +25 -0
  40. data/TODO.bug-fixes/27-table-class-registry.md +50 -0
  41. data/TODO.bug-fixes/28-spec-doubles-cleanup.md +40 -0
  42. data/TODO.bug-fixes/29-strategy-registries.md +30 -0
  43. data/TODO.bug-fixes/30-eliminate-send-in-specs.md +36 -0
  44. data/TODO.bug-fixes/README.md +52 -0
  45. data/TODO.improvements/01-cbdt-cblc-gid-stable-propagation.md +73 -0
  46. data/TODO.improvements/02-collection-outline-priority.md +48 -0
  47. data/TODO.improvements/03-fontisan-audit-command.md +219 -0
  48. data/TODO.improvements/04-ufo-composite-glyph-encoding.md +46 -0
  49. data/TODO.improvements/05-otf-compiler-real-cff.md +63 -0
  50. data/TODO.improvements/06-cff2-blend-vsindex-operators.md +51 -0
  51. data/TODO.improvements/07-cpal-v1-header-fields.md +71 -0
  52. data/TODO.improvements/08-cff-standard-string-table.md +52 -0
  53. data/TODO.improvements/09-type1-seac-expansion.md +57 -0
  54. data/TODO.improvements/10-ufo-image-set-feature-writers.md +71 -0
  55. data/TODO.improvements/11-kern-groups-plist.md +49 -0
  56. data/TODO.improvements/12-cbdt-fixture-bindata-conversion.md +68 -0
  57. data/TODO.improvements/13-split-octokit-fetcher.md +45 -0
  58. data/TODO.improvements/14-rubocop-baseline-chip.md +62 -0
  59. data/TODO.improvements/15-cff-cff2-subsetter-strategy.md +78 -0
  60. data/TODO.improvements/README.md +58 -0
  61. data/benchmark/baseline.json +5 -0
  62. data/benchmark/ci_gate.rb +217 -0
  63. data/benchmark/compile_benchmark.rb +78 -0
  64. data/benchmark/corpus/harness.rb +175 -0
  65. data/benchmark/corpus/ops.rb +150 -0
  66. data/benchmark/corpus/run.rb +182 -0
  67. data/benchmark/corpus/scan_child.rb +8 -0
  68. data/benchmark/corpus/tiers.rb +176 -0
  69. data/benchmark/tier_baseline.json +12 -0
  70. data/benchmark/variation_quick_bench.rb +47 -0
  71. data/build_mingw32_stub.rb +15 -0
  72. data/docs/.gitignore +17 -0
  73. data/docs/.vitepress/config.ts +373 -0
  74. data/docs/.vitepress/theme/components/ApiMethod.vue +127 -0
  75. data/docs/.vitepress/theme/components/Badge.vue +51 -0
  76. data/docs/.vitepress/theme/components/FeatureComparison.vue +87 -0
  77. data/docs/.vitepress/theme/components/HeroCodeBlock.vue +98 -0
  78. data/docs/.vitepress/theme/components/WithinHero.vue +30 -0
  79. data/docs/.vitepress/theme/index.ts +22 -0
  80. data/docs/.vitepress/theme/style.css +628 -0
  81. data/docs/AFDKO_MIGRATION.adoc +175 -0
  82. data/docs/APPLE_LEGACY_FONTS.adoc +173 -0
  83. data/docs/CFF2_SUPPORT.adoc +184 -0
  84. data/docs/COLLECTION_VALIDATION.adoc +204 -0
  85. data/docs/COLOR_FONTS.adoc +127 -0
  86. data/docs/CONVERSION_GUIDE.adoc +656 -0
  87. data/docs/EXTRACT_TTC_MIGRATION.md +549 -0
  88. data/docs/FEATURE_PARITY.adoc +263 -0
  89. data/docs/FONT_HINTING.adoc +570 -0
  90. data/docs/STITCHER_GUIDE.adoc +436 -0
  91. data/docs/SVG_TO_GLYF.adoc +118 -0
  92. data/docs/TTX.adoc +176 -0
  93. data/docs/TYPE1_FONTS.adoc +445 -0
  94. data/docs/UFO_COMPILATION.adoc +397 -0
  95. data/docs/VALIDATION.adoc +254 -0
  96. data/docs/VARIABLE_FONT_OPERATIONS.adoc +599 -0
  97. data/docs/WOFF_WOFF2_FORMATS.adoc +220 -0
  98. data/docs/api/conversion-options.md +164 -0
  99. data/docs/api/converters/curve-converter.md +34 -0
  100. data/docs/api/converters/hint-converter.md +34 -0
  101. data/docs/api/converters/outline-converter.md +27 -0
  102. data/docs/api/font-loader.md +117 -0
  103. data/docs/api/font-writer.md +103 -0
  104. data/docs/api/index.md +79 -0
  105. data/docs/api/layer.md +89 -0
  106. data/docs/api/models/glyph-accessor.md +43 -0
  107. data/docs/api/models/glyph.md +40 -0
  108. data/docs/api/models/table-analyzer.md +35 -0
  109. data/docs/api/sfnt-font.md +53 -0
  110. data/docs/api/type1-font.md +43 -0
  111. data/docs/api/validators/font-validator.md +31 -0
  112. data/docs/api/validators/helper.md +36 -0
  113. data/docs/api/validators/profile.md +39 -0
  114. data/docs/cli/convert.md +148 -0
  115. data/docs/cli/dump-table.md +110 -0
  116. data/docs/cli/export.md +176 -0
  117. data/docs/cli/features.md +124 -0
  118. data/docs/cli/glyphs.md +90 -0
  119. data/docs/cli/index.md +232 -0
  120. data/docs/cli/info.md +254 -0
  121. data/docs/cli/instance.md +122 -0
  122. data/docs/cli/ls.md +95 -0
  123. data/docs/cli/optical-size.md +94 -0
  124. data/docs/cli/pack.md +125 -0
  125. data/docs/cli/scripts.md +105 -0
  126. data/docs/cli/subset.md +58 -0
  127. data/docs/cli/tables.md +84 -0
  128. data/docs/cli/unicode.md +101 -0
  129. data/docs/cli/validate-collection.md +95 -0
  130. data/docs/cli/validate.md +56 -0
  131. data/docs/cli/variable.md +126 -0
  132. data/docs/cli/version.md +46 -0
  133. data/docs/guide/cli/convert.md +108 -0
  134. data/docs/guide/cli/export.md +138 -0
  135. data/docs/guide/cli/index.md +99 -0
  136. data/docs/guide/cli/info.md +144 -0
  137. data/docs/guide/cli/pack.md +155 -0
  138. data/docs/guide/cli/subset.md +149 -0
  139. data/docs/guide/cli/validate.md +139 -0
  140. data/docs/guide/color-fonts/bitmaps.md +194 -0
  141. data/docs/guide/color-fonts/colr-cpal.md +175 -0
  142. data/docs/guide/color-fonts/index.md +140 -0
  143. data/docs/guide/color-fonts/svg.md +154 -0
  144. data/docs/guide/color.md +51 -0
  145. data/docs/guide/comparisons/font-validator.md +222 -0
  146. data/docs/guide/comparisons/fonttools.md +200 -0
  147. data/docs/guide/comparisons/index.md +83 -0
  148. data/docs/guide/comparisons/lcdf-typetools.md +205 -0
  149. data/docs/guide/contributing.md +279 -0
  150. data/docs/guide/conversion/collections.md +251 -0
  151. data/docs/guide/conversion/curves.md +246 -0
  152. data/docs/guide/conversion/index.md +157 -0
  153. data/docs/guide/conversion/options.md +280 -0
  154. data/docs/guide/conversion/ttf-otf.md +184 -0
  155. data/docs/guide/conversion/type1.md +208 -0
  156. data/docs/guide/conversion/web.md +299 -0
  157. data/docs/guide/conversion.md +40 -0
  158. data/docs/guide/engines.md +117 -0
  159. data/docs/guide/formats/collections.md +147 -0
  160. data/docs/guide/formats/dfont.md +99 -0
  161. data/docs/guide/formats/index.md +65 -0
  162. data/docs/guide/formats/otf.md +103 -0
  163. data/docs/guide/formats/svg.md +97 -0
  164. data/docs/guide/formats/ttf.md +105 -0
  165. data/docs/guide/formats/type1.md +118 -0
  166. data/docs/guide/formats/woff.md +139 -0
  167. data/docs/guide/hinting/autohint.md +141 -0
  168. data/docs/guide/hinting/conversion.md +161 -0
  169. data/docs/guide/hinting/index.md +86 -0
  170. data/docs/guide/hinting/postscript.md +149 -0
  171. data/docs/guide/hinting/truetype.md +135 -0
  172. data/docs/guide/hinting.md +44 -0
  173. data/docs/guide/index.md +152 -0
  174. data/docs/guide/installation.md +116 -0
  175. data/docs/guide/migrations/extract-ttc.md +549 -0
  176. data/docs/guide/migrations/font-validator.md +260 -0
  177. data/docs/guide/migrations/fonttools.md +208 -0
  178. data/docs/guide/migrations/index.md +64 -0
  179. data/docs/guide/migrations/otfinfo.md +197 -0
  180. data/docs/guide/quick-start.md +204 -0
  181. data/docs/guide/type1.md +58 -0
  182. data/docs/guide/universal-outline.md +151 -0
  183. data/docs/guide/validation/custom.md +195 -0
  184. data/docs/guide/validation/helpers.md +188 -0
  185. data/docs/guide/validation/index.md +132 -0
  186. data/docs/guide/validation/profiles.md +156 -0
  187. data/docs/guide/validation.md +47 -0
  188. data/docs/guide/variable-fonts/advanced.md +231 -0
  189. data/docs/guide/variable-fonts/axes.md +209 -0
  190. data/docs/guide/variable-fonts/conversion.md +197 -0
  191. data/docs/guide/variable-fonts/index.md +84 -0
  192. data/docs/guide/variable-fonts/instances.md +187 -0
  193. data/docs/guide/variable-fonts/named-instances.md +194 -0
  194. data/docs/guide/variable-fonts/static.md +168 -0
  195. data/docs/guide/variable.md +58 -0
  196. data/docs/guide/woff.md +61 -0
  197. data/docs/index.md +136 -0
  198. data/docs/lychee.toml +41 -0
  199. data/docs/package-lock.json +2560 -0
  200. data/docs/package.json +15 -0
  201. data/docs/public/apple-touch-icon.png +0 -0
  202. data/docs/public/favicon-96x96.png +0 -0
  203. data/docs/public/favicon.ico +0 -0
  204. data/docs/public/favicon.svg +1 -0
  205. data/docs/public/logo-full.svg +1 -0
  206. data/docs/public/logo.svg +1 -0
  207. data/docs/public/robots.txt +4 -0
  208. data/docs/public/site.webmanifest +21 -0
  209. data/docs/public/web-app-manifest-192x192.png +0 -0
  210. data/docs/public/web-app-manifest-512x512.png +0 -0
  211. data/docs/reference-facade.md +130 -0
  212. data/docs/scripts/post-build.mjs +81 -0
  213. data/exe/fontisan +7 -0
  214. data/lib/fontisan/audit/check.rb +47 -0
  215. data/lib/fontisan/audit/check_registry.rb +77 -0
  216. data/lib/fontisan/audit/checks/cff_table_check.rb +87 -0
  217. data/lib/fontisan/audit/checks/cmap_check.rb +256 -0
  218. data/lib/fontisan/audit/checks/collection_integrity_check.rb +102 -0
  219. data/lib/fontisan/audit/checks/format_round_trip_check.rb +150 -0
  220. data/lib/fontisan/audit/checks/glyf_table_check.rb +115 -0
  221. data/lib/fontisan/audit/checks/glyph_name_check.rb +107 -0
  222. data/lib/fontisan/audit/checks/head_check.rb +96 -0
  223. data/lib/fontisan/audit/checks/hhea_check.rb +68 -0
  224. data/lib/fontisan/audit/checks/hinting_check.rb +163 -0
  225. data/lib/fontisan/audit/checks/kern_check.rb +47 -0
  226. data/lib/fontisan/audit/checks/layout_table_check.rb +70 -0
  227. data/lib/fontisan/audit/checks/maxp_check.rb +85 -0
  228. data/lib/fontisan/audit/checks/name_table_check.rb +78 -0
  229. data/lib/fontisan/audit/checks/naming_consistency_check.rb +102 -0
  230. data/lib/fontisan/audit/checks/opentype_conformance_check.rb +108 -0
  231. data/lib/fontisan/audit/checks/os2_check.rb +117 -0
  232. data/lib/fontisan/audit/checks/ots_compatibility_check.rb +191 -0
  233. data/lib/fontisan/audit/checks/post_check.rb +75 -0
  234. data/lib/fontisan/audit/checks/table_directory_check.rb +157 -0
  235. data/lib/fontisan/audit/checks/variable_font_check.rb +151 -0
  236. data/lib/fontisan/audit/checks/woff2_validation_check.rb +140 -0
  237. data/lib/fontisan/audit/checks.rb +42 -0
  238. data/lib/fontisan/audit.rb +20 -0
  239. data/lib/fontisan/base_collection.rb +312 -0
  240. data/lib/fontisan/binary/base_record.rb +82 -0
  241. data/lib/fontisan/binary/structures.rb +82 -0
  242. data/lib/fontisan/binary.rb +11 -0
  243. data/lib/fontisan/byte_ops.rb +314 -0
  244. data/lib/fontisan/cli.rb +1111 -0
  245. data/lib/fontisan/collection/builder.rb +336 -0
  246. data/lib/fontisan/collection/dfont_builder.rb +305 -0
  247. data/lib/fontisan/collection/offset_calculator.rb +229 -0
  248. data/lib/fontisan/collection/reader/stats.rb +23 -0
  249. data/lib/fontisan/collection/reader.rb +90 -0
  250. data/lib/fontisan/collection/shared_logic.rb +52 -0
  251. data/lib/fontisan/collection/table_analyzer.rb +289 -0
  252. data/lib/fontisan/collection/table_deduplicator.rb +317 -0
  253. data/lib/fontisan/collection/writer.rb +289 -0
  254. data/lib/fontisan/collection.rb +16 -0
  255. data/lib/fontisan/commands/audit_command.rb +288 -0
  256. data/lib/fontisan/commands/base_command.rb +88 -0
  257. data/lib/fontisan/commands/convert_command.rb +506 -0
  258. data/lib/fontisan/commands/dump_table_command.rb +68 -0
  259. data/lib/fontisan/commands/export_command.rb +157 -0
  260. data/lib/fontisan/commands/features_command.rb +90 -0
  261. data/lib/fontisan/commands/glyphs_command.rb +50 -0
  262. data/lib/fontisan/commands/info_command.rb +447 -0
  263. data/lib/fontisan/commands/instance_command.rb +357 -0
  264. data/lib/fontisan/commands/ls_command.rb +107 -0
  265. data/lib/fontisan/commands/multi_format_output.rb +64 -0
  266. data/lib/fontisan/commands/optical_size_command.rb +38 -0
  267. data/lib/fontisan/commands/pack_command.rb +344 -0
  268. data/lib/fontisan/commands/scripts_command.rb +56 -0
  269. data/lib/fontisan/commands/subset_command.rb +285 -0
  270. data/lib/fontisan/commands/tables_command.rb +52 -0
  271. data/lib/fontisan/commands/unicode_command.rb +73 -0
  272. data/lib/fontisan/commands/unpack_command.rb +387 -0
  273. data/lib/fontisan/commands/validate_collection_command.rb +127 -0
  274. data/lib/fontisan/commands/validate_command.rb +305 -0
  275. data/lib/fontisan/commands/variable_command.rb +87 -0
  276. data/lib/fontisan/commands.rb +30 -0
  277. data/lib/fontisan/config/collection_settings.yml +56 -0
  278. data/lib/fontisan/config/conversion_matrix.yml +626 -0
  279. data/lib/fontisan/config/export_settings.yml +66 -0
  280. data/lib/fontisan/config/features.yml +143 -0
  281. data/lib/fontisan/config/scripts.yml +42 -0
  282. data/lib/fontisan/config/subset_profiles.yml +106 -0
  283. data/lib/fontisan/config/svg_settings.yml +60 -0
  284. data/lib/fontisan/config/variable_settings.yml +99 -0
  285. data/lib/fontisan/config/woff2_settings.yml +77 -0
  286. data/lib/fontisan/constants.rb +219 -0
  287. data/lib/fontisan/conversion_options.rb +389 -0
  288. data/lib/fontisan/converters/cff_table_builder.rb +195 -0
  289. data/lib/fontisan/converters/collection_converter.rb +520 -0
  290. data/lib/fontisan/converters/conversion_strategy.rb +211 -0
  291. data/lib/fontisan/converters/format_converter.rb +536 -0
  292. data/lib/fontisan/converters/glyf_table_builder.rb +61 -0
  293. data/lib/fontisan/converters/outline_converter.rb +720 -0
  294. data/lib/fontisan/converters/outline_extraction.rb +88 -0
  295. data/lib/fontisan/converters/outline_optimizer.rb +84 -0
  296. data/lib/fontisan/converters/svg_generator.rb +236 -0
  297. data/lib/fontisan/converters/table_copier.rb +107 -0
  298. data/lib/fontisan/converters/type1_converter.rb +1201 -0
  299. data/lib/fontisan/converters/woff2_encoder.rb +520 -0
  300. data/lib/fontisan/converters/woff_writer.rb +358 -0
  301. data/lib/fontisan/converters.rb +21 -0
  302. data/lib/fontisan/dfont_collection.rb +288 -0
  303. data/lib/fontisan/engine.rb +393 -0
  304. data/lib/fontisan/error.rb +281 -0
  305. data/lib/fontisan/export/exporter.rb +255 -0
  306. data/lib/fontisan/export/table_serializer.rb +140 -0
  307. data/lib/fontisan/export/transformers/font_to_ttx.rb +163 -0
  308. data/lib/fontisan/export/transformers/head_transformer.rb +94 -0
  309. data/lib/fontisan/export/transformers/hhea_transformer.rb +57 -0
  310. data/lib/fontisan/export/transformers/maxp_transformer.rb +61 -0
  311. data/lib/fontisan/export/transformers/name_transformer.rb +61 -0
  312. data/lib/fontisan/export/transformers/os2_transformer.rb +119 -0
  313. data/lib/fontisan/export/transformers/post_transformer.rb +49 -0
  314. data/lib/fontisan/export/transformers.rb +17 -0
  315. data/lib/fontisan/export/ttx_generator.rb +526 -0
  316. data/lib/fontisan/export/ttx_parser.rb +300 -0
  317. data/lib/fontisan/export.rb +13 -0
  318. data/lib/fontisan/ffi/client.rb +123 -0
  319. data/lib/fontisan/ffi/libfontisan_cdylib.so +0 -0
  320. data/lib/fontisan/ffi.rb +387 -0
  321. data/lib/fontisan/ffi_platform.rb +24 -0
  322. data/lib/fontisan/font_loader.rb +315 -0
  323. data/lib/fontisan/font_writer.rb +309 -0
  324. data/lib/fontisan/formatters/text_formatter.rb +517 -0
  325. data/lib/fontisan/formatters.rb +9 -0
  326. data/lib/fontisan/glyph_accessor.rb +525 -0
  327. data/lib/fontisan/hints/hint_converter.rb +309 -0
  328. data/lib/fontisan/hints/hint_validator.rb +287 -0
  329. data/lib/fontisan/hints/postscript_hint_applier.rb +255 -0
  330. data/lib/fontisan/hints/postscript_hint_extractor.rb +347 -0
  331. data/lib/fontisan/hints/truetype_hint_applier.rb +117 -0
  332. data/lib/fontisan/hints/truetype_hint_extractor.rb +283 -0
  333. data/lib/fontisan/hints/truetype_instruction_analyzer.rb +268 -0
  334. data/lib/fontisan/hints/truetype_instruction_generator.rb +266 -0
  335. data/lib/fontisan/hints.rb +19 -0
  336. data/lib/fontisan/loading_modes.rb +113 -0
  337. data/lib/fontisan/metrics_calculator.rb +275 -0
  338. data/lib/fontisan/models/all_scripts_features_info.rb +20 -0
  339. data/lib/fontisan/models/audit_report.rb +196 -0
  340. data/lib/fontisan/models/bitmap_glyph.rb +123 -0
  341. data/lib/fontisan/models/bitmap_strike.rb +94 -0
  342. data/lib/fontisan/models/collection_brief_info.rb +36 -0
  343. data/lib/fontisan/models/collection_font_summary.rb +52 -0
  344. data/lib/fontisan/models/collection_info.rb +79 -0
  345. data/lib/fontisan/models/collection_list_info.rb +36 -0
  346. data/lib/fontisan/models/collection_validation_report.rb +102 -0
  347. data/lib/fontisan/models/color_glyph.rb +56 -0
  348. data/lib/fontisan/models/color_layer.rb +53 -0
  349. data/lib/fontisan/models/color_palette.rb +60 -0
  350. data/lib/fontisan/models/features_info.rb +42 -0
  351. data/lib/fontisan/models/font_export.rb +158 -0
  352. data/lib/fontisan/models/font_info.rb +98 -0
  353. data/lib/fontisan/models/font_report.rb +23 -0
  354. data/lib/fontisan/models/font_summary.rb +48 -0
  355. data/lib/fontisan/models/glyph_info.rb +26 -0
  356. data/lib/fontisan/models/glyph_outline.rb +343 -0
  357. data/lib/fontisan/models/hint.rb +404 -0
  358. data/lib/fontisan/models/optical_size_info.rb +33 -0
  359. data/lib/fontisan/models/outline.rb +667 -0
  360. data/lib/fontisan/models/scripts_info.rb +39 -0
  361. data/lib/fontisan/models/svg_glyph.rb +89 -0
  362. data/lib/fontisan/models/table_info.rb +55 -0
  363. data/lib/fontisan/models/table_sharing_info.rb +40 -0
  364. data/lib/fontisan/models/ttx/glyph_order.rb +31 -0
  365. data/lib/fontisan/models/ttx/tables/binary_table.rb +67 -0
  366. data/lib/fontisan/models/ttx/tables/head_table.rb +74 -0
  367. data/lib/fontisan/models/ttx/tables/hhea_table.rb +74 -0
  368. data/lib/fontisan/models/ttx/tables/maxp_table.rb +55 -0
  369. data/lib/fontisan/models/ttx/tables/name_table.rb +45 -0
  370. data/lib/fontisan/models/ttx/tables/os2_table.rb +157 -0
  371. data/lib/fontisan/models/ttx/tables/post_table.rb +50 -0
  372. data/lib/fontisan/models/ttx/tables.rb +21 -0
  373. data/lib/fontisan/models/ttx/ttfont.rb +41 -0
  374. data/lib/fontisan/models/ttx.rb +14 -0
  375. data/lib/fontisan/models/unicode_mappings.rb +42 -0
  376. data/lib/fontisan/models/validation_report.rb +435 -0
  377. data/lib/fontisan/models/variable_font_info.rb +82 -0
  378. data/lib/fontisan/models.rb +49 -0
  379. data/lib/fontisan/native/3.2/fontisan_native.so +0 -0
  380. data/lib/fontisan/native/3.3/fontisan_native.so +0 -0
  381. data/lib/fontisan/native/3.4/fontisan_native.so +0 -0
  382. data/lib/fontisan/native/4.0/fontisan_native.so +0 -0
  383. data/lib/fontisan/native.rb +235 -0
  384. data/lib/fontisan/open_type_collection.rb +49 -0
  385. data/lib/fontisan/open_type_font.rb +161 -0
  386. data/lib/fontisan/open_type_font_extensions.rb +54 -0
  387. data/lib/fontisan/optimizers/charstring_rewriter.rb +172 -0
  388. data/lib/fontisan/optimizers/pattern_analyzer.rb +310 -0
  389. data/lib/fontisan/optimizers/stack_tracker.rb +246 -0
  390. data/lib/fontisan/optimizers/subroutine_builder.rb +135 -0
  391. data/lib/fontisan/optimizers/subroutine_generator.rb +207 -0
  392. data/lib/fontisan/optimizers/subroutine_optimizer.rb +114 -0
  393. data/lib/fontisan/optimizers.rb +14 -0
  394. data/lib/fontisan/outline_extractor.rb +417 -0
  395. data/lib/fontisan/output_guard.rb +40 -0
  396. data/lib/fontisan/parsers/dfont_parser.rb +191 -0
  397. data/lib/fontisan/parsers/tag.rb +77 -0
  398. data/lib/fontisan/parsers.rb +10 -0
  399. data/lib/fontisan/pipeline/format_detector.rb +176 -0
  400. data/lib/fontisan/pipeline/output_writer.rb +161 -0
  401. data/lib/fontisan/pipeline/strategies/base_strategy.rb +75 -0
  402. data/lib/fontisan/pipeline/strategies/instance_strategy.rb +89 -0
  403. data/lib/fontisan/pipeline/strategies/named_strategy.rb +114 -0
  404. data/lib/fontisan/pipeline/strategies/preserve_strategy.rb +54 -0
  405. data/lib/fontisan/pipeline/strategies.rb +16 -0
  406. data/lib/fontisan/pipeline/transformation_pipeline.rb +407 -0
  407. data/lib/fontisan/pipeline/variation_resolver.rb +158 -0
  408. data/lib/fontisan/pipeline.rb +14 -0
  409. data/lib/fontisan/reference/table_digests.rb +251 -0
  410. data/lib/fontisan/reference.rb +663 -0
  411. data/lib/fontisan/scan.rb +372 -0
  412. data/lib/fontisan/sfnt_builder.rb +66 -0
  413. data/lib/fontisan/sfnt_directory.rb +41 -0
  414. data/lib/fontisan/sfnt_font.rb +749 -0
  415. data/lib/fontisan/sfnt_source.rb +28 -0
  416. data/lib/fontisan/sfnt_table.rb +260 -0
  417. data/lib/fontisan/stitcher/cbdt_propagator.rb +212 -0
  418. data/lib/fontisan/stitcher/collection_result.rb +19 -0
  419. data/lib/fontisan/stitcher/deduplicator.rb +47 -0
  420. data/lib/fontisan/stitcher/format_metadata.rb +51 -0
  421. data/lib/fontisan/stitcher/glyph_cloner.rb +41 -0
  422. data/lib/fontisan/stitcher/glyph_copier.rb +110 -0
  423. data/lib/fontisan/stitcher/glyph_limit.rb +53 -0
  424. data/lib/fontisan/stitcher/glyph_signature.rb +51 -0
  425. data/lib/fontisan/stitcher/partition_strategy/base.rb +52 -0
  426. data/lib/fontisan/stitcher/partition_strategy/blueprint.rb +24 -0
  427. data/lib/fontisan/stitcher/partition_strategy/by_block.rb +430 -0
  428. data/lib/fontisan/stitcher/partition_strategy/by_plane.rb +161 -0
  429. data/lib/fontisan/stitcher/partition_strategy/by_script.rb +309 -0
  430. data/lib/fontisan/stitcher/partition_strategy/partition.rb +24 -0
  431. data/lib/fontisan/stitcher/partition_strategy.rb +24 -0
  432. data/lib/fontisan/stitcher/selector/codepoints.rb +29 -0
  433. data/lib/fontisan/stitcher/selector/gid.rb +25 -0
  434. data/lib/fontisan/stitcher/selector/range.rb +30 -0
  435. data/lib/fontisan/stitcher/selector.rb +26 -0
  436. data/lib/fontisan/stitcher/source.rb +459 -0
  437. data/lib/fontisan/stitcher/unique_glyph_name.rb +46 -0
  438. data/lib/fontisan/stitcher.rb +185 -0
  439. data/lib/fontisan/stitcher_cli.rb +69 -0
  440. data/lib/fontisan/subset/builder.rb +263 -0
  441. data/lib/fontisan/subset/glyph_mapping.rb +222 -0
  442. data/lib/fontisan/subset/options.rb +142 -0
  443. data/lib/fontisan/subset/profile.rb +152 -0
  444. data/lib/fontisan/subset/shared_state.rb +42 -0
  445. data/lib/fontisan/subset/subset_context.rb +20 -0
  446. data/lib/fontisan/subset/table_strategy/cbdt.rb +30 -0
  447. data/lib/fontisan/subset/table_strategy/cblc.rb +27 -0
  448. data/lib/fontisan/subset/table_strategy/cff.rb +92 -0
  449. data/lib/fontisan/subset/table_strategy/cff2.rb +391 -0
  450. data/lib/fontisan/subset/table_strategy/cmap.rb +146 -0
  451. data/lib/fontisan/subset/table_strategy/color_bitmap_placement.rb +20 -0
  452. data/lib/fontisan/subset/table_strategy/color_bitmap_strike_plan.rb +45 -0
  453. data/lib/fontisan/subset/table_strategy/color_bitmap_subset_plan.rb +62 -0
  454. data/lib/fontisan/subset/table_strategy/color_bitmap_subsetter.rb +182 -0
  455. data/lib/fontisan/subset/table_strategy/color_bitmap_subtable_plan.rb +59 -0
  456. data/lib/fontisan/subset/table_strategy/glyf.rb +29 -0
  457. data/lib/fontisan/subset/table_strategy/glyf_loca_builder.rb +146 -0
  458. data/lib/fontisan/subset/table_strategy/head.rb +43 -0
  459. data/lib/fontisan/subset/table_strategy/hhea.rb +67 -0
  460. data/lib/fontisan/subset/table_strategy/hmtx.rb +52 -0
  461. data/lib/fontisan/subset/table_strategy/loca.rb +41 -0
  462. data/lib/fontisan/subset/table_strategy/maxp.rb +23 -0
  463. data/lib/fontisan/subset/table_strategy/name.rb +19 -0
  464. data/lib/fontisan/subset/table_strategy/os2.rb +21 -0
  465. data/lib/fontisan/subset/table_strategy/pass_through.rb +20 -0
  466. data/lib/fontisan/subset/table_strategy/post.rb +37 -0
  467. data/lib/fontisan/subset/table_strategy.rb +79 -0
  468. data/lib/fontisan/subset/table_subsetter.rb +110 -0
  469. data/lib/fontisan/subset.rb +16 -0
  470. data/lib/fontisan/svg/font_face_generator.rb +274 -0
  471. data/lib/fontisan/svg/font_generator.rb +256 -0
  472. data/lib/fontisan/svg/glyph_generator.rb +201 -0
  473. data/lib/fontisan/svg/standalone_glyph.rb +132 -0
  474. data/lib/fontisan/svg/view_box_calculator.rb +137 -0
  475. data/lib/fontisan/svg.rb +13 -0
  476. data/lib/fontisan/svg_to_glyf/assembler.rb +174 -0
  477. data/lib/fontisan/svg_to_glyf/document.rb +102 -0
  478. data/lib/fontisan/svg_to_glyf/geometry/affine_transform.rb +112 -0
  479. data/lib/fontisan/svg_to_glyf/geometry/normalizer.rb +62 -0
  480. data/lib/fontisan/svg_to_glyf/geometry/transform_parser.rb +98 -0
  481. data/lib/fontisan/svg_to_glyf/geometry.rb +15 -0
  482. data/lib/fontisan/svg_to_glyf/path/command.rb +18 -0
  483. data/lib/fontisan/svg_to_glyf/path/contour_builder.rb +140 -0
  484. data/lib/fontisan/svg_to_glyf/path/parser.rb +98 -0
  485. data/lib/fontisan/svg_to_glyf/path/state.rb +79 -0
  486. data/lib/fontisan/svg_to_glyf/path.rb +14 -0
  487. data/lib/fontisan/svg_to_glyf.rb +62 -0
  488. data/lib/fontisan/tables/cbdt.rb +113 -0
  489. data/lib/fontisan/tables/cblc.rb +172 -0
  490. data/lib/fontisan/tables/cblc_big_glyph_metrics.rb +28 -0
  491. data/lib/fontisan/tables/cblc_bitmap_size.rb +67 -0
  492. data/lib/fontisan/tables/cblc_glyph_bitmap_location.rb +28 -0
  493. data/lib/fontisan/tables/cblc_index_subtable.rb +104 -0
  494. data/lib/fontisan/tables/cblc_index_subtable_array_entry.rb +20 -0
  495. data/lib/fontisan/tables/cblc_index_subtable_format_parser.rb +150 -0
  496. data/lib/fontisan/tables/cblc_index_subtable_header.rb +18 -0
  497. data/lib/fontisan/tables/cblc_sbit_line_metrics.rb +28 -0
  498. data/lib/fontisan/tables/cff/cff2_charstring_builder.rb +225 -0
  499. data/lib/fontisan/tables/cff/cff_glyph.rb +176 -0
  500. data/lib/fontisan/tables/cff/charset.rb +276 -0
  501. data/lib/fontisan/tables/cff/charstring.rb +978 -0
  502. data/lib/fontisan/tables/cff/charstring_builder.rb +356 -0
  503. data/lib/fontisan/tables/cff/charstring_parser.rb +249 -0
  504. data/lib/fontisan/tables/cff/charstring_rebuilder.rb +168 -0
  505. data/lib/fontisan/tables/cff/charstrings_index.rb +159 -0
  506. data/lib/fontisan/tables/cff/dict.rb +353 -0
  507. data/lib/fontisan/tables/cff/dict_builder.rb +260 -0
  508. data/lib/fontisan/tables/cff/encoding.rb +273 -0
  509. data/lib/fontisan/tables/cff/expert_charsets.rb +85 -0
  510. data/lib/fontisan/tables/cff/header.rb +100 -0
  511. data/lib/fontisan/tables/cff/hint_operation_injector.rb +207 -0
  512. data/lib/fontisan/tables/cff/index.rb +241 -0
  513. data/lib/fontisan/tables/cff/index_builder.rb +170 -0
  514. data/lib/fontisan/tables/cff/offset_recalculator.rb +70 -0
  515. data/lib/fontisan/tables/cff/private_dict.rb +282 -0
  516. data/lib/fontisan/tables/cff/private_dict_writer.rb +129 -0
  517. data/lib/fontisan/tables/cff/standard_strings_data.rb +83 -0
  518. data/lib/fontisan/tables/cff/table_builder.rb +215 -0
  519. data/lib/fontisan/tables/cff/top_dict.rb +234 -0
  520. data/lib/fontisan/tables/cff.rb +497 -0
  521. data/lib/fontisan/tables/cff2/blend_operator.rb +240 -0
  522. data/lib/fontisan/tables/cff2/charstring_parser.rb +624 -0
  523. data/lib/fontisan/tables/cff2/dict_encoder.rb +94 -0
  524. data/lib/fontisan/tables/cff2/fd_select.rb +142 -0
  525. data/lib/fontisan/tables/cff2/header.rb +34 -0
  526. data/lib/fontisan/tables/cff2/index.rb +155 -0
  527. data/lib/fontisan/tables/cff2/index_builder.rb +80 -0
  528. data/lib/fontisan/tables/cff2/operand_stack.rb +232 -0
  529. data/lib/fontisan/tables/cff2/private_dict_blend_handler.rb +247 -0
  530. data/lib/fontisan/tables/cff2/region_matcher.rb +200 -0
  531. data/lib/fontisan/tables/cff2/table_builder.rb +567 -0
  532. data/lib/fontisan/tables/cff2/table_reader.rb +418 -0
  533. data/lib/fontisan/tables/cff2/variation_data_extractor.rb +212 -0
  534. data/lib/fontisan/tables/cff2.rb +353 -0
  535. data/lib/fontisan/tables/cmap.rb +399 -0
  536. data/lib/fontisan/tables/cmap_table.rb +228 -0
  537. data/lib/fontisan/tables/colr.rb +290 -0
  538. data/lib/fontisan/tables/cpal.rb +381 -0
  539. data/lib/fontisan/tables/cvar.rb +204 -0
  540. data/lib/fontisan/tables/fvar.rb +159 -0
  541. data/lib/fontisan/tables/glyf/compound_glyph.rb +482 -0
  542. data/lib/fontisan/tables/glyf/compound_glyph_resolver.rb +135 -0
  543. data/lib/fontisan/tables/glyf/curve_converter.rb +349 -0
  544. data/lib/fontisan/tables/glyf/glyph_builder.rb +468 -0
  545. data/lib/fontisan/tables/glyf/simple_glyph.rb +391 -0
  546. data/lib/fontisan/tables/glyf.rb +347 -0
  547. data/lib/fontisan/tables/glyf_table.rb +252 -0
  548. data/lib/fontisan/tables/gpos/glyph_filter.rb +87 -0
  549. data/lib/fontisan/tables/gpos/kerning_pairs.rb +215 -0
  550. data/lib/fontisan/tables/gpos/pair_position.rb +274 -0
  551. data/lib/fontisan/tables/gpos.rb +139 -0
  552. data/lib/fontisan/tables/gsub.rb +116 -0
  553. data/lib/fontisan/tables/gvar.rb +232 -0
  554. data/lib/fontisan/tables/head.rb +208 -0
  555. data/lib/fontisan/tables/head_table.rb +108 -0
  556. data/lib/fontisan/tables/hhea.rb +199 -0
  557. data/lib/fontisan/tables/hhea_table.rb +252 -0
  558. data/lib/fontisan/tables/hmtx.rb +281 -0
  559. data/lib/fontisan/tables/hmtx_table.rb +188 -0
  560. data/lib/fontisan/tables/hvar.rb +192 -0
  561. data/lib/fontisan/tables/layout_common.rb +245 -0
  562. data/lib/fontisan/tables/loca.rb +323 -0
  563. data/lib/fontisan/tables/loca_table.rb +209 -0
  564. data/lib/fontisan/tables/maxp.rb +253 -0
  565. data/lib/fontisan/tables/maxp_table.rb +255 -0
  566. data/lib/fontisan/tables/mvar.rb +185 -0
  567. data/lib/fontisan/tables/name.rb +340 -0
  568. data/lib/fontisan/tables/name_table.rb +173 -0
  569. data/lib/fontisan/tables/os2.rb +291 -0
  570. data/lib/fontisan/tables/os2_table.rb +326 -0
  571. data/lib/fontisan/tables/post.rb +206 -0
  572. data/lib/fontisan/tables/post_table.rb +180 -0
  573. data/lib/fontisan/tables/registry.rb +71 -0
  574. data/lib/fontisan/tables/sbix.rb +379 -0
  575. data/lib/fontisan/tables/svg.rb +300 -0
  576. data/lib/fontisan/tables/variation_common.rb +345 -0
  577. data/lib/fontisan/tables/vvar.rb +234 -0
  578. data/lib/fontisan/tables.rb +69 -0
  579. data/lib/fontisan/true_type_collection.rb +160 -0
  580. data/lib/fontisan/true_type_font.rb +80 -0
  581. data/lib/fontisan/true_type_font_extensions.rb +54 -0
  582. data/lib/fontisan/type1/afm_generator.rb +379 -0
  583. data/lib/fontisan/type1/afm_parser.rb +299 -0
  584. data/lib/fontisan/type1/agl.rb +456 -0
  585. data/lib/fontisan/type1/cff_to_type1_converter.rb +307 -0
  586. data/lib/fontisan/type1/charstring_converter.rb +238 -0
  587. data/lib/fontisan/type1/charstrings.rb +441 -0
  588. data/lib/fontisan/type1/conversion_options.rb +242 -0
  589. data/lib/fontisan/type1/decryptor.rb +183 -0
  590. data/lib/fontisan/type1/encodings.rb +695 -0
  591. data/lib/fontisan/type1/font_dictionary.rb +576 -0
  592. data/lib/fontisan/type1/generator.rb +217 -0
  593. data/lib/fontisan/type1/inf_generator.rb +307 -0
  594. data/lib/fontisan/type1/pfa_generator.rb +376 -0
  595. data/lib/fontisan/type1/pfa_parser.rb +159 -0
  596. data/lib/fontisan/type1/pfb_generator.rb +321 -0
  597. data/lib/fontisan/type1/pfb_parser.rb +166 -0
  598. data/lib/fontisan/type1/pfm_generator.rb +589 -0
  599. data/lib/fontisan/type1/pfm_parser.rb +433 -0
  600. data/lib/fontisan/type1/private_dict.rb +363 -0
  601. data/lib/fontisan/type1/seac_expander.rb +517 -0
  602. data/lib/fontisan/type1/ttf_to_type1_converter.rb +389 -0
  603. data/lib/fontisan/type1/upm_scaler.rb +118 -0
  604. data/lib/fontisan/type1.rb +48 -0
  605. data/lib/fontisan/type1_font.rb +347 -0
  606. data/lib/fontisan/ufo/anchor.rb +17 -0
  607. data/lib/fontisan/ufo/bounds.rb +91 -0
  608. data/lib/fontisan/ufo/cli.rb +105 -0
  609. data/lib/fontisan/ufo/compile/avar.rb +46 -0
  610. data/lib/fontisan/ufo/compile/base_compiler.rb +162 -0
  611. data/lib/fontisan/ufo/compile/cbdt_cblc.rb +104 -0
  612. data/lib/fontisan/ufo/compile/cff.rb +229 -0
  613. data/lib/fontisan/ufo/compile/cff2.rb +323 -0
  614. data/lib/fontisan/ufo/compile/cff2_subroutines.rb +39 -0
  615. data/lib/fontisan/ufo/compile/cmap.rb +143 -0
  616. data/lib/fontisan/ufo/compile/colr.rb +80 -0
  617. data/lib/fontisan/ufo/compile/cpal.rb +62 -0
  618. data/lib/fontisan/ufo/compile/feature_compiler.rb +161 -0
  619. data/lib/fontisan/ufo/compile/feature_writers/base.rb +56 -0
  620. data/lib/fontisan/ufo/compile/feature_writers/curs.rb +72 -0
  621. data/lib/fontisan/ufo/compile/feature_writers/gdef.rb +92 -0
  622. data/lib/fontisan/ufo/compile/feature_writers/kern.rb +50 -0
  623. data/lib/fontisan/ufo/compile/feature_writers/kern2.rb +57 -0
  624. data/lib/fontisan/ufo/compile/feature_writers/mark.rb +45 -0
  625. data/lib/fontisan/ufo/compile/feature_writers/mark_family_base.rb +124 -0
  626. data/lib/fontisan/ufo/compile/feature_writers/mkmk.rb +53 -0
  627. data/lib/fontisan/ufo/compile/feature_writers.rb +38 -0
  628. data/lib/fontisan/ufo/compile/filters/cubic_to_quadratic.rb +176 -0
  629. data/lib/fontisan/ufo/compile/filters/decompose_components.rb +33 -0
  630. data/lib/fontisan/ufo/compile/filters/flatten_components.rb +22 -0
  631. data/lib/fontisan/ufo/compile/filters/propagate_anchors.rb +102 -0
  632. data/lib/fontisan/ufo/compile/filters/remove_overlaps.rb +95 -0
  633. data/lib/fontisan/ufo/compile/filters/reverse_contour_direction.rb +27 -0
  634. data/lib/fontisan/ufo/compile/filters/sort_contours.rb +69 -0
  635. data/lib/fontisan/ufo/compile/filters/transformations.rb +113 -0
  636. data/lib/fontisan/ufo/compile/filters.rb +69 -0
  637. data/lib/fontisan/ufo/compile/fvar.rb +113 -0
  638. data/lib/fontisan/ufo/compile/glyf_loca.rb +206 -0
  639. data/lib/fontisan/ufo/compile/gpos.rb +248 -0
  640. data/lib/fontisan/ufo/compile/gsub.rb +267 -0
  641. data/lib/fontisan/ufo/compile/gvar.rb +225 -0
  642. data/lib/fontisan/ufo/compile/head.rb +97 -0
  643. data/lib/fontisan/ufo/compile/hhea.rb +57 -0
  644. data/lib/fontisan/ufo/compile/hmtx.rb +38 -0
  645. data/lib/fontisan/ufo/compile/hvar.rb +42 -0
  646. data/lib/fontisan/ufo/compile/item_variation_store.rb +100 -0
  647. data/lib/fontisan/ufo/compile/math.rb +143 -0
  648. data/lib/fontisan/ufo/compile/maxp.rb +57 -0
  649. data/lib/fontisan/ufo/compile/meta.rb +51 -0
  650. data/lib/fontisan/ufo/compile/mvar.rb +59 -0
  651. data/lib/fontisan/ufo/compile/name.rb +81 -0
  652. data/lib/fontisan/ufo/compile/os2.rb +81 -0
  653. data/lib/fontisan/ufo/compile/otf2_compiler.rb +40 -0
  654. data/lib/fontisan/ufo/compile/otf_compiler.rb +34 -0
  655. data/lib/fontisan/ufo/compile/post.rb +32 -0
  656. data/lib/fontisan/ufo/compile/sbix.rb +100 -0
  657. data/lib/fontisan/ufo/compile/stat.rb +106 -0
  658. data/lib/fontisan/ufo/compile/svg_table.rb +60 -0
  659. data/lib/fontisan/ufo/compile/ttf_compiler.rb +75 -0
  660. data/lib/fontisan/ufo/compile/variable_otf.rb +84 -0
  661. data/lib/fontisan/ufo/compile/variable_ttf.rb +161 -0
  662. data/lib/fontisan/ufo/compile.rb +72 -0
  663. data/lib/fontisan/ufo/component.rb +18 -0
  664. data/lib/fontisan/ufo/contour.rb +34 -0
  665. data/lib/fontisan/ufo/convert/from_bin_data.rb +366 -0
  666. data/lib/fontisan/ufo/convert/to_dfont.rb +45 -0
  667. data/lib/fontisan/ufo/convert/to_otc.rb +40 -0
  668. data/lib/fontisan/ufo/convert/to_otf.rb +18 -0
  669. data/lib/fontisan/ufo/convert/to_otf2.rb +20 -0
  670. data/lib/fontisan/ufo/convert/to_postscript.rb +64 -0
  671. data/lib/fontisan/ufo/convert/to_ttc.rb +35 -0
  672. data/lib/fontisan/ufo/convert/to_ttf.rb +21 -0
  673. data/lib/fontisan/ufo/convert/to_woff.rb +61 -0
  674. data/lib/fontisan/ufo/convert/to_woff2.rb +50 -0
  675. data/lib/fontisan/ufo/convert.rb +84 -0
  676. data/lib/fontisan/ufo/data_set.rb +21 -0
  677. data/lib/fontisan/ufo/features.rb +17 -0
  678. data/lib/fontisan/ufo/font.rb +63 -0
  679. data/lib/fontisan/ufo/glyph.rb +445 -0
  680. data/lib/fontisan/ufo/glyph_exists_error.rb +23 -0
  681. data/lib/fontisan/ufo/groups.rb +45 -0
  682. data/lib/fontisan/ufo/guideline.rb +19 -0
  683. data/lib/fontisan/ufo/image.rb +29 -0
  684. data/lib/fontisan/ufo/image_set.rb +99 -0
  685. data/lib/fontisan/ufo/info.rb +133 -0
  686. data/lib/fontisan/ufo/kerning.rb +32 -0
  687. data/lib/fontisan/ufo/layer.rb +78 -0
  688. data/lib/fontisan/ufo/layer_set.rb +37 -0
  689. data/lib/fontisan/ufo/lib.rb +24 -0
  690. data/lib/fontisan/ufo/plist.rb +123 -0
  691. data/lib/fontisan/ufo/point.rb +32 -0
  692. data/lib/fontisan/ufo/reader.rb +163 -0
  693. data/lib/fontisan/ufo/transformation.rb +50 -0
  694. data/lib/fontisan/ufo/writer.rb +123 -0
  695. data/lib/fontisan/ufo.rb +47 -0
  696. data/lib/fontisan/unicode/plane.rb +44 -0
  697. data/lib/fontisan/unicode.rb +17 -0
  698. data/lib/fontisan/utilities/brotli_wrapper.rb +177 -0
  699. data/lib/fontisan/utilities/checksum_calculator.rb +104 -0
  700. data/lib/fontisan/utilities/padding.rb +61 -0
  701. data/lib/fontisan/utilities.rb +11 -0
  702. data/lib/fontisan/utils/thread_pool.rb +134 -0
  703. data/lib/fontisan/utils.rb +10 -0
  704. data/lib/fontisan/validation/collection_validator.rb +265 -0
  705. data/lib/fontisan/validation.rb +9 -0
  706. data/lib/fontisan/validators/basic_validator.rb +73 -0
  707. data/lib/fontisan/validators/font_book_validator.rb +107 -0
  708. data/lib/fontisan/validators/opentype_validator.rb +118 -0
  709. data/lib/fontisan/validators/profile_loader.rb +134 -0
  710. data/lib/fontisan/validators/validator.rb +494 -0
  711. data/lib/fontisan/validators/web_font_validator.rb +95 -0
  712. data/lib/fontisan/validators.rb +14 -0
  713. data/lib/fontisan/variable/axis_normalizer.rb +215 -0
  714. data/lib/fontisan/variable/delta_applicator.rb +302 -0
  715. data/lib/fontisan/variable/glyph_delta_processor.rb +218 -0
  716. data/lib/fontisan/variable/instancer.rb +172 -0
  717. data/lib/fontisan/variable/metric_delta_processor.rb +282 -0
  718. data/lib/fontisan/variable/region_matcher.rb +208 -0
  719. data/lib/fontisan/variable/static_font_builder.rb +209 -0
  720. data/lib/fontisan/variable/table_updater.rb +219 -0
  721. data/lib/fontisan/variable.rb +16 -0
  722. data/lib/fontisan/variation/blend_applier.rb +197 -0
  723. data/lib/fontisan/variation/cache.rb +299 -0
  724. data/lib/fontisan/variation/cache_key_builder.rb +162 -0
  725. data/lib/fontisan/variation/converter.rb +373 -0
  726. data/lib/fontisan/variation/data_extractor.rb +84 -0
  727. data/lib/fontisan/variation/delta_applier.rb +262 -0
  728. data/lib/fontisan/variation/delta_parser.rb +228 -0
  729. data/lib/fontisan/variation/inspector.rb +275 -0
  730. data/lib/fontisan/variation/instance_font_wrapper.rb +41 -0
  731. data/lib/fontisan/variation/instance_generator.rb +122 -0
  732. data/lib/fontisan/variation/instance_writer.rb +360 -0
  733. data/lib/fontisan/variation/instancing/axis_space.rb +136 -0
  734. data/lib/fontisan/variation/instancing/glyph_outline.rb +204 -0
  735. data/lib/fontisan/variation/instancing/gvar_reader.rb +146 -0
  736. data/lib/fontisan/variation/instancing/item_variation_store.rb +92 -0
  737. data/lib/fontisan/variation/instancing/name_rewriter.rb +90 -0
  738. data/lib/fontisan/variation/instancing/true_type_instancer.rb +326 -0
  739. data/lib/fontisan/variation/instancing.rb +20 -0
  740. data/lib/fontisan/variation/interpolator.rb +231 -0
  741. data/lib/fontisan/variation/metrics_adjuster.rb +309 -0
  742. data/lib/fontisan/variation/optimizer.rb +417 -0
  743. data/lib/fontisan/variation/parallel_generator.rb +147 -0
  744. data/lib/fontisan/variation/region_matcher.rb +221 -0
  745. data/lib/fontisan/variation/subsetter.rb +400 -0
  746. data/lib/fontisan/variation/table_accessor.rb +105 -0
  747. data/lib/fontisan/variation/tuple_variation_header.rb +49 -0
  748. data/lib/fontisan/variation/validator.rb +336 -0
  749. data/lib/fontisan/variation/variable_svg_generator.rb +235 -0
  750. data/lib/fontisan/variation/variation_context.rb +208 -0
  751. data/lib/fontisan/variation/variation_preserver.rb +287 -0
  752. data/lib/fontisan/variation.rb +33 -0
  753. data/lib/fontisan/version.rb +5 -0
  754. data/lib/fontisan/version.rb.orig +9 -0
  755. data/lib/fontisan/woff2/collection_decoder.rb +223 -0
  756. data/lib/fontisan/woff2/collection_encoder.rb +302 -0
  757. data/lib/fontisan/woff2/directory.rb +255 -0
  758. data/lib/fontisan/woff2/encoder_rules.rb +114 -0
  759. data/lib/fontisan/woff2/glyf_canonicalizer.rb +90 -0
  760. data/lib/fontisan/woff2/glyf_loca_reconstruct.rb +401 -0
  761. data/lib/fontisan/woff2/glyf_loca_transform.rb +319 -0
  762. data/lib/fontisan/woff2/header.rb +101 -0
  763. data/lib/fontisan/woff2/hmtx_transformer.rb +140 -0
  764. data/lib/fontisan/woff2/sfnt_checksum.rb +107 -0
  765. data/lib/fontisan/woff2/table_transformer.rb +575 -0
  766. data/lib/fontisan/woff2/triplet_codec.rb +181 -0
  767. data/lib/fontisan/woff2/uint255.rb +101 -0
  768. data/lib/fontisan/woff2.rb +21 -0
  769. data/lib/fontisan/woff2_collection.rb +127 -0
  770. data/lib/fontisan/woff2_font.rb +754 -0
  771. data/lib/fontisan/woff_container.rb +83 -0
  772. data/lib/fontisan/woff_font.rb +554 -0
  773. data/lib/fontisan.rb +299 -0
  774. data/rakelib/bench.rake +9 -0
  775. data/rakelib/cdylib.rake +39 -0
  776. data/rakelib/corpus.rake +272 -0
  777. data/rakelib/corpus_convert.rake +43 -0
  778. data/rakelib/corpus_goldens.rake +22 -0
  779. data/rakelib/corpus_malformed.rake +20 -0
  780. data/rakelib/corpus_scan.rake +24 -0
  781. data/rakelib/java.rake +61 -0
  782. data/rakelib/native.rake +43 -0
  783. data/scripts/build-woff2.sh +57 -0
  784. data/scripts/compare_stack_aware.rb +187 -0
  785. data/scripts/corpus/generate_convert_goldens.rb +478 -0
  786. data/scripts/corpus/generate_goldens.rb +282 -0
  787. data/scripts/corpus/generate_malformed_goldens.rb +254 -0
  788. data/scripts/corpus/generate_scan_goldens.rb +98 -0
  789. data/scripts/measure_optimization.rb +148 -0
  790. data/scripts/tier_fallback.rb +228 -0
  791. data/scripts/tier_smoke.rb +72 -0
  792. metadata +945 -0
data/README.adoc ADDED
@@ -0,0 +1,2811 @@
1
+ = Fontisan: Font analysis tools and utilities
2
+
3
+ image:https://img.shields.io/gem/v/fontisan.svg[RubyGems Version, link=https://rubygems.org/gems/fontisan]
4
+ image:https://img.shields.io/github/license/fontist/fontisan.svg[License]
5
+ image:https://github.com/fontist/fontisan/actions/workflows/test.yml/badge.svg[Build Status, link=https://github.com/fontist/fontisan/actions/workflows/test.yml]
6
+
7
+ == Purpose
8
+
9
+ Fontisan is a Ruby gem providing font analysis tools and utilities.
10
+
11
+ It is designed as a pure Ruby implementation with full object-oriented
12
+ architecture, supporting extraction of information from OpenType, TrueType,
13
+ and Adobe Type 1 fonts (OTF, TTF, OTC, TTC, dfont, PFB, PFA).
14
+
15
+ The gem provides both a Ruby library API and a command-line interface, with
16
+ structured output formats (YAML, JSON, text) via lutaml-model.
17
+
18
+ Fontisan is designed to replace the following tools (see
19
+ link:docs/FEATURE_PARITY.adoc[Feature Parity] for the full list and
20
+ per-tool coverage):
21
+
22
+ * `otfinfo` from http://www.lcdf.org/type/[LCDF Typetools]. Fontisan supports
23
+ all features provided by `otfinfo`, including extraction of font metadata,
24
+ OpenType tables, glyph names, Unicode mappings, variable font axes, optical size
25
+ information, supported scripts, OpenType features, and raw table dumps.
26
+
27
+ * `extract_ttc` from https://github.com/fontist/extract_ttc[ExtractTTC].
28
+ Fontisan fully supersedes extract_ttc with Docker-like commands (`ls`, `info`,
29
+ `unpack`) that work on both collections and individual fonts. Fontisan provides
30
+ all `extract_ttc` functionality plus comprehensive font analysis, subsetting,
31
+ validation, format conversion, and collection creation. See
32
+ link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide] for detailed
33
+ command mappings and usage examples.
34
+
35
+ * **Adobe AFDKO** — `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`,
36
+ `checkOutlinesUFO`, `rotateFont`. See
37
+ link:docs/AFDKO_MIGRATION.adoc[AFDKO Migration Guide].
38
+
39
+ * **Python fontTools + ufoLib2 + ufo2ft** — UFO model layer, UFO
40
+ compile pipeline (TTF/OTF/CFF2 + variable), glyph filters (8/8),
41
+ feature writers (GDEF, kern, mark, mkmk, curs), `pyftsubset`,
42
+ `pyftmerge`, `varLib`. See link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide].
43
+
44
+ * **`ttx` (TTX format)** — full read/write of the FontTools XML
45
+ format. See link:docs/TTX.adoc[TTX Support].
46
+
47
+ * **Google `woff2_compress` / `woff2_decompress`** — WOFF and
48
+ WOFF2 compression/decompression in pure Ruby. See
49
+ link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Formats Guide].
50
+
51
+ * **Type 1 utilities** (`t1disasm`, `t1asm`, `t1embed`, `pfm2afm`)
52
+ — full PFB/PFA parse/generate, eexec decryption, PFM↔AFM
53
+ round-trip. See link:docs/TYPE1_FONTS.adoc[Type 1 Fonts Guide].
54
+
55
+
56
+ == Engine
57
+
58
+ Fontisan can serve its read, audit, scan, convert, extract, instance and subset
59
+ operations from three tiers: `native` (a precompiled Rust extension), `ffi` (the
60
+ bundled Rust shared library, loaded through the `ffi` gem) and `ruby` (the pure
61
+ Ruby implementation, always present).
62
+
63
+ The default is `auto`, which currently serves everything from `ruby`: the Rust
64
+ tiers are used only when selected with `FONTISAN_ENGINE=native` or `ffi`, until
65
+ the native tier's release gates pass (see fontist/fontisan#160). After that,
66
+ `auto` will pick the first available tier in the order `native`, `ffi`, `ruby`.
67
+
68
+ [cols="1,3"]
69
+ |===
70
+ |Variable |Effect
71
+
72
+ |`FONTISAN_ENGINE=auto\|native\|ffi\|ruby`
73
+ |Pick the tier. Unset or empty means `auto`. `ruby` never uses the Rust tiers.
74
+ A forced tier that is not available falls back to `ruby`.
75
+
76
+ |`FONTISAN_ENGINE_STRICT=1`
77
+ |No fallback: a forced tier that is not available raises
78
+ `Fontisan::Engine::TierUnavailable` at setup. `1`, `true`, `yes` and `on` enable it;
79
+ unset, empty, `0`, `false`, `no` and `off` leave it off; any other value raises
80
+ `Fontisan::Engine::ConfigError`.
81
+ |===
82
+
83
+ `Fontisan::Engine.served_by(:read)` reports which tier served the last call of
84
+ an operation. See link:docs/guide/engines.md[Engines] for tiers, platforms and
85
+ troubleshooting.
86
+
87
+ === Python face
88
+
89
+ https://github.com/fontist/fontisan-python[fontisan-python] is the Python face
90
+ of fontisan. It is a setuptools package that rides the same Rust cdylib the
91
+ `ffi` tier loads, shipped as per-platform package data and bound with
92
+ `ctypes`. It is not a second engine and adds no new FFI surface.
93
+
94
+ It binds the batch audit and table-read operations. Anything the C ABI does not
95
+ expose returns an explicit `unsupported` result rather than a guess.
96
+
97
+ Its results are held to the same parity contract as the other faces: they are
98
+ compared against the Ruby-tier goldens in `corpus/` (see
99
+ link:https://github.com/fontist/fontisan/issues/166[fontist/fontisan#166]).
100
+
101
+ NOTE: The package name on PyPI and the Python version floor are not settled,
102
+ and nothing is published yet. Treat the package as unreleased until the
103
+ maintainers say otherwise.
104
+
105
+ == Installation
106
+
107
+ Add this line to your application's Gemfile:
108
+
109
+ [source,ruby]
110
+ ----
111
+ gem "fontisan"
112
+ ----
113
+
114
+ And then execute:
115
+
116
+ [source,shell]
117
+ ----
118
+ bundle install
119
+ ----
120
+
121
+ Or install it yourself as:
122
+
123
+ [source,shell]
124
+ ----
125
+ gem install fontisan
126
+ ----
127
+
128
+ == Features
129
+
130
+ Font compilation and assembly::
131
+ * UFO → TTF compilation with cubic-to-quadratic conversion and winding-order correction (see link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide])
132
+ * UFO → OTF (CFF1) compilation with Type 2 charstring encoding
133
+ * UFO → OTF (CFF2) compilation with variable-font blend/vsindex operators (see link:docs/CFF2_SUPPORT.adoc[CFF2 Support Guide])
134
+ * UFO → all binary formats via the `Ufo::Convert` dispatcher: TTF, OTF, OTF2, WOFF, WOFF2, dfont, TTC, OTC, PFB, PFA
135
+ * UFO feature writers: GDEF glyph classification, GPOS kern/mark/mkmk/curs (see link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide — Filters + Feature Writers])
136
+ * Glyph-processing filters: cubic_to_quadratic, decompose_components, flatten_components, reverse_contour_direction, transformations, sort_contours, propagate_anchors, remove_overlaps
137
+ * Multi-source font stitching with explicit subfont declaration and TTC/OTC collection output (see link:docs/STITCHER_GUIDE.adoc[Stitcher Guide])
138
+ * SVG path → UFO glyph conversion for chart-extracted glyphs (see link:docs/SVG_TO_GLYF.adoc[SVG to Glyph Guide])
139
+ * Variable font compilation: fvar, gvar, HVAR, MVAR, avar, STAT tables
140
+ * Signature-based glyph deduplication with 65,535 glyph cap enforcement
141
+ * Compound (composite) TrueType glyph flattening
142
+ * AFDKO migration: drop-in replacement for `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`, `checkOutlinesUFO` (see link:docs/AFDKO_MIGRATION.adoc[AFDKO Migration Guide])
143
+
144
+ Color fonts and collections::
145
+ * Color font table builders: COLR v0, CPAL, SVG table, sbix, CBDT/CBLC (see link:docs/COLOR_FONTS.adoc[Color Fonts Guide])
146
+ * Font collection management: pack/unpack TTC/OTC with table deduplication (see link:docs/COLLECTION_VALIDATION.adoc[Collection Validation Guide])
147
+
148
+ Font analysis and information::
149
+ * Comprehensive per-face font metadata extraction (replaces `otfinfo`) covering identity, style, metrics, codepoint coverage, licensing, hinting, color capabilities, variable-font detail, and OpenType layout features
150
+ * Bidirectional font hint conversion (see link:docs/FONT_HINTING.adoc[Font Hinting Guide])
151
+ * Extract comprehensive font metadata (name, version, designer, license, etc.)
152
+ * Brief mode for fast font indexing (5x faster, metadata-only loading)
153
+ * List OpenType tables with checksums and offsets
154
+ * Extract glyph names from post table
155
+ * Display Unicode codepoint to glyph index mappings
156
+ * Analyze variable font axes and named instances
157
+ * Display optical size information
158
+ * List supported scripts from GSUB/GPOS tables
159
+ * List OpenType features (ligatures, kerning, etc.) by script
160
+ * Dump raw binary table data for analysis
161
+
162
+ Font operations::
163
+ * Generate static font instances from variable fonts
164
+ * Font subsetting with multiple profiles (PDF, web, minimal)
165
+ * Font validation framework with multiple profiles (indexability, usability, production, web, spec_compliance) (see link:docs/VALIDATION.adoc[Validation Guide])
166
+ * Collection management (pack/unpack TTC/OTC/dfont files with table deduplication)
167
+
168
+ Font format support::
169
+ * TTF, OTF (CFF1), OTF2 (CFF2), TTC, OTC font formats (production ready)
170
+ * CFF2 with variable-font blend/vsindex operators, FDSelect, subroutines
171
+ * Adobe Type 1 fonts (PFB/PFA) with bidirectional conversion (see link:docs/TYPE1_FONTS.adoc[Type 1 Fonts Guide])
172
+ * WOFF/WOFF2 format support with reading, writing, and conversion — fully compliant with W3C WOFF 1.0 (https://www.w3.org/TR/WOFF/[Recommendation 13 December 2012]) and WOFF 2.0 (https://www.w3.org/TR/WOFF2/[Recommendation 08 August 2024]) specifications. See link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Guide].
173
+ * Apple legacy font support: 'true' signature TrueType fonts and dfont format (see link:docs/APPLE_LEGACY_FONTS.adoc[Apple Legacy Fonts Guide])
174
+ * SVG font generation and SVG-to-glyph conversion (complete)
175
+
176
+ Font engineering::
177
+ * Universal outline model for format-agnostic glyph representation
178
+ * CFF/CFF2 CharString encoding/decoding with blend operator support
179
+ * CFF/CFF2 INDEX structure building (uint16 for CFF1, uint32 for CFF2)
180
+ * CFF/CFF2 DICT structure building
181
+ * TrueType curve converter for bi-directional quadratic/cubic conversion (complete)
182
+ * Compound glyph decomposition with affine transformation flattening (complete)
183
+ * CFF2 subroutine bias calculation and INDEX management
184
+ * FDSelect (format 0, 3) for CID-keyed CFF2 fonts
185
+ * Bidirectional hint conversion (TrueType ↔ PostScript) with validation (complete)
186
+ * MATH table builder for mathematical formula layout
187
+ * Meta table builder for tagged metadata
188
+ * Glyph signature-based deduplication across donor fonts
189
+ * CFF2 variable font support for PostScript hint conversion (complete)
190
+
191
+ Export and interfaces::
192
+ * TTX/YAML/JSON export (complete)
193
+ * Command-line interface with 19 commands
194
+ * Ruby library API for programmatic access
195
+ * Structured output in YAML, JSON, and text formats
196
+
197
+
198
+ == Font audit
199
+
200
+ [NOTE]
201
+ ====
202
+ The `audit` and `ucd` subsystems have moved to the `ucode` gem. See
203
+ the `ucode` documentation for the equivalent commands.
204
+ ====
205
+
206
+
207
+ == Font information
208
+
209
+ === General
210
+
211
+ Extract comprehensive metadata from font files. This includes font names,
212
+ version information, designer credits, vendor details, licensing information,
213
+ and font metrics.
214
+
215
+ [source,shell]
216
+ ----
217
+
218
+ $ fontisan info FONT_FILE [--format FORMAT] [--brief]
219
+ ----
220
+
221
+ Where,
222
+
223
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
224
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
225
+ `--brief`:: Show only basic font information
226
+
227
+
228
+ === Brief mode
229
+
230
+ ==== General
231
+
232
+ For font indexing systems that need to scan thousands of fonts quickly, use the
233
+ `--brief` flag to get essential metadata only. This mode uses metadata loading
234
+ and is **5x faster** than full mode.
235
+
236
+ Brief mode provides significant performance improvements for font indexing:
237
+
238
+ * **5x faster** than full mode by using the `metadata` load mode
239
+ * **Loads only 6 tables** instead of 15-20 (name, head, hhea, maxp, OS/2, post)
240
+ * **Lower memory usage** through reduced table loading
241
+ * **Optimized for batch processing** of many fonts
242
+
243
+ Brief mode populates only the following 13 essential attributes:
244
+
245
+ Font identification::
246
+ * `font_format` - Font format (truetype, cff)
247
+ * `is_variable` - Whether font is variable
248
+
249
+ Essential names::
250
+ * `family_name` - Font family name
251
+ * `subfamily_name` - Font subfamily/style
252
+ * `full_name` - Full font name
253
+ * `postscript_name` - PostScript name
254
+
255
+ Version info::
256
+ * `version` - Version string
257
+
258
+ Metrics::
259
+ * `font_revision` - Font revision number
260
+ * `units_per_em` - Units per em
261
+
262
+ Vendor::
263
+ * `vendor_id` - Vendor/foundry ID
264
+
265
+
266
+ ==== Command-line usage
267
+
268
+ Syntax:
269
+
270
+ [source,shell]
271
+ ----
272
+ $ fontisan info FONT_FILE --brief [--format FORMAT]
273
+ ----
274
+
275
+ [source,shell]
276
+ ----
277
+ # Individual font
278
+ $ fontisan info font.ttf --brief
279
+ Font type: TrueType (Not Variable)
280
+ Family: Noto Sans
281
+ ...
282
+
283
+ # Collection
284
+ $ fontisan info fonts.ttc --brief
285
+ Collection: fonts.ttc
286
+ Fonts: 35
287
+
288
+ Font 0 (offset: 152):
289
+ Font type: OpenType (CFF) (Not Variable)
290
+ Family: Noto Serif CJK JP ExtraLight
291
+ ...
292
+ ----
293
+
294
+
295
+ .Brief mode with default text output
296
+ [example]
297
+ ====
298
+ [source,shell]
299
+ ----
300
+ $ fontisan info spec/fixtures/fonts/MonaSans/variable/MonaSans[wdth,wght].ttf --brief
301
+
302
+ Font type: TrueType (Variable)
303
+ Family: Mona Sans ExtraLight
304
+ Subfamily: Regular
305
+ Full name: Mona Sans ExtraLight
306
+ PostScript name: MonaSans-ExtraLight
307
+ Version: Version 2.001
308
+ Vendor ID: GTHB
309
+ Font revision: 2.00101
310
+ Units per em: 1000
311
+ ----
312
+ ====
313
+
314
+ .Brief mode with JSON output
315
+ [example]
316
+ ====
317
+ [source,shell]
318
+ ----
319
+ $ fontisan info font.ttf --brief --format json
320
+ ----
321
+
322
+ [source,json]
323
+ ----
324
+ {
325
+ "font_format": "truetype",
326
+ "is_variable": false,
327
+ "family_name": "Open Sans",
328
+ "subfamily_name": "Regular",
329
+ "full_name": "Open Sans Regular",
330
+ "postscript_name": "OpenSans-Regular",
331
+ "version": "Version 3.000",
332
+ "font_revision": 3.0,
333
+ "vendor_id": "2001",
334
+ "units_per_em": 2048
335
+ }
336
+ ----
337
+ ====
338
+
339
+
340
+ ==== Ruby API usage
341
+
342
+ .Basic brief info access
343
+ [example]
344
+ ====
345
+ [source,ruby]
346
+ ----
347
+ require 'fontisan'
348
+
349
+ info = Fontisan.info("font.ttf", brief: true)
350
+
351
+ # Access populated fields
352
+ puts info.family_name # "Open Sans"
353
+ puts info.postscript_name # "OpenSans-Regular"
354
+ puts info.is_variable # false
355
+
356
+ # Non-essential fields are nil
357
+ puts info.copyright # nil (not populated)
358
+ puts info.designer # nil (not populated)
359
+
360
+ # Serialize to YAML/JSON
361
+ puts info.to_yaml
362
+ puts info.to_json
363
+ ----
364
+ ====
365
+
366
+ .Brief info for font collections
367
+ [example]
368
+ ====
369
+ [source,ruby]
370
+ ----
371
+ require 'fontisan'
372
+
373
+ # Specify font index for TTC/OTC files
374
+ info = Fontisan.info("/path/to/fonts.ttc", brief: true, font_index: 0)
375
+ puts info.family_name
376
+ ----
377
+ ====
378
+
379
+ === Full mode
380
+
381
+ ==== General
382
+
383
+ In full mode, these additional attributes are populated (remain `nil` in brief
384
+ mode):
385
+
386
+ * `postscript_cid_name`, `preferred_family`, `preferred_subfamily`, `mac_font_menu_name`
387
+ * `unique_id`, `description`, `designer`, `designer_url`
388
+ * `manufacturer`, `vendor_url`, `trademark`, `copyright`
389
+ * `license_description`, `license_url`, `sample_text`, `permissions`
390
+
391
+ ==== Command-line usage
392
+
393
+ Syntax:
394
+
395
+ [source,shell]
396
+ ----
397
+ $ fontisan info FONT_FILE [--format FORMAT]
398
+ ----
399
+
400
+ .Font information for Libertinus Serif Regular
401
+ [example]
402
+ ====
403
+ [source,shell]
404
+ ----
405
+ $ fontisan info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
406
+
407
+ Font type: TrueType
408
+ Family: Libertinus Serif
409
+ Subfamily: Regular
410
+ Full name: Libertinus Serif Regular
411
+ PostScript name: LibertinusSerif-Regular
412
+ Version: Version 7.051;RELEASE
413
+ Unique ID: 5.000;QUE ;LibertinusSerif-Regular
414
+ Designer: Philipp H. Poll, Khaled Hosny
415
+ Manufacturer: Caleb Maclennan
416
+ Vendor URL: https://github.com/alerque/libertinus
417
+ Vendor ID: QUE
418
+ License Description: This Font Software is licensed under the SIL Open Font
419
+ License, Version 1.1. This license is available with a
420
+ FAQ at: https://openfontlicense.org
421
+ License URL: https://openfontlicense.org
422
+ Font revision: 7.05099
423
+ Permissions: Installable
424
+ Units per em: 1000
425
+ ----
426
+ ====
427
+
428
+
429
+ .Output in structured YAML format
430
+ [example]
431
+ ====
432
+ [source,shell]
433
+ ----
434
+ $ fontisan info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
435
+ ----
436
+
437
+ [source,yaml]
438
+ ----
439
+ font_format: truetype
440
+ is_variable: false
441
+ family_name: Libertinus Serif
442
+ subfamily_name: Regular
443
+ full_name: Libertinus Serif Regular
444
+ postscript_name: LibertinusSerif-Regular
445
+ version: Version 7.051;RELEASE
446
+ unique_id: 5.000;QUE ;LibertinusSerif-Regular
447
+ designer: Philipp H. Poll, Khaled Hosny
448
+ manufacturer: Caleb Maclennan
449
+ vendor_url: https://github.com/alerque/libertinus
450
+ vendor_id: QUE
451
+ license_description: 'This Font Software is licensed under the SIL Open Font License,
452
+ Version 1.1. This license is available with a FAQ at: https://openfontlicense.org'
453
+ license_url: https://openfontlicense.org
454
+ font_revision: 7.050994873046875
455
+ permissions: Installable
456
+ units_per_em: 1000
457
+ ----
458
+ ====
459
+
460
+
461
+
462
+
463
+ == List OpenType tables
464
+
465
+ === General
466
+
467
+ To understanding font structure and verifying table integrity, Fontisan provides
468
+ detailed table listings.
469
+
470
+ Display the font's table directory, showing all OpenType tables with their
471
+ sizes, offsets, and checksums.
472
+
473
+ === Command-line usage
474
+
475
+ Syntax:
476
+
477
+ [source,shell]
478
+ ----
479
+ $ fontisan tables FONT_FILE [--format FORMAT]
480
+ ----
481
+
482
+ Where,
483
+
484
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
485
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
486
+
487
+ .List of OpenType tables in Libertinus Serif Regular
488
+ [example]
489
+ ====
490
+ [source,shell]
491
+ ----
492
+ $ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
493
+ ----
494
+
495
+ [source,text]
496
+ ----
497
+ SFNT Version: TrueType (0x00010000)
498
+ Number of tables: 16
499
+
500
+ Tables:
501
+ GDEF 834 bytes (offset: 542156, checksum: 0x429C5C0C)
502
+ GPOS 17870 bytes (offset: 542992, checksum: 0x29CE4200)
503
+ OS/2 96 bytes (offset: 392, checksum: 0x4830F1C3)
504
+ cmap 3620 bytes (offset: 11412, checksum: 0x03AD3899)
505
+ cvt 248 bytes (offset: 18868, checksum: 0x3098127E)
506
+ fpgm 3596 bytes (offset: 15032, checksum: 0x622F0781)
507
+ gasp 8 bytes (offset: 542148, checksum: 0x00000010)
508
+ glyf 484900 bytes (offset: 30044, checksum: 0x0FF34594)
509
+ head 54 bytes (offset: 268, checksum: 0x18F5BDD0)
510
+ hhea 36 bytes (offset: 324, checksum: 0x191E2264)
511
+ hmtx 10924 bytes (offset: 488, checksum: 0x1F9D892B)
512
+ loca 10928 bytes (offset: 19116, checksum: 0x230B1A58)
513
+ maxp 32 bytes (offset: 360, checksum: 0x0EF919E7)
514
+ name 894 bytes (offset: 514944, checksum: 0x4E9173E6)
515
+ post 26308 bytes (offset: 515840, checksum: 0xE3D70231)
516
+ prep 239 bytes (offset: 18628, checksum: 0x8B4AB356)
517
+ ----
518
+ ====
519
+
520
+ .Output in structured YAML format
521
+ [example]
522
+ ====
523
+ [source,shell]
524
+ ----
525
+ $ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
526
+ ----
527
+
528
+ [source,yaml]
529
+ ----
530
+ ---
531
+ sfnt_version: TrueType (0x00010000)
532
+ num_tables: 16
533
+ tables:
534
+ - tag: GDEF
535
+ length: 834
536
+ offset: 542156
537
+ checksum: 1117543436
538
+ - tag: GPOS
539
+ length: 17870
540
+ offset: 542992
541
+ checksum: 701383168
542
+ ...
543
+ ----
544
+ ====
545
+
546
+
547
+ == List glyph names
548
+
549
+ === General
550
+
551
+ Show all glyph names defined in the font's post table. Each glyph is listed with
552
+ its index and name, useful for understanding the font's character coverage.
553
+
554
+ === Command-line usage
555
+
556
+ Syntax:
557
+
558
+ [source,shell]
559
+ ----
560
+ $ fontisan glyphs FONT_FILE [--format FORMAT]
561
+ ----
562
+
563
+ Where,
564
+
565
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
566
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
567
+
568
+
569
+ .List of glyph names in Libertinus Serif Regular
570
+ [example]
571
+ ====
572
+ [source,shell]
573
+ ----
574
+ $ fontisan glyphs spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
575
+ ----
576
+
577
+ [source,text]
578
+ ----
579
+ Glyph count: 2731
580
+ Source: post-2.0
581
+
582
+ Glyph names:
583
+ 0 .notdef
584
+ 1 space
585
+ 2 exclam
586
+ 3 quotedbl
587
+ 4 numbersign
588
+ 5 dollar
589
+ 6 percent
590
+ 7 ampersand
591
+ 8 quotesingle
592
+ 9 parenleft
593
+ 10 parenright
594
+ 11 asterisk
595
+ 12 plus
596
+ 13 comma
597
+ 14 hyphen
598
+ 15 period
599
+ 16 slash
600
+ 17 zero
601
+ 18 one
602
+ 19 two
603
+ 20 three
604
+ ...
605
+ ----
606
+ ====
607
+
608
+
609
+ == Show Unicode mappings
610
+
611
+ === General
612
+
613
+ Display Unicode codepoint to glyph index mappings from the cmap table. Shows
614
+ which glyphs are assigned to which Unicode characters.
615
+
616
+ === Command-line usage
617
+ Syntax:
618
+
619
+ [source,shell]
620
+ ----
621
+ $ fontisan unicode FONT_FILE [--format FORMAT]
622
+ ----
623
+
624
+ Where:
625
+
626
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
627
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
628
+
629
+
630
+ .Unicode to glyph mappings in Libertinus Serif Regular
631
+ [example]
632
+ ====
633
+ [source,shell]
634
+ ----
635
+ $ fontisan unicode spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
636
+ ----
637
+
638
+ [source,text]
639
+ ----
640
+ Unicode mappings: 2382
641
+
642
+ U+0020 glyph 1 space
643
+ U+0021 glyph 2 exclam
644
+ U+0022 glyph 3 quotedbl
645
+ U+0023 glyph 4 numbersign
646
+ U+0024 glyph 5 dollar
647
+ U+0025 glyph 6 percent
648
+ U+0026 glyph 7 ampersand
649
+ U+0027 glyph 8 quotesingle
650
+ U+0028 glyph 9 parenleft
651
+ U+0029 glyph 10 parenright
652
+ U+002A glyph 11 asterisk
653
+ U+002B glyph 12 plus
654
+ U+002C glyph 13 comma
655
+ U+002D glyph 14 hyphen
656
+ U+002E glyph 15 period
657
+ U+002F glyph 16 slash
658
+ U+0030 glyph 17 zero
659
+ U+0031 glyph 18 one
660
+ ...
661
+ ----
662
+ ====
663
+
664
+
665
+ == Variable font information
666
+
667
+ === General
668
+
669
+ Display variation axes and named instances for variable fonts. Shows the design
670
+ space and predefined styles available in the font.
671
+
672
+ === Command-line usage
673
+
674
+ Syntax:
675
+
676
+ [source,shell]
677
+ ----
678
+ $ fontisan variable FONT_FILE [--format FORMAT]
679
+ ----
680
+
681
+ Where,
682
+
683
+ `FONT_FILE`:: Path to the variable font file
684
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
685
+
686
+
687
+ .Variable font axes and instances in Mona Sans
688
+ [example]
689
+ ====
690
+ [source,shell]
691
+ ----
692
+ $ fontisan variable spec/fixtures/fonts/MonaSans/variable/MonaSans[wdth,wght].ttf
693
+ ----
694
+
695
+ [source,text]
696
+ ----
697
+ Axis 0: wdth
698
+ Axis 0 name: Width
699
+ Axis 0 range: 75 125
700
+ Axis 0 default: 100
701
+ Axis 1: wght
702
+ Axis 1 name: Weight
703
+ Axis 1 range: 200 900
704
+ Axis 1 default: 400
705
+ Instance 0 name: Mona Sans Narrow Thin
706
+ Instance 0 position: 75 200
707
+ Instance 1 name: Mona Sans Narrow ExtraLight
708
+ Instance 1 position: 75 250
709
+ Instance 2 name: Mona Sans Narrow Light
710
+ Instance 2 position: 75 300
711
+ ...
712
+ ----
713
+ ====
714
+
715
+
716
+ == Generate static instances from variable fonts
717
+
718
+ === General
719
+
720
+ Generate static font instances from variable fonts at specific variation
721
+ coordinates and output in any supported format (TTF, OTF, WOFF).
722
+
723
+ === Command-line usage
724
+
725
+ Syntax:
726
+
727
+ [source,shell]
728
+ ----
729
+ $ fontisan instance VARIABLE_FONT [OPTIONS]
730
+ ----
731
+
732
+ Where,
733
+
734
+ `VARIABLE_FONT`:: Path to the variable font file
735
+ `OPTIONS`:: Instance generation options
736
+
737
+ Options:
738
+
739
+ `--wght VALUE`:: Weight axis value
740
+ `--wdth VALUE`:: Width axis value
741
+ `--slnt VALUE`:: Slant axis value
742
+ `--ital VALUE`:: Italic axis value
743
+ `--opsz VALUE`:: Optical size axis value
744
+ `--to FORMAT`:: Output format: `ttf` (default), `otf`, `woff`, or `woff2`
745
+ `--output FILE`:: Output file path
746
+ `--optimize`:: Enable CFF optimization for OTF output
747
+ `--named-instance INDEX`:: Use named instance by index
748
+ `--list-instances`:: List available named instances
749
+ `--validate`:: Validate font before generation
750
+ `--dry-run`:: Preview instance without generating
751
+ `--progress`:: Show progress during generation
752
+
753
+
754
+ .Generate bold instance at wght=700
755
+ [example]
756
+ ====
757
+ [source,shell]
758
+ ----
759
+ $ fontisan instance variable.ttf --wght 700 --output bold.ttf
760
+
761
+ Generating instance... done
762
+ Writing output... done
763
+ Static font instance written to: bold.ttf
764
+ ----
765
+ ====
766
+
767
+ .Generate instance and convert to OTF
768
+ [example]
769
+ ====
770
+ [source,shell]
771
+ ----
772
+ $ fontisan instance variable.ttf --wght 300 --to otf --output light.otf
773
+
774
+ Generating instance... done
775
+ Writing output... done
776
+ Static font instance written to: light.otf
777
+ ----
778
+ ====
779
+
780
+ .Generate instance and convert to WOFF
781
+ [example]
782
+ ====
783
+ [source,shell]
784
+ ----
785
+ $ fontisan instance variable.ttf --wght 600 --to woff --output semibold.woff
786
+
787
+ Generating instance... done
788
+ Writing output... done
789
+ Static font instance written to: semibold.woff
790
+ ----
791
+ ====
792
+
793
+ .Generate instance with multiple axes
794
+ [example]
795
+ ====
796
+ [source,shell]
797
+ ----
798
+ $ fontisan instance variable.ttf --wght 600 --wdth 75 --output condensed.ttf
799
+
800
+ Generating instance... done
801
+ Writing output... done
802
+ Static font instance written to: condensed.ttf
803
+ ----
804
+ ====
805
+
806
+ .List available named instances
807
+ [example]
808
+ ====
809
+ [source,shell]
810
+ ----
811
+ $ fontisan instance variable.ttf --list-instances
812
+
813
+ Available named instances:
814
+
815
+ [0] Instance 4
816
+ Coordinates:
817
+ wdth: 75.0
818
+ wght: 200.0
819
+
820
+ [1] Instance 5
821
+ Coordinates:
822
+ wdth: 75.0
823
+ wght: 250.0
824
+
825
+ [2] Instance 6
826
+ Coordinates:
827
+ wdth: 75.0
828
+ wght: 300.0
829
+ ----
830
+ ====
831
+
832
+ .Use named instance
833
+ [example]
834
+ ====
835
+ [source,shell]
836
+ ----
837
+ $ fontisan instance variable.ttf --named-instance 0 --output thin.ttf
838
+ ----
839
+ ====
840
+
841
+ .Preview instance generation (dry-run)
842
+ [example]
843
+ ====
844
+ [source,shell]
845
+ ----
846
+ $ fontisan instance variable.ttf --wght 700 --dry-run
847
+
848
+ Dry-run mode: Preview of instance generation
849
+
850
+ Coordinates:
851
+ wght: 700.0
852
+
853
+ Output file: variable-instance.ttf
854
+ Format: same as input
855
+
856
+ Use without --dry-run to actually generate the instance.
857
+ ----
858
+ ====
859
+
860
+
861
+ == Optical size information
862
+
863
+ === General
864
+
865
+ Display optical size range from the OS/2 table for fonts designed for specific
866
+ point sizes.
867
+
868
+ === Command-line usage
869
+
870
+ Syntax:
871
+
872
+ [source,shell]
873
+ ----
874
+ $ fontisan optical-size FONT_FILE [--format FORMAT]
875
+ ----
876
+
877
+ Where,
878
+
879
+ `FONT_FILE`:: Path to the font file with optical sizing
880
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
881
+
882
+
883
+ .Optical size information in Libertinus Serif Display
884
+ [example]
885
+ ====
886
+ [source,shell]
887
+ ----
888
+ $ fontisan optical-size spec/fixtures/fonts/libertinus/ttf/LibertinusSerifDisplay-Regular.ttf
889
+ ----
890
+
891
+ [source,text]
892
+ ----
893
+ Size range: [18, 72) pt (source: OS/2_usLowerOpticalPointSize)
894
+ ----
895
+ ====
896
+
897
+
898
+ == List supported scripts
899
+
900
+ === General
901
+
902
+ Show all scripts (writing systems) supported by the font, extracted from GSUB
903
+ and GPOS tables. Useful for understanding language coverage.
904
+
905
+ === Command-line usage
906
+
907
+ Syntax:
908
+
909
+ [source,shell]
910
+ ----
911
+ $ fontisan scripts FONT_FILE [--format FORMAT]
912
+ ----
913
+
914
+ Where,
915
+
916
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
917
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
918
+
919
+
920
+ .Supported scripts in Libertinus Serif Regular
921
+ [example]
922
+ ====
923
+ [source,shell]
924
+ ----
925
+ $ fontisan scripts spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
926
+ ----
927
+
928
+ [source,text]
929
+ ----
930
+ Script count: 5
931
+
932
+ DFLT Default
933
+ cyrl Cyrillic
934
+ grek Greek
935
+ hebr Hebrew
936
+ latn Latin
937
+ ----
938
+ ====
939
+
940
+
941
+ == List OpenType features
942
+
943
+ === General
944
+
945
+ Show OpenType layout features (typography features like ligatures, kerning,
946
+ small capitals) available for specific scripts or all scripts.
947
+
948
+ === Command-line usage
949
+
950
+ Syntax:
951
+
952
+ [source,shell]
953
+ ----
954
+ $ fontisan features FONT_FILE [--script SCRIPT] [--format FORMAT]
955
+ ----
956
+
957
+ Where,
958
+
959
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
960
+ `SCRIPT`:: Optional 4-character script tag (e.g., `latn`, `cyrl`, `arab`). If not specified, shows features for all scripts
961
+ `FORMAT`:: Output format: `text` (default), `json`, or `yaml`
962
+
963
+
964
+ .OpenType features for Latin script
965
+ [example]
966
+ ====
967
+ [source,shell]
968
+ ----
969
+ $ fontisan features spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --script latn
970
+ ----
971
+
972
+ [source,text]
973
+ ----
974
+ Script: latn
975
+ Feature count: 4
976
+
977
+ cpsp Capital Spacing
978
+ kern Kerning
979
+ mark Mark Positioning
980
+ mkmk Mark to Mark Positioning
981
+ ----
982
+ ====
983
+
984
+
985
+ .OpenType features for all scripts
986
+ [example]
987
+ ====
988
+ [source,shell]
989
+ ----
990
+ $ fontisan features spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
991
+ ----
992
+
993
+ [source,text]
994
+ ----
995
+ Script: DFLT
996
+ Feature count: 4
997
+
998
+ cpsp Capital Spacing
999
+ kern Kerning
1000
+ mark Mark Positioning
1001
+ mkmk Mark to Mark Positioning
1002
+
1003
+ Script: cyrl
1004
+ Feature count: 4
1005
+
1006
+ cpsp Capital Spacing
1007
+ kern Kerning
1008
+ mark Mark Positioning
1009
+ mkmk Mark to Mark Positioning
1010
+
1011
+ Script: grek
1012
+ Feature count: 4
1013
+
1014
+ cpsp Capital Spacing
1015
+ kern Kerning
1016
+ mark Mark Positioning
1017
+ mkmk Mark to Mark Positioning
1018
+
1019
+ Script: hebr
1020
+ Feature count: 2
1021
+
1022
+ mark Mark Positioning
1023
+ mkmk Mark to Mark Positioning
1024
+
1025
+ Script: latn
1026
+ Feature count: 4
1027
+
1028
+ cpsp Capital Spacing
1029
+ kern Kerning
1030
+ mark Mark Positioning
1031
+ mkmk Mark to Mark Positioning
1032
+ ----
1033
+ ====
1034
+
1035
+
1036
+ == Dump raw table data
1037
+
1038
+ === General
1039
+
1040
+ Extract raw binary data from a specific OpenType table. Useful for detailed
1041
+ analysis or debugging font issues.
1042
+
1043
+ === Command-line usage
1044
+
1045
+ TODO: should support output to file directly with `--output FILE`.
1046
+
1047
+ Syntax:
1048
+
1049
+ [source,shell]
1050
+ ----
1051
+ $ fontisan dump-table FONT_FILE TABLE_TAG
1052
+ ----
1053
+
1054
+ Where,
1055
+
1056
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
1057
+ `TABLE_TAG`:: Four-character table tag (e.g., `name`, `head`, `GSUB`, `GPOS`)
1058
+
1059
+
1060
+ .Dump raw table data to files
1061
+ [example]
1062
+ ====
1063
+ [source,shell]
1064
+ ----
1065
+ $ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf name > name_table.bin
1066
+ $ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf GPOS > gpos_table.bin
1067
+ $ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf head > head_table.bin
1068
+ ----
1069
+
1070
+ The output is binary data written directly to stdout, which can be redirected to
1071
+ a file for further analysis.
1072
+ ====
1073
+
1074
+
1075
+ == Export font structure
1076
+
1077
+ === General
1078
+
1079
+ Export font structure to TTX (FontTools XML), YAML, or JSON formats for
1080
+ analysis, interchange, or version control. Supports selective table export and
1081
+ configurable binary data encoding.
1082
+
1083
+ === Command-line usage
1084
+
1085
+ Syntax:
1086
+
1087
+ [source,shell]
1088
+ ----
1089
+ $ fontisan export FONT_FILE [--output FILE] [--format FORMAT] [--tables TABLES] [--binary-format FORMAT]
1090
+ ----
1091
+
1092
+ Where,
1093
+
1094
+ `FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTC, dfont)
1095
+ `--output FILE`:: Output file path (default: stdout)
1096
+ `--format FORMAT`:: Export format: `yaml` (default), `json`, or `ttx`
1097
+ `--tables TABLES`:: Specific tables to export (space-separated list)
1098
+ `--binary-format FORMAT`:: Binary encoding: `hex` (default) or `base64`
1099
+
1100
+
1101
+ .Export font to YAML format
1102
+ [example]
1103
+ ====
1104
+ [source,shell]
1105
+ ----
1106
+ $ fontisan export spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --output font.yaml
1107
+
1108
+ # Output: font.yaml with complete font structure in YAML
1109
+ ----
1110
+ ====
1111
+
1112
+ .Export specific tables to TTX format
1113
+ [example]
1114
+ ====
1115
+ [source,shell]
1116
+ ----
1117
+ $ fontisan export spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf \
1118
+ --format ttx --tables head hhea maxp name --output font.ttx
1119
+ ----
1120
+
1121
+ Exports only the specified tables in FontTools TTX XML format for compatibility
1122
+ with fonttools.
1123
+ ====
1124
+
1125
+ .Export to JSON with base64 binary encoding
1126
+ [example]
1127
+ ====
1128
+ [source,shell]
1129
+ ----
1130
+ $ fontisan export font.ttf --format json --binary-format base64 --output font.json
1131
+ ----
1132
+
1133
+ Uses base64 encoding for binary data instead of hexadecimal, useful for
1134
+ JSON-based workflows.
1135
+ ====
1136
+
1137
+ == Font validation
1138
+
1139
+ === General
1140
+
1141
+ Fontisan provides validation functionality to ensure font quality, structural
1142
+ integrity, and compliance with various standards.
1143
+
1144
+ The validation framework allows developers to create custom validators using a
1145
+ declarative DSL. Validators can perform checks on font tables, fields,
1146
+ structures, usability, instructions, and glyphs.
1147
+
1148
+ === Predefined profiles
1149
+
1150
+ Fontisan includes validation profiles for different use cases:
1151
+
1152
+ `indexability`:: Fast font discovery and indexing (~5x faster, 8 checks, metadata-only)
1153
+
1154
+ `usability`:: Font installation compatibility (26 checks, macOS Font Book focused)
1155
+
1156
+ `production`:: Comprehensive production quality (36 checks, OpenType spec compliance - default)
1157
+
1158
+ `web`:: Web font embedding readiness (18 checks for web deployment)
1159
+
1160
+ `spec_compliance`:: Full OpenType specification compliance (detailed analysis mode)
1161
+
1162
+ `default`:: Alias for the production profile
1163
+
1164
+
1165
+ === Command-line usage
1166
+
1167
+ ==== Validate a font file against a predefined profile
1168
+
1169
+ .Validate with default profile
1170
+ [example]
1171
+ ====
1172
+ [source,shell]
1173
+ ----
1174
+ $ fontisan validate font.ttf
1175
+ ----
1176
+ ====
1177
+
1178
+ .Validate for web use
1179
+ [example]
1180
+ ====
1181
+ [source,shell]
1182
+ ----
1183
+ $ fontisan validate font.ttf -t web
1184
+ ----
1185
+ ====
1186
+
1187
+ .List available profiles
1188
+ [example]
1189
+ ====
1190
+ [source,shell]
1191
+ ----
1192
+ $ fontisan validate --list
1193
+ Available validation profiles:
1194
+ indexability - Fast validation for font discovery and indexing
1195
+ usability - Basic usability for installation
1196
+ production - Comprehensive quality checks
1197
+ web - Web embedding and optimization
1198
+ spec_compliance - Full OpenType spec compliance
1199
+ default - Default validation profile (alias for production)
1200
+ ----
1201
+ ====
1202
+
1203
+ .Full report to file
1204
+ [example]
1205
+ ====
1206
+ [source,shell]
1207
+ ----
1208
+ $ fontisan validate font.ttf -t production -r -o report.txt
1209
+ ----
1210
+ ====
1211
+
1212
+ .Summary with return value
1213
+ [example]
1214
+ ====
1215
+ [source,shell]
1216
+ ----
1217
+ $ fontisan validate font.ttf -S -R
1218
+ 0 errors, 2 warnings, 0 info
1219
+ $ echo $?
1220
+ 4 # Exit code 4 indicates warnings found
1221
+ ----
1222
+ ====
1223
+
1224
+ .Table format output
1225
+ [example]
1226
+ ====
1227
+ [source,shell]
1228
+ ----
1229
+ $ fontisan validate font.ttf -T
1230
+ CHECK_ID | STATUS | SEVERITY | TABLE
1231
+ ------------------------------------------------------------
1232
+ required_tables | PASS | error | N/A
1233
+ name_version | PASS | error | name
1234
+ family_name | PASS | error | name
1235
+ ...
1236
+ ----
1237
+ ====
1238
+
1239
+ ==== CLI options
1240
+
1241
+ -t, --test-list PROFILE:: Select validation profile (indexability, usability,
1242
+ production, web, spec_compliance, default)
1243
+
1244
+ -l, --list:: List available validation profiles
1245
+
1246
+ -o, --output FILE:: Write report to file instead of stdout
1247
+
1248
+ -r, --full-report:: Generate full detailed report
1249
+
1250
+ -R, --return-value-results:: Use return value to indicate results (0=none,
1251
+ 1=error, 2=fatal, 3=major, 4=minor, 5=info)
1252
+
1253
+ -S, --summary-report:: Generate brief summary report
1254
+
1255
+ -T, --table-report:: Generate tabular format report
1256
+
1257
+ -v, --verbose:: Enable verbose output
1258
+
1259
+ -w, --suppress-warnings:: Suppress warning output
1260
+
1261
+ -e, --exclude CHECKS:: Exclude specific checks (comma-separated list)
1262
+
1263
+ === Collection validation
1264
+
1265
+ The `validate` command automatically detects and validates font collections (TTC, OTC, dfont).
1266
+ When validating a collection, fontisan validates all fonts in the collection and displays
1267
+ per-font results with an overall summary.
1268
+
1269
+ .Validation profiles with collections
1270
+ [example]
1271
+ ====
1272
+ All validation profiles work with font collections. The selected profile determines:
1273
+
1274
+ * **Which tables are loaded** - metadata vs full mode
1275
+ * **Which checks are performed** - number and type of validations
1276
+ * **Performance characteristics** - indexability is ~5x faster than production
1277
+
1278
+ For large collections (CJK fonts with 30+ fonts), use the `indexability` profile for fast
1279
+ validation when scanning for font discovery, or `production` for comprehensive quality
1280
+ checks.
1281
+
1282
+ [source,shell]
1283
+ ----
1284
+ # Quick validation for indexing (metadata mode, 8 checks, ~5x faster)
1285
+ $ fontisan validate /path/to/font.ttc -t indexability
1286
+
1287
+ # Comprehensive validation (full mode, 37 checks)
1288
+ $ fontisan validate /path/to/font.ttc -t production
1289
+
1290
+ # Web font readiness validation
1291
+ $ fontisan validate /path/to/font.ttc -t web
1292
+ ----
1293
+
1294
+ The collection validation output includes:
1295
+
1296
+ * *Collection header* - Path, type, and number of fonts
1297
+ * *Summary* - Total errors, warnings, and info across all fonts
1298
+ * *Per-font sections* - Individual validation results for each font with:
1299
+ ** Font index and name
1300
+ ** Font path in `collection.ttc:index` format
1301
+ ** Individual font status (VALID/INVALID/VALID_WITH_WARNINGS)
1302
+ ** Font-specific errors and warnings
1303
+ ** Exit codes* - For collections, uses the "worst" status across all fonts:
1304
+ ** 0 = All fonts valid
1305
+ ** 2 = Any font has fatal errors
1306
+ ** 3 = Any font has errors (and no fatal)
1307
+ ** 4 = Any font has warnings (and no errors)
1308
+ ** 5 = Any font has info issues (and no errors or warnings)
1309
+ ====
1310
+
1311
+ .Validate a font collection
1312
+ [example]
1313
+ ====
1314
+ [source,shell]
1315
+ ----
1316
+ $ fontisan validate /path/to/font.ttc
1317
+ Collection: /path/to/font.ttc
1318
+ Type: TTC
1319
+ Fonts: 4
1320
+
1321
+ Summary:
1322
+ Total Errors: 14
1323
+ Total Warnings: 8
1324
+ Total Info: 0
1325
+
1326
+ === Font 0: Lucida Grande ===
1327
+ Font: /path/to/font.ttc:0
1328
+ Status: INVALID
1329
+ ...
1330
+
1331
+ === Font 1: Lucida Grande Bold ===
1332
+ Font: /path/to/font.ttc:1
1333
+ Status: INVALID
1334
+ ...
1335
+ ----
1336
+ ====
1337
+
1338
+ === Collection structural validation (`validate-collection`)
1339
+
1340
+ For collection-level structural checks (face count, per-face glyph cap,
1341
+ optional cmap-union size) without running the full per-face profile
1342
+ machinery, use the dedicated `validate-collection` command:
1343
+
1344
+ [source,shell]
1345
+ ----
1346
+ # Glyph-cap-only check (default)
1347
+ fontisan validate-collection family.ttc
1348
+
1349
+ # Require exactly 5 faces
1350
+ fontisan validate-collection family.ttc --expected-faces 5
1351
+
1352
+ # Tighter per-face glyph cap + minimum cmap coverage
1353
+ fontisan validate-collection family.ttc \
1354
+ --max-glyphs 60000 \
1355
+ --expected-cmap-union 100000
1356
+ ----
1357
+
1358
+ Exit code is `0` when every requested check passes, `1` when any
1359
+ check fails. With no options, only the per-face glyph cap is checked
1360
+ (default `65,535`).
1361
+
1362
+ This command is intentionally separate from `fontisan validate PATH`
1363
+ (MECE): `validate` runs profile-based per-face checks;
1364
+ `validate-collection` runs collection-level structural checks. They
1365
+ do not share a subcommand tree.
1366
+
1367
+ For programmatic access to the same metadata, see
1368
+ `Fontisan::Collection::Reader` — the read-only counterpart to
1369
+ `Collection::Builder`. It opens a TTC/OTC/dfont and exposes
1370
+ `face_count`, per-face `stats` (glyph/codepoint counts), and the
1371
+ cmap union across all faces, without hand-rolling the TTC header
1372
+ bytes.
1373
+
1374
+ === Ruby API usage
1375
+
1376
+ ==== Architecture
1377
+
1378
+ The validation framework in Ruby consists of:
1379
+
1380
+ DSL base class:: `Fontisan::Validators::Validator` provides a declarative syntax
1381
+ for defining validation checks
1382
+
1383
+ Table validation helpers::
1384
+ 56 helper methods across 8 core OpenType tables (name, head, maxp, hhea, glyf,
1385
+ cmap, post, OS/2) that perform specific validation checks
1386
+
1387
+ ValidationReport::
1388
+ Structured reports with individual check results, severity levels, and
1389
+ comprehensive issue tracking
1390
+
1391
+ ==== Using predefined profiles
1392
+
1393
+ .Validate with Ruby API
1394
+ [example]
1395
+ ====
1396
+ [source,ruby]
1397
+ ----
1398
+ require 'fontisan'
1399
+
1400
+ # Validate with default profile (production)
1401
+ report = Fontisan.validate('font.ttf')
1402
+ puts report.valid? # => true or false
1403
+
1404
+ # Validate with specific profile
1405
+ report = Fontisan.validate('font.ttf', profile: :web)
1406
+ puts "Errors: #{report.summary.errors}"
1407
+ puts "Warnings: #{report.summary.warnings}"
1408
+
1409
+ # Check validation status
1410
+ if report.valid?
1411
+ puts "Font is valid for web use!"
1412
+ else
1413
+ puts "Font has #{report.summary.errors} errors"
1414
+ end
1415
+ ----
1416
+ ====
1417
+
1418
+ .Query validation results
1419
+ [example]
1420
+ ====
1421
+ [source,ruby]
1422
+ ----
1423
+ report = Fontisan.validate('font.ttf', profile: :production)
1424
+
1425
+ # Get issues by severity
1426
+ fatal_issues = report.fatal_errors
1427
+ error_issues = report.errors_only
1428
+ warning_issues = report.warnings_only
1429
+ info_issues = report.info_only
1430
+
1431
+ # Get issues by category
1432
+ table_issues = report.issues_by_category('table_validation')
1433
+
1434
+ # Get check results
1435
+ failed_ids = report.failed_check_ids
1436
+ pass_rate = report.pass_rate
1437
+
1438
+ # Export to different formats
1439
+ yaml_output = report.to_yaml
1440
+ json_output = report.to_json
1441
+ summary = report.to_summary # "2 errors, 3 warnings, 0 info"
1442
+ ----
1443
+ ====
1444
+
1445
+ .Use validators directly
1446
+ [example]
1447
+ ====
1448
+ [source,ruby]
1449
+ ----
1450
+ require 'fontisan'
1451
+
1452
+ # Load font
1453
+ font = Fontisan::FontLoader.load('font.ttf')
1454
+
1455
+ # Use specific validator
1456
+ validator = Fontisan::Validators::OpenTypeValidator.new
1457
+ report = validator.validate(font)
1458
+
1459
+ # Check individual results
1460
+ name_check = report.result_of(:name_validation)
1461
+ puts name_check.passed?
1462
+ puts name_check.severity
1463
+ ----
1464
+ ====
1465
+
1466
+ ==== Using custom validators
1467
+
1468
+ ===== General
1469
+
1470
+ Custom validators inherit from `Fontisan::Validators::Validator` and define
1471
+ validation logic using the DSL.
1472
+
1473
+ The DSL provides 6 check methods for different validation types:
1474
+
1475
+ * `check_table` - Validate table-level properties
1476
+ * `check_field` - Validate specific field values
1477
+ * `check_structure` - Validate font structure and relationships
1478
+ * `check_usability` - Validate usability and best practices
1479
+ * `check_instructions` - Validate TrueType instructions/hinting
1480
+ * `check_glyphs` - Validate individual glyphs
1481
+
1482
+ Each check receives a unique ID, severity level (:info, :warning, :error,
1483
+ :fatal), and a validation block.
1484
+
1485
+ .Creating a custom validator
1486
+ [example]
1487
+ ====
1488
+ [source,ruby]
1489
+ ----
1490
+ require 'fontisan/validators/validator'
1491
+
1492
+ # Define a custom validator
1493
+ class MyFontValidator < Fontisan::Validators::Validator
1494
+ private
1495
+
1496
+ def define_checks
1497
+ # Check name table
1498
+ check_table :name_validation, 'name', severity: :error do |table|
1499
+ table.valid_version? &&
1500
+ table.valid_encoding_heuristics? &&
1501
+ table.family_name_present? &&
1502
+ table.postscript_name_valid?
1503
+ end
1504
+
1505
+ # Check head table
1506
+ check_table :head_validation, 'head', severity: :error do |table|
1507
+ table.valid_magic? &&
1508
+ table.valid_version? &&
1509
+ table.valid_units_per_em? &&
1510
+ table.valid_bounding_box? &&
1511
+ table.valid_index_to_loc_format? &&
1512
+ table.valid_glyph_data_format?
1513
+ end
1514
+
1515
+ # Check structure
1516
+ check_structure :required_tables, severity: :error do |font|
1517
+ %w[name head maxp hhea].all? { |tag| !font.table(tag).nil? }
1518
+ end
1519
+ end
1520
+ end
1521
+
1522
+ # Use the validator
1523
+ font = Fontisan::FontLoader.load('font.ttf')
1524
+ validator = MyFontValidator.new
1525
+ report = validator.validate(font)
1526
+
1527
+ # Check validation results
1528
+ puts report.valid? # => true/false
1529
+ puts report.status # => "valid", "valid_with_warnings", "invalid"
1530
+ puts report.summary.errors # => number of errors
1531
+ puts report.summary.warnings # => number of warnings
1532
+
1533
+ # Query specific checks
1534
+ result = report.result_of(:name_validation)
1535
+ puts result.passed? # => true/false
1536
+ puts result.severity # => "error"
1537
+ puts result.messages # => array of messages
1538
+
1539
+ # Get all failed checks
1540
+ report.failed_checks.each do |check|
1541
+ puts "#{check.check_id}: #{check.messages.join(', ')}"
1542
+ end
1543
+
1544
+ # Serialize report
1545
+ puts report.to_yaml
1546
+ puts report.to_json
1547
+ ----
1548
+ ====
1549
+
1550
+
1551
+ .Using table validation helpers
1552
+ [example]
1553
+ ====
1554
+ [source,ruby]
1555
+ ----
1556
+ class ComprehensiveValidator < Fontisan::Validators::Validator
1557
+ private
1558
+
1559
+ def define_checks
1560
+ # Name table validation helpers
1561
+ check_table :name_validation, 'name', severity: :error do |table|
1562
+ table.valid_version? &&
1563
+ table.valid_encoding_heuristics? &&
1564
+ table.family_name_present? &&
1565
+ table.postscript_name_valid?
1566
+ end
1567
+
1568
+ # Head table validation helpers
1569
+ check_table :head_validation, 'head', severity: :error do |table|
1570
+ table.valid_magic? &&
1571
+ table.valid_version? &&
1572
+ table.valid_units_per_em? &&
1573
+ table.valid_bounding_box? &&
1574
+ table.valid_index_to_loc_format? &&
1575
+ table.valid_glyph_data_format?
1576
+ end
1577
+
1578
+ # Maxp table validation helpers
1579
+ check_table :maxp_validation, 'maxp', severity: :error do |table|
1580
+ table.valid_version? &&
1581
+ table.valid_num_glyphs? &&
1582
+ table.valid_max_zones? &&
1583
+ table.has_truetype_metrics? &&
1584
+ table.reasonable_metrics?
1585
+ end
1586
+ end
1587
+ end
1588
+ ----
1589
+ ====
1590
+
1591
+ .Handling validation results
1592
+ [example]
1593
+ ====
1594
+ [source,ruby]
1595
+ ----
1596
+ validator = MyFontValidator.new
1597
+ report = validator.validate(font)
1598
+
1599
+ # Overall validation status
1600
+ if report.valid?
1601
+ puts "Font is valid!"
1602
+ else
1603
+ puts "Font has issues:"
1604
+
1605
+ # Show errors
1606
+ report.errors.each do |error|
1607
+ puts " [ERROR] #{error.category}: #{error.message}"
1608
+ puts " Location: #{error.location}" if error.location
1609
+ end
1610
+
1611
+ # Show warnings
1612
+ report.warnings.each do |warning|
1613
+ puts " [WARN] #{warning.category}: #{warning.message}"
1614
+ end
1615
+ end
1616
+
1617
+ # Check specific validation results
1618
+ if report.result_of(:name_validation)&.passed?
1619
+ puts "Name table version is valid"
1620
+ else
1621
+ puts "Name table version check failed"
1622
+ end
1623
+
1624
+ # Get summary statistics
1625
+ puts "\nValidation Summary:"
1626
+ puts " Total checks: #{report.check_results.count}"
1627
+ puts " Passed: #{report.passed_checks.count}"
1628
+ puts " Failed: #{report.failed_checks.count}"
1629
+ puts " Errors: #{report.summary.errors}"
1630
+ puts " Warnings: #{report.summary.warnings}"
1631
+ puts " Info: #{report.summary.info}"
1632
+ ----
1633
+ ====
1634
+
1635
+ ==== Validation helpers
1636
+
1637
+ ===== General
1638
+
1639
+ The validation framework provides 56 helper methods across 8 core OpenType
1640
+ tables. Each helper returns a boolean indicating whether the validation passed.
1641
+
1642
+ Name table:
1643
+
1644
+ * `valid_version?` - Check if version is 0 or 1
1645
+ * `valid_encoding_heuristics?` - Check platform/encoding combinations
1646
+ * `has_valid_platform_combos?` - Check for required platform combinations
1647
+ * `family_name_present?` - Check if family name exists and is non-empty
1648
+ * `postscript_name_present?` - Check if PostScript name exists and is non-empty
1649
+ * `postscript_name_valid?` - Check if PostScript name matches required pattern
1650
+
1651
+ Head table:
1652
+
1653
+ * `valid_magic?` - Check magic number (0x5F0F3CF5)
1654
+ * `valid_version?` - Check version is 1.0
1655
+ * `valid_units_per_em?` - Check units per em is valid (16-16384)
1656
+ * `valid_bounding_box?` - Check bounding box coordinates
1657
+ * `valid_index_to_loc_format?` - Check format is 0 or 1
1658
+ * `valid_glyph_data_format?` - Check format is 0
1659
+
1660
+ Maxp Table:
1661
+
1662
+ * `valid_version?` - Check version is 0.5 or 1.0
1663
+ * `valid_num_glyphs?` - Check num glyphs >= 1
1664
+ * `valid_max_zones?` - Check maxZones is 1 or 2
1665
+ * `has_truetype_metrics?` - Check TrueType metrics are present
1666
+ * `reasonable_metrics?` - Check metrics are within reasonable bounds
1667
+
1668
+ Hhea Table:
1669
+
1670
+ * `valid_version?` - Check version is 1.0
1671
+ * `valid_metric_data_format?` - Check format is 0
1672
+ * `valid_number_of_h_metrics?` - Check count >= 1
1673
+ * `valid_ascent_descent?` - Check signs are correct
1674
+ * `valid_line_gap?` - Check line gap >= 0
1675
+ * `valid_advance_width_max?` - Check max width > 0
1676
+ * `valid_caret_slope?` - Check caret slope values
1677
+ * `valid_x_max_extent?` - Check extent > 0
1678
+
1679
+ Glyf Table:
1680
+
1681
+ * `has_empty_glyphs?` - Check for empty glyphs
1682
+ * `has_clipped_glyphs?` - Check for clipped glyphs
1683
+ * `has_instructions?` - Check for TrueType instructions
1684
+ * `contours_valid?` - Check contour counts
1685
+ * `glyphs_accessible?` - Check glyph accessibility
1686
+
1687
+ Cmap Table:
1688
+
1689
+ * `valid_version?` - Check version is 0
1690
+ * `has_valid_subtables?` - Check subtable validity
1691
+ * `has_unicode_mapping?` - Check for Unicode support
1692
+ * `has_valid_bmp_coverage?` - Check BMP coverage
1693
+ * `has_valid_format4?` - Check format 4 subtable
1694
+ * `glyph_indices_valid?` - Check glyph index validity
1695
+ * `supports_platform?` - Check platform support
1696
+
1697
+ Post Table:
1698
+
1699
+ * `valid_version?` - Check version (1.0, 2.0, 2.5, 3.0, 4.0)
1700
+ * `valid_italic_angle?` - Check italic angle range
1701
+ * `valid_underline_position?` - Check underline metrics
1702
+ * `valid_underline_thickness?` - Check underline thickness
1703
+ * `valid_is_fixed_pitch?` - Check fixed pitch flag
1704
+ * `has_glyph_names?` - Check for glyph names
1705
+
1706
+ OS/2 Table:
1707
+
1708
+ * `valid_version?` - Check version (0-5)
1709
+ * `valid_weight_class?` - Check weight class (100-900)
1710
+ * `valid_width_class?` - Check width class (1-9)
1711
+ * `valid_vendor_id?` - Check vendor ID format
1712
+ * `valid_typo_metrics?` - Check typographic metrics
1713
+ * `valid_win_metrics?` - Check Windows metrics
1714
+ * `valid_unicode_ranges?` - Check Unicode range bits
1715
+ * `has_valid_panose?` - Check PANOSE classification
1716
+ * `valid_selection_flags?` - Check style selection flags
1717
+ * `valid_first_char_index?` - Check first character index
1718
+ * `valid_last_char_index?` - Check last character index
1719
+ * `valid_typo_ascender?` - Check typographic ascender
1720
+ * `valid_typo_descender?` - Check typographic descender
1721
+
1722
+
1723
+ == Version information
1724
+
1725
+ === General
1726
+
1727
+ Display the Fontisan version.
1728
+
1729
+ === Command-line usage
1730
+
1731
+ [source,shell]
1732
+ ----
1733
+ fontisan version
1734
+ ----
1735
+
1736
+
1737
+ == Font containers and collections
1738
+
1739
+ === General
1740
+
1741
+ Fontisan provides comprehensive tools for managing font containers and
1742
+ collections. A font container is defined as a packaging format that can hold one
1743
+ or more font assets.
1744
+
1745
+ In general, Fontisan supports the following levels of font packaging:
1746
+
1747
+ Level 1:: Outline formats. This level defines the actual glyph outline data
1748
+ format for fonts.
1749
+
1750
+ TrueType::: Quadratic Bézier curves (glyf/loca tables)
1751
+ CFF::: Cubic Bézier curves (CFF table, PostScript outlines)
1752
+ CFF2::: Variable CFF with cubic curves (CFF2 table)
1753
+
1754
+ Level 2:: Curve and metadata container. This level defines the overall font
1755
+ file format that encapsulates outline data along with various metadata tables.
1756
+
1757
+ SFNT::: "Spine/Scalable font" defines the overall structure and directory system
1758
+ for a font file, which houses different "tables" containing specific data like
1759
+ glyph outlines, character maps, and kerning information.
1760
+
1761
+ TrueType (TTF)::: A specific implementation of the SFNT container that uses
1762
+ TrueType outlines.
1763
+
1764
+ OpenType (OTF)::: A more versatile SFNT container that can house either TrueType
1765
+ or CFF outlines, along with additional typographic features.
1766
+
1767
+ Web Open Font Format (WOFF and WOFF2)::: Compressed SFNT-based formats optimized
1768
+ for web delivery.
1769
+
1770
+ Level 3:: Individual font file, representing a single font asset packaged in a
1771
+ specific container format.
1772
+
1773
+ TTF `.ttf`::: A single font file in TrueType format
1774
+ OTF `.otf`::: A single font file in OpenType format
1775
+ WOFF `.woff`::: A single font file in Web Open Font Format 1.0 that is SFNT-based
1776
+ and uses zlib compression
1777
+ WOFF2 `.woff2`::: A single font file in Web Open Font Format 2.0 that is
1778
+ SFNT-based and uses Brotli compression
1779
+
1780
+ Level 4:: Font collections, which are container formats that can hold multiple
1781
+ font assets within a single file.
1782
+
1783
+ TTC (TrueType Collection):: Supported since OpenType 1.4. Contains fonts with
1784
+ TrueType outlines (glyf table). Multiple fonts can share identical tables for
1785
+ efficient storage. File extension: `.ttc`
1786
+
1787
+ OTC (OpenType Collection):: Supported since OpenType 1.8. Contains fonts with
1788
+ CFF-format outlines (CFF table). Provides the same storage benefits and
1789
+ glyph-count advantages as TTC but for CFF fonts. File extension: `.otc`
1790
+
1791
+ dfont (Apple suitcase)::: Apple proprietary format storing complete Mac font
1792
+ suitcase resources in the data fork. Supports any SFNT fonts (TTF, OTF, or
1793
+ mixed). Mac OS X specific. File extension: `.dfont`
1794
+
1795
+ Fontist returns the appropriate collection type based on the font data:
1796
+
1797
+ * Examines font data within collection to determine type (TTC vs OTC)
1798
+ * TTC contains fonts with TrueType outlines (glyf table)
1799
+ * OTC contains fonts with CFF outlines (CFF table)
1800
+ * If ANY font in the collection has CFF outlines, use OpenTypeCollection
1801
+ * Only use TrueTypeCollection if ALL fonts have TrueType outlines
1802
+
1803
+
1804
+ === Collection compatibility
1805
+
1806
+ .Compatibility matrix
1807
+ |===
1808
+ | Container | TrueType | CFF | Mixed | WOFF/WOFF2 | Platform
1809
+
1810
+ | TTC | ✅ ONLY | ❌ | ❌ | ❌ | Cross-platform
1811
+ | OTC | ✅ | ✅ | ✅ | ❌ | Cross-platform
1812
+ | dfont | ✅ | ✅ | ✅ | ❌ | Apple only
1813
+
1814
+ |===
1815
+
1816
+ NOTE: WOFF/WOFF2 cannot be packaged into TTC, OTC or dfont collections. Web
1817
+ fonts are designed for single-font delivery only.
1818
+
1819
+
1820
+ === Working with collections
1821
+
1822
+ Fontist supports working with TrueType Collections (TTC), OpenType Collections
1823
+ (OTC) and the legacy Apple dfont format. You can list fonts in a collection,
1824
+ extract individual fonts, unpack entire collections, and validate collection
1825
+ integrity.
1826
+
1827
+ NOTE: Both TTC and OTC files use the same `ttcf` tag in their binary format, but
1828
+ differ in the type of font data they contain.
1829
+
1830
+ In particular, the TTC and OTC formats allows:
1831
+
1832
+ Table sharing::
1833
+ Identical tables are stored once and referenced by multiple fonts
1834
+
1835
+ Gap mode::
1836
+ Overcomes the 65,535 glyph limit per font by distributing glyphs across multiple
1837
+ fonts in a single file
1838
+
1839
+ Efficient storage::
1840
+ Significant size reduction, especially for CJK fonts (e.g., Noto CJK OTC is ~10
1841
+ MB smaller than separate OTF files)
1842
+
1843
+ Fontist returns the appropriate collection type based on the font data:
1844
+
1845
+ * Examines font data within collection to determine type (TTC vs OTC)
1846
+ * TTC contains fonts with TrueType outlines (glyf table)
1847
+ * OTC contains fonts with CFF outlines (CFF table)
1848
+ * If ANY font in the collection has CFF outlines, use OpenTypeCollection
1849
+ * Only use TrueTypeCollection if ALL fonts have TrueType outlines
1850
+
1851
+ === List fonts
1852
+
1853
+ ==== General
1854
+
1855
+ List all fonts in a font collection, with their index, family name, and style.
1856
+
1857
+ ==== Command-line usage
1858
+
1859
+ [source,shell]
1860
+ ----
1861
+ $ fontisan ls FONT.{ttc,otc}
1862
+ ----
1863
+
1864
+ NOTE: In `extract_ttc`, this was done with `extract_ttc --list FONT.ttc`.
1865
+
1866
+ .List collection contents
1867
+ [example]
1868
+ ====
1869
+ [source,shell]
1870
+ ----
1871
+ # List all fonts in a TTC with detailed info
1872
+ $ fontisan ls spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc
1873
+
1874
+ Font 0: Noto Serif CJK JP
1875
+ Family: Noto Serif CJK JP
1876
+ Subfamily: Regular
1877
+ PostScript: NotoSerifCJKJP-Regular
1878
+
1879
+ Font 1: Noto Serif CJK KR
1880
+ Family: Noto Serif CJK KR
1881
+ Subfamily: Regular
1882
+ PostScript: NotoSerifCJKKR-Regular
1883
+
1884
+ Font 2: Noto Serif CJK SC
1885
+ Family: Noto Serif CJK SC
1886
+ Subfamily: Regular
1887
+ PostScript: NotoSerifCJKSC-Regular
1888
+
1889
+ Font 3: Noto Serif CJK TC
1890
+ Family: Noto Serif CJK TC
1891
+ Subfamily: Regular
1892
+ PostScript: NotoSerifCJKTC-Regular
1893
+ ----
1894
+ ====
1895
+
1896
+ .List fonts in dfont suitcase
1897
+ [example]
1898
+ ====
1899
+ [source,shell]
1900
+ ----
1901
+ $ fontisan ls family.dfont
1902
+
1903
+ Font 0: Arial
1904
+ Family: Arial
1905
+ Subfamily: Regular
1906
+
1907
+ Font 1: Arial
1908
+ Family: Arial
1909
+ Subfamily: Bold
1910
+
1911
+ Font 2: Arial
1912
+ Family: Arial
1913
+ Subfamily: Italic
1914
+ ----
1915
+ ====
1916
+
1917
+
1918
+ === Show collection info
1919
+
1920
+ ==== General
1921
+
1922
+ Show detailed information about a TrueType Collection (TTC) or OpenType Collection
1923
+ (OTC), including the number of fonts and metadata for each font.
1924
+
1925
+ ==== Command-line usage
1926
+
1927
+ [source,shell]
1928
+ ----
1929
+ $ fontisan info FONT.{ttc,otc}
1930
+ ----
1931
+
1932
+ NOTE: In `extract_ttc`, this was done with `extract_ttc --info FONT.ttc`.
1933
+
1934
+ .Get collection information
1935
+ [example]
1936
+ ====
1937
+ [source,shell]
1938
+ ----
1939
+ # Detailed collection analysis
1940
+ $ fontisan info spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc --format yaml
1941
+
1942
+ ---
1943
+ collection_type: ttc
1944
+ font_count: 4
1945
+ fonts:
1946
+ - index: 0
1947
+ family_name: Noto Serif CJK JP
1948
+ subfamily_name: Regular
1949
+ postscript_name: NotoSerifCJKJP-Regular
1950
+ font_format: opentype
1951
+ - index: 1
1952
+ family_name: Noto Serif CJK KR
1953
+ subfamily_name: Regular
1954
+ postscript_name: NotoSerifCJKKR-Regular
1955
+ font_format: opentype
1956
+ - index: 2
1957
+ family_name: Noto Serif CJK SC
1958
+ subfamily_name: Regular
1959
+ postscript_name: NotoSerifCJKSC-Regular
1960
+ font_format: opentype
1961
+ - index: 3
1962
+ family_name: Noto Serif CJK TC
1963
+ subfamily_name: Regular
1964
+ postscript_name: NotoSerifCJKTC-Regular
1965
+ font_format: opentype
1966
+ ----
1967
+ ====
1968
+
1969
+
1970
+ === Unpack fonts
1971
+
1972
+ ==== General
1973
+
1974
+ Extract all fonts from a TrueType Collection (TTC) or OpenType Collection (OTC)
1975
+ to a specified output directory.
1976
+
1977
+ ==== Command-line usage
1978
+
1979
+ [source,shell]
1980
+ ----
1981
+ $ fontisan unpack FONT.{ttc,otc} OUTPUT_DIR
1982
+ ----
1983
+
1984
+ NOTE: In `extract_ttc`, this was done with `extract_ttc --unpack FONT.ttc OUTPUT_DIR`.
1985
+
1986
+ .Extract fonts from collection
1987
+ [example]
1988
+ ====
1989
+ [source,shell]
1990
+ ----
1991
+ # Extract all fonts from collection
1992
+ $ fontisan unpack family.ttc --output-dir extracted/
1993
+
1994
+ Collection unpacked successfully:
1995
+ Input: family.ttc
1996
+ Output directory: extracted/
1997
+ Fonts extracted: 3/3
1998
+ - font1.ttf (89.2 KB)
1999
+ - font2.ttf (89.2 KB)
2000
+ - font3.ttf (67.4 KB)
2001
+
2002
+ # Extract specific font with format conversion
2003
+ $ fontisan unpack family.ttc --output-dir extracted/ --font-index 0 --format woff2
2004
+ ----
2005
+ ====
2006
+
2007
+ === Extract specific font
2008
+
2009
+ ==== General
2010
+
2011
+ Extract a specific font from a TrueType Collection (TTC) or OpenType Collection
2012
+ (OTC) by its index.
2013
+
2014
+ ==== Command-line usage
2015
+
2016
+ [source,shell]
2017
+ ----
2018
+ $ fontisan unpack FONT.{ttc,otc} --font-index INDEX OUTPUT.{ttf,otf}
2019
+ ----
2020
+
2021
+ NOTE: In `extract_ttc`, this was done with `extract_ttc --font-index INDEX FONT.ttc OUTPUT.ttf`.
2022
+
2023
+ .Extract with validation
2024
+ [example]
2025
+ ====
2026
+ [source,shell]
2027
+ ----
2028
+ # Extract and validate simultaneously
2029
+ $ fontisan unpack spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc extracted_fonts/ --validate
2030
+
2031
+ Extracting font 0: Noto Serif CJK JP → extracted_fonts/NotoSerifCJKJP-Regular.ttf
2032
+ Extracting font 1: Noto Serif CJK KR → extracted_fonts/NotoSerifCJKKR-Regular.ttf
2033
+ Extracting font 2: Noto Serif CJK SC → extracted_fonts/NotoSerifCJKSC-Regular.ttf
2034
+ Extracting font 3: Noto Serif CJK TC → extracted_fonts/NotoSerifCJKTC-Regular.ttf
2035
+
2036
+ Validation: All fonts extracted successfully
2037
+ ----
2038
+ ====
2039
+
2040
+ === Pack fonts into collection
2041
+
2042
+ ==== General
2043
+
2044
+ Create a new TrueType Collection (TTC) or OpenType Collection (OTC) from multiple
2045
+ font files. Fontisan optimizes the collection by deduplicating shared tables
2046
+ to reduce file size.
2047
+
2048
+ ==== Command-line usage
2049
+
2050
+ .Create TTC collection from multiple fonts
2051
+ [source,shell]
2052
+ ----
2053
+ # Pack fonts into TTC with table sharing optimization
2054
+ $ fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc --analyze
2055
+
2056
+ Collection Analysis:
2057
+ Total fonts: 3
2058
+ Shared tables: 12
2059
+ Potential space savings: 45.2 KB
2060
+ Table sharing: 68.5%
2061
+
2062
+ Collection created successfully:
2063
+ Output: family.ttc
2064
+ Format: TTC
2065
+ Fonts: 3
2066
+ Size: 245.8 KB
2067
+ Space saved: 45.2 KB
2068
+ Sharing: 68.5%
2069
+ ----
2070
+
2071
+ .Create OTC collection from OpenType fonts
2072
+ [source,shell]
2073
+ ----
2074
+ $ fontisan pack Regular.otf Bold.otf Italic.otf --output family.otc --format otc
2075
+ ----
2076
+
2077
+ .Pack into OTC
2078
+ [example]
2079
+ ====
2080
+ [source,shell]
2081
+ ----
2082
+ $ fontisan pack Regular.otf Bold.otf Italic.otf --output family.otc --format otc
2083
+
2084
+ Collection created successfully:
2085
+ Output: family.otc
2086
+ Format: OTC
2087
+ Fonts: 3
2088
+ ----
2089
+
2090
+ NOTE: dfont supports mixed TrueType and OpenType fonts in the same suitcase.
2091
+ dfont does not perform table deduplication like TTC/OTC.
2092
+ ====
2093
+
2094
+
2095
+ === Convert between font container formats
2096
+
2097
+ ==== General
2098
+
2099
+ Fontisan supports converting font collections between TrueType Collection (TTC),
2100
+ OpenType Collection (OTC), and Apple dfont formats.
2101
+
2102
+ All collection formats (TTC, OTC, dfont) support mixed TrueType and OpenType fonts.
2103
+
2104
+ By default, original font formats are preserved during conversion. Use the
2105
+ `--target-format` option to standardize all fonts to a specific outline format:
2106
+
2107
+ * `--target-format preserve` (default) - Keep original mixed TTF+OTF formats
2108
+ * `--target-format ttf` - Convert all fonts to TrueType outlines
2109
+ * `--target-format otf` - Convert all fonts to OpenType/CFF outlines
2110
+
2111
+
2112
+ NOTE: dfont supports mixed TrueType and OpenType fonts in the same suitcase.
2113
+
2114
+ .TTC to OTC conversion (preserves formats)
2115
+ [example]
2116
+ ====
2117
+ [source,shell]
2118
+ ----
2119
+ $ fontisan convert family.ttc --to otc --output family.otc
2120
+
2121
+ Conversion complete!
2122
+ Input: family.ttc (245.8 KB)
2123
+ Output: family.otc (312.4 KB)
2124
+ Format: TTC → OTC
2125
+ Fonts: 3
2126
+ ----
2127
+
2128
+ Original font formats are preserved (mixed TTF+OTF supported).
2129
+ ====
2130
+
2131
+ .TTC to OTC with forced conversion
2132
+ [example]
2133
+ ====
2134
+ [source,shell]
2135
+ ----
2136
+ $ fontisan convert family.ttc --to otc --output family.otc --target-format otf
2137
+
2138
+ Conversion complete!
2139
+ Input: family.ttc (245.8 KB)
2140
+ Output: family.otc (312.4 KB)
2141
+ Format: TTC → OTC
2142
+ Fonts: 3
2143
+ ----
2144
+
2145
+ All TrueType fonts are converted to OpenType/CFF format.
2146
+ ====
2147
+
2148
+ .dfont to OTC conversion (preserves formats)
2149
+ [example]
2150
+ ====
2151
+ [source,shell]
2152
+ ----
2153
+ $ fontisan convert family.dfont --to otc --output family.otc
2154
+
2155
+ Conversion complete!
2156
+ Input: family.dfont (387.6 KB)
2157
+ Output: family.otc (312.4 KB)
2158
+ Format: DFONT → OTC
2159
+ Fonts: 3
2160
+ ----
2161
+
2162
+ Fonts are extracted from dfont and repacked as OTC.
2163
+ Original font formats are preserved (mixed TTF+OTF supported).
2164
+ ====
2165
+
2166
+ .dfont to OTC with forced conversion
2167
+ [example]
2168
+ ====
2169
+ [source,shell]
2170
+ ----
2171
+ $ fontisan convert family.dfont --to otc --output family.otc --target-format otf
2172
+
2173
+ Conversion complete!
2174
+ Input: family.dfont (387.6 KB)
2175
+ Output: family.otc (312.4 KB)
2176
+ Format: DFONT → OTC
2177
+ Fonts: 3
2178
+ ----
2179
+
2180
+ Fonts are extracted from dfont and repacked as OTC.
2181
+ All TrueType fonts are converted to OpenType/CFF format.
2182
+ ====
2183
+
2184
+
2185
+ == Font conversion options
2186
+
2187
+ === General
2188
+
2189
+ Fontisan provides a comprehensive conversion options system based on the TypeTool 3
2190
+ manual's recommended options for different font format conversions. The system supports:
2191
+
2192
+ * Format-specific default options
2193
+ * Named presets for common workflows
2194
+ * Fine-grained control over conversion behavior
2195
+ * Type-safe option validation
2196
+
2197
+ The conversion options system gives you control over how fonts are converted between
2198
+ formats, with options for opening (reading) fonts and generating (writing) fonts.
2199
+
2200
+ For complete documentation, see link:docs/CONVERSION_GUIDE.adoc[Conversion Guide]
2201
+ and link:docs/TYPE1_FONTS.adoc[Type 1 Font Support].
2202
+
2203
+
2204
+ === Show recommended options
2205
+
2206
+ Use `--show-options` to display the recommended options for a conversion:
2207
+
2208
+ [source,shell]
2209
+ ----
2210
+ $ fontisan convert font.ttf --to otf --show-options
2211
+
2212
+ Recommended options for TTF → OTF conversion:
2213
+ ======================================================================
2214
+
2215
+ Opening options:
2216
+ --convert-curves: true
2217
+ --scale-to-1000: true
2218
+ --autohint: true
2219
+ --decompose-composites: false
2220
+ --store-custom-tables: true
2221
+
2222
+ Generating options:
2223
+ --hinting-mode: auto
2224
+ --decompose-on-output: true
2225
+
2226
+ Available presets:
2227
+ type1_to_modern
2228
+ modern_to_type1
2229
+ web_optimized
2230
+ archive_to_modern
2231
+
2232
+ To use preset:
2233
+ fontisan convert ttf --to otf --preset <name> --output output.ext
2234
+ ----
2235
+
2236
+
2237
+ === Using presets
2238
+
2239
+ Presets provide pre-configured options for common conversion scenarios:
2240
+
2241
+ [source,shell]
2242
+ ----
2243
+ # Convert Type 1 to modern OpenType
2244
+ fontisan convert font.pfb --to otf --preset type1_to_modern --output font.otf
2245
+
2246
+ # Convert to web-optimized WOFF2
2247
+ fontisan convert font.otf --to woff2 --preset web_optimized --output font.woff2
2248
+
2249
+ # Convert font archive to modern format
2250
+ fontisan convert family.ttc --to otc --preset archive_to_modern --output family.otc
2251
+ ----
2252
+
2253
+
2254
+ === Custom conversion options
2255
+
2256
+ Individual options can be specified for fine-grained control:
2257
+
2258
+ Opening options (control how the source font is read):
2259
+
2260
+ * `--decompose` - Decompose composite glyphs
2261
+ * `--convert-curves` - Convert curve types during conversion
2262
+ * `--scale-to-1000` - Scale units-per-em to 1000
2263
+ * `--autohint` - Auto-hint the font
2264
+ * `--generate-unicode` - Generate Unicode mappings (Type 1)
2265
+
2266
+ Generating options (control how the output font is written):
2267
+
2268
+ * `--hinting-mode` - Hint mode: preserve, auto, none, or full
2269
+ * `--optimize-tables` - Enable table optimization
2270
+ * `--decompose-on-output` - Decompose composites in output
2271
+
2272
+ WOFF compression knobs (apply to `--to woff` only):
2273
+
2274
+ * `--zlib-level=N` - zlib level (0–9, default 6)
2275
+ * `--uncompressed` - store tables uncompressed (legal per WOFF 1.0 §5.1)
2276
+ * `--compression-threshold=N` - skip compression for tables smaller than N bytes
2277
+
2278
+ WOFF2 compression knobs (apply to `--to woff2` only):
2279
+
2280
+ * `--brotli-quality=N` - Brotli quality (0–11, default 11)
2281
+ * `--transform-tables` / `--no-transform-tables` - apply glyf/loca + hmtx transformations
2282
+
2283
+ The format selection (`--to woff` vs `--to woff2`) **is** the algorithm
2284
+ choice: WOFF mandates zlib, WOFF2 mandates Brotli. Passing a knob that
2285
+ doesn't apply to the requested target exits 1 with a clear error.
2286
+
2287
+ [source,shell]
2288
+ ----
2289
+ # Convert with autohinting and optimization
2290
+ fontisan convert font.ttf --to otf --output font.otf \
2291
+ --autohint --hinting-mode auto --optimize-tables
2292
+
2293
+ # Smallest WOFF2 (max Brotli + table transforms)
2294
+ fontisan convert font.ttf --to woff2 --output font.woff2 \
2295
+ --brotli-quality 11 --transform-tables
2296
+
2297
+ # WOFF for IE 9+ legacy reach (max zlib)
2298
+ fontisan convert font.ttf --to woff --output font.woff --zlib-level 9
2299
+ ----
2300
+
2301
+ `--to` accepts multiple targets so a single invocation produces N
2302
+ output files from one input font. Pass a comma-separated list
2303
+ (`--to woff,woff2`) or repeat the flag (`--to woff --to woff2`).
2304
+ Duplicates are deduplicated.
2305
+
2306
+ [source,shell]
2307
+ ----
2308
+ # Emit both WOFF and WOFF2 in one invocation
2309
+ fontisan convert font.ttf --to woff,woff2 --output font
2310
+ # → font.woff, font.woff2
2311
+ ----
2312
+
2313
+ Output-path rules for multi-format:
2314
+
2315
+ * `--output out` (no extension) + N formats → append `.<format>` per
2316
+ target (`out.woff`, `out.woff2`).
2317
+ * `--output out.ttf` (extension present) + N formats → exits 1
2318
+ (ambiguous which format gets the extension).
2319
+ * `--output out.ttf` + one format → use as given (existing behaviour).
2320
+
2321
+ Multi-format is single-font → single-font only. Combining multi-format
2322
+ with collection input (TTC/OTC/dfont) exits 1.
2323
+
2324
+ For detailed information on all available options and conversion scenarios,
2325
+ see the link:docs/CONVERSION_GUIDE.adoc[Conversion Guide].
2326
+
2327
+
2328
+ === Ruby API usage
2329
+
2330
+ .Using recommended options
2331
+ [example]
2332
+ ====
2333
+ [source,ruby]
2334
+ ----
2335
+ require 'fontisan'
2336
+
2337
+ # Get recommended options for TTF → OTF conversion
2338
+ options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
2339
+
2340
+ # Access opening and generating options
2341
+ options.opening # => { convert_curves: true, scale_to_1000: true, ... }
2342
+ options.generating # => { hinting_mode: "auto", decompose_on_output: true }
2343
+
2344
+ # Use with converter
2345
+ converter = Fontisan::Converters::OutlineConverter.new
2346
+ tables = converter.convert(font, options: options)
2347
+ ----
2348
+ ====
2349
+
2350
+
2351
+ .Using presets programmatically
2352
+ [example]
2353
+ ====
2354
+ [source,ruby]
2355
+ ----
2356
+ require 'fontisan'
2357
+
2358
+ # Load a preset
2359
+ options = Fontisan::ConversionOptions.from_preset(:type1_to_modern)
2360
+
2361
+ # Convert with preset
2362
+ converter = Fontisan::Converters::Type1Converter.new
2363
+ tables = converter.convert(font, options: options)
2364
+ ----
2365
+ ====
2366
+
2367
+
2368
+ .Building custom options
2369
+ [example]
2370
+ ====
2371
+ [source,ruby]
2372
+ ----
2373
+ require 'fontisan'
2374
+
2375
+ # Build custom conversion options
2376
+ options = Fontisan::ConversionOptions.new(
2377
+ from: :ttf,
2378
+ to: :otf,
2379
+ opening: { autohint: true, convert_curves: true },
2380
+ generating: { hinting_mode: "auto" }
2381
+ )
2382
+
2383
+ # Use with converter
2384
+ converter = Fontisan::Converters::OutlineConverter.new
2385
+ tables = converter.convert(font, options: options)
2386
+ ----
2387
+ ====
2388
+
2389
+
2390
+ .One-shot conversion via Fontisan.convert
2391
+ [example]
2392
+ ====
2393
+ [source,ruby]
2394
+ ----
2395
+ require 'fontisan'
2396
+
2397
+ # TTF → WOFF2 (modern browsers)
2398
+ Fontisan.convert('font.ttf', to: :woff2, output: 'font.woff2',
2399
+ brotli_quality: 11, transform_tables: true)
2400
+
2401
+ # TTF → WOFF (IE 9+ legacy reach, max zlib)
2402
+ Fontisan.convert('font.ttf', to: :woff, output: 'font.woff', zlib_level: 9)
2403
+
2404
+ # WOFF stored uncompressed (legal per WOFF 1.0 §5.1; useful for tooling)
2405
+ Fontisan.convert('font.ttf', to: :woff, output: 'font.woff', uncompressed: true)
2406
+ ----
2407
+ ====
2408
+
2409
+
2410
+ == Round-Trip validation
2411
+
2412
+ === General
2413
+
2414
+ Fontisan ensures high-fidelity font conversion through comprehensive round-trip
2415
+ validation.
2416
+
2417
+ When converting between TrueType (TTF) and OpenType/CFF (OTF) formats, the
2418
+ validation system verifies that glyph geometry is preserved accurately.
2419
+
2420
+ Key validation features:
2421
+
2422
+ * **Command-Level Precision**: Validates individual drawing commands (move, line, curve)
2423
+ * **Coordinate Tolerance**: Accepts ±2 pixels tolerance for rounding during conversion
2424
+ * **Format-Aware Comparison**: Handles differences between TrueType quadratic and CFF cubic curves
2425
+ * **Closepath Handling**: Smart detection of geometrically closed vs open contours
2426
+
2427
+ === Technical details
2428
+
2429
+ Round-trip validation works by:
2430
+
2431
+ [source]
2432
+ ----
2433
+ Original TTF → Convert to CFF → Extract CFF → Compare Geometry
2434
+ (Input) (Encode) (Decode) (Validate)
2435
+ ----
2436
+
2437
+ **Validation process**:
2438
+
2439
+ . Extract glyph outlines from original TTF
2440
+ . Convert to CFF format with CharString encoding
2441
+ . Parse CFF CharStrings back to universal outlines
2442
+ . Compare geometry with coordinate tolerance (±2 pixels)
2443
+
2444
+ **Format differences handled**:
2445
+
2446
+ * **Closepath**: CFF has implicit closepath, TTF has explicit
2447
+ * **Curve types**: TrueType quadratic (`:quad_to`) vs CFF cubic (`:curve_to`)
2448
+ * **Coordinate rounding**: Different number encoding causes minor differences
2449
+
2450
+ **Validation criteria**: Geometry Match:
2451
+ . Same bounding box (±2 pixel tolerance)
2452
+ . Same number of path commands (excluding closepath)
2453
+ . Same endpoint coordinates for curves (±2 pixels)
2454
+ . Quadratic→cubic conversion accepted
2455
+
2456
+
2457
+ == Universal outline model
2458
+
2459
+ === General
2460
+
2461
+ The Fontisan Universal Outline Model (UOM) is based on a self-stable algorithm
2462
+ for converting soft glyph contours to outline format used in all tools of
2463
+ Fontisan. This ability allows easy modeling of import glyphs from one font
2464
+ format TrueType (TTF, OTF binaries), converting glyph elements into any font
2465
+ format, TrueType for example.
2466
+
2467
+ === Locker
2468
+
2469
+ Locker is an object-oriented model for storing imported outlines and glyphs.
2470
+ Storage is based on monotonic spirals computed based on 2D points and curves.
2471
+ Invisible converting from TrueType, CFF Opentype and ColorGlyph formats.
2472
+
2473
+ === Translator
2474
+
2475
+ Translation is an object-oriented model for converting from and to PostScript
2476
+ custom CFF charset. New encoding/decoding includes PostScript Type 2/3/composite
2477
+ Loron.
2478
+
2479
+ === ColorGlyph
2480
+
2481
+ Support for layered import CFF color glyphs rasterizing on demand, with
2482
+ composite font support, a multi-layer color font represented by many
2483
+ CFF fonts stacked on top of each other. ColorGlyph support contains
2484
+ color glyphs, advanced color fonts glyphs and raster images (PNG or JPG)
2485
+ combined with TrueType outlines.
2486
+
2487
+ === Universal fonts
2488
+
2489
+ Fontisan can:
2490
+
2491
+ * Import TrueType contours into Universal Outline Model (UOM)
2492
+ * Operate UOM outlines including transformations, serialization (save)
2493
+ * Select and convert all UOM contours to TTF/OTF
2494
+ * Cleaning
2495
+ * Improve
2496
+ * Render
2497
+ * Building works for TrueType
2498
+ * Convert colors (cvt to TTF/OTF or TTF to cvt)
2499
+ * Saving and sharing font structures
2500
+ * Working with advanced color fonts
2501
+
2502
+ === Universal glyphs
2503
+
2504
+ Fontisan can:
2505
+
2506
+ * Use Universal Outline Model (UOM) for TrueType contours and CFF color glyphs
2507
+ * Repository for investor-defined fonts
2508
+ * Custom Unicode assignments, rewriting Unicode configurations
2509
+ * Saving and import outlines, including TrueType and OTF/CFF
2510
+ * Rendering for advanced font types
2511
+ * Universal layer stacking for advanced color glyph combinations
2512
+
2513
+ === Universal color layers
2514
+
2515
+ (Fontisan, converted TTF, OTF files)
2516
+
2517
+ Fontisan can:
2518
+
2519
+ * Import embedded TTF/OTF color layers
2520
+ * Assembler from individual TTF/OTF slices
2521
+ * Advanced managing layer maps in TTF color (CFF) fonts
2522
+ * Advanced color layer blending style management
2523
+ * Managing Gray/Overprint/Color-Full image comps and layer conversion
2524
+ * Strategy management for smart vector combos from raster
2525
+ * Importing and generation PNG block ruler layers
2526
+
2527
+
2528
+ == UFO source operations
2529
+
2530
+ fontisan reads, writes, and compiles UFO (Unified Font Object) v2/v3
2531
+ font sources into binary font formats (TTF, OTF, OTF2/CFF2). No AFDKO
2532
+ or Python fonttools needed.
2533
+
2534
+ === Build a UFO to binary
2535
+
2536
+ [source,bash]
2537
+ ----
2538
+ # TTF (TrueType outlines)
2539
+ fontisan ufo build font.ufo --output out.ttf --to ttf
2540
+
2541
+ # OTF (CFF outlines)
2542
+ fontisan ufo build font.ufo --output out.otf --to otf
2543
+ ----
2544
+
2545
+ The TTF compiler automatically applies:
2546
+ - `cubic_to_quadratic` filter (UFO cubic Beziers -> TTF quadratic)
2547
+ - `reverse_contour_direction` filter (TTF winding convention)
2548
+
2549
+ === Ruby API — compile to TTF, OTF, or CFF2
2550
+
2551
+ [source,ruby]
2552
+ ----
2553
+ require "fontisan"
2554
+
2555
+ font = Fontisan::Ufo::Font.open("font.ufo")
2556
+
2557
+ # TrueType (.ttf) — quadratic outlines
2558
+ Fontisan::Ufo::Compile::TtfCompiler.new(font).compile(output_path: "out.ttf")
2559
+
2560
+ # OpenType/CFF1 (.otf) — cubic outlines
2561
+ Fontisan::Ufo::Compile::OtfCompiler.new(font).compile(output_path: "out.otf")
2562
+
2563
+ # OpenType/CFF2 (.otf) — modern format, supports variable fonts
2564
+ Fontisan::Ufo::Compile::Otf2Compiler.new(font).compile(output_path: "out.otf")
2565
+
2566
+ # Write back to UFO (round-trip)
2567
+ Fontisan::Ufo::Writer.new(font).write("out.ufo")
2568
+
2569
+ # Convert a binary font to UFO
2570
+ ttf = Fontisan::FontLoader.load("font.ttf")
2571
+ ufo = Fontisan::Ufo::Convert::FromBinData.convert(ttf)
2572
+ ----
2573
+
2574
+ === Variable font compilation
2575
+
2576
+ [source,ruby]
2577
+ ----
2578
+ # Variable TTF (glyf outlines)
2579
+ orchestrator = Fontisan::Ufo::Compile::VariableTtf.new(
2580
+ font: default_font,
2581
+ axes: [{ tag: "wght", min: 100, default: 400, max: 900 }],
2582
+ masters: [{ font: bold_font, axes: { "wght" => 1.0 } }],
2583
+ )
2584
+ orchestrator.compile(output_path: "variable.ttf")
2585
+
2586
+ # Variable OTF (CFF2 outlines)
2587
+ orchestrator = Fontisan::Ufo::Compile::VariableOtf.new(
2588
+ default_font,
2589
+ axes: [{ tag: "wght", min: 100, default: 400, max: 900 }],
2590
+ )
2591
+ orchestrator.compile(output_path: "variable.otf")
2592
+ ----
2593
+
2594
+ See link:docs/CFF2_SUPPORT.adoc[CFF2 Support Guide] for CFF2-specific
2595
+ features (blend operators, FDSelect, subroutines, VariationStore).
2596
+
2597
+ == Font stitching
2598
+
2599
+ The Stitcher combines glyphs from multiple source fonts into one or
2600
+ more new fonts. Sources can be UFO directories or loaded TTF/OTF files.
2601
+
2602
+ Every `include_*` method requires an `into:` keyword naming the target
2603
+ subfont. `write_to` requires a `subfont:` name. No defaults — the user
2604
+ controls the collection structure explicitly.
2605
+
2606
+ === Single font
2607
+
2608
+ [source,ruby]
2609
+ ----
2610
+ stitcher = Fontisan::Stitcher.new
2611
+ stitcher.add_source(:latin, Fontisan::FontLoader.load("NotoSans.ttf"))
2612
+ stitcher.add_source(:cjk, Fontisan::FontLoader.load("FSung-m.ttf"))
2613
+
2614
+ stitcher.include_notdef(from: :latin, into: :main)
2615
+ stitcher.include_range(0x41..0x5A, from: :latin, into: :main) # A-Z
2616
+ stitcher.include_range(0x4E00..0x9FFF, from: :cjk, into: :main) # CJK
2617
+
2618
+ stitcher.write_to("stitched.ttf", format: :ttf, subfont: :main)
2619
+ ----
2620
+
2621
+ === Collection (TTC/OTC) with explicit subfonts
2622
+
2623
+ When the glyph count exceeds 65,535 (the OpenType cap), split across
2624
+ named subfonts and write a collection:
2625
+
2626
+ [source,ruby]
2627
+ ----
2628
+ stitcher = Fontisan::Stitcher.new
2629
+ stitcher.add_source(:noto_sans, Fontisan::FontLoader.load("NotoSans.ttf"))
2630
+ stitcher.add_source(:noto_cjk, Fontisan::FontLoader.load("NotoSansCJK.ttf"))
2631
+
2632
+ # Explicitly assign codepoints to named subfonts
2633
+ stitcher.include_range(0x41..0x5A, from: :noto_sans, into: :latin)
2634
+ stitcher.include_range(0x4E00..0x9FFF, from: :noto_cjk, into: :cjk)
2635
+
2636
+ # Write as OTC with CFF2 subfonts and table deduplication.
2637
+ # Returns a Stitcher::CollectionResult (path, bytes, per-subfont stats).
2638
+ result = stitcher.write_collection("out.otc", format: :otf2)
2639
+ result.face_count # => 2
2640
+ result.subfonts.map(&:name) # => [:latin, :cjk]
2641
+ result.subfonts.first.glyph_count # maxp.num_glyphs of face 0
2642
+ ----
2643
+
2644
+ === Donor maps and partitioning
2645
+
2646
+ `include_codepoints_map(cp_map, into:)` takes a `{codepoint => donor}`
2647
+ map and groups internally — one call handles N codepoints from M
2648
+ donors:
2649
+
2650
+ [source,ruby]
2651
+ ----
2652
+ stitcher.include_codepoints_map(
2653
+ { 0x41 => :noto_sans, 0x4E00 => :noto_cjk },
2654
+ into: :main,
2655
+ )
2656
+ ----
2657
+
2658
+ For automatic plane-aware splitting, use
2659
+ `Stitcher::PartitionStrategy::ByPlane`. It groups codepoints by
2660
+ Unicode plane and sub-splits planes that overflow the cap along the
2661
+ large CJK-extension block boundaries:
2662
+
2663
+ [source,ruby]
2664
+ ----
2665
+ require "fontisan/stitcher/partition_strategy"
2666
+
2667
+ blueprint = Fontisan::Stitcher::PartitionStrategy::ByPlane.new
2668
+ .call(cp_map, cap: 65_484)
2669
+ blueprint.apply_to(stitcher) # declares one subfont per partition
2670
+ ----
2671
+
2672
+ If a single CJK extension block alone exceeds the cap, ByPlane raises
2673
+ `Fontisan::PartitionCapExceededError`. ByBlock/ByScript partitioners
2674
+ (via Unicode Blocks.txt / Scripts.txt) are tracked as a follow-up —
2675
+ the framework is open for them.
2676
+
2677
+ === Per-subfont metadata
2678
+
2679
+ `Ufo::Info.for_subfont(family:, subfont:, version:, ...)` builds the
2680
+ standard name-table fields for one subfont of a collection. The
2681
+ family name embeds the subfont (`"essenfont SIP"`), the PostScript
2682
+ name uses the hyphenated form (`"essenfont-SIP"`), and the version is
2683
+ parsed into `version_major` / `version_minor` per the UFO
2684
+ major.minor shape.
2685
+
2686
+ [source,ruby]
2687
+ ----
2688
+ stitcher.set_info(
2689
+ Fontisan::Ufo::Info.for_subfont(
2690
+ family: "essenfont", subfont: :SIP, version: "0.1"
2691
+ ).to_plist,
2692
+ )
2693
+ ----
2694
+
2695
+ === CBDT/CBLC passthrough (color emoji)
2696
+
2697
+ Sources with CBDT/CBLC tables (e.g. NotoColorEmoji) can be used as
2698
+ Stitcher sources. The bitmap data is propagated byte-for-byte from the
2699
+ source into the output.
2700
+
2701
+ [source,ruby]
2702
+ ----
2703
+ stitcher = Fontisan::Stitcher.new
2704
+ stitcher.add_source(:text, Fontisan::FontLoader.load("NotoSans.ttf"))
2705
+ stitcher.add_source(:emoji, Fontisan::FontLoader.load("NotoColorEmoji.ttf"))
2706
+
2707
+ stitcher.include_notdef(from: :text, into: :main)
2708
+ stitcher.include_range(0x41..0x5A, from: :text, into: :main)
2709
+ stitcher.include_range(0x1F600..0x1F64F, from: :emoji, into: :main)
2710
+
2711
+ stitcher.write_to("out.ttf", format: :ttf, subfont: :main)
2712
+ # → out.ttf has glyf + CBDT + CBLC, emoji renders correctly
2713
+ ----
2714
+
2715
+ === SVG path → glyph conversion
2716
+
2717
+ Convert SVG path data (from ucode code-chart extraction) into UFO glyphs:
2718
+
2719
+ [source,ruby]
2720
+ ----
2721
+ # Single path → glyph
2722
+ glyph = Fontisan::SvgToGlyf.convert(
2723
+ "M 0 0 L 500 0 L 500 700 Z",
2724
+ upm: 1000,
2725
+ codepoint: 0x10940,
2726
+ )
2727
+
2728
+ # SVG file → glyph
2729
+ glyph = Fontisan::SvgToGlyf.from_svg_file("U+10940.svg", upm: 1000)
2730
+
2731
+ # Directory of SVGs → font (for Stitcher#add_source)
2732
+ font = Fontisan::SvgToGlyf.from_directory("/tmp/chart-svg/Khitan", upm: 1000)
2733
+ ----
2734
+
2735
+ See link:docs/SVG_TO_GLYF.adoc[SVG to Glyph Guide] for details.
2736
+
2737
+ === CLI
2738
+
2739
+ [source,bash]
2740
+ ----
2741
+ fontisan stitch \
2742
+ --source latin=NotoSans.ttf \
2743
+ --source cjk=FSung-m.ttf \
2744
+ --include-range latin=0x41-0x5A \
2745
+ --include-range cjk=0x4E00-0x9FFF \
2746
+ --notdef-from latin \
2747
+ --output stitched.ttf
2748
+ ----
2749
+
2750
+
2751
+ == Testing
2752
+
2753
+ === General
2754
+
2755
+ Fontisan has a comprehensive test suite covering all font operations, formats,
2756
+ and features.
2757
+
2758
+ === Running tests
2759
+
2760
+ [source,shell]
2761
+ ----
2762
+ # Run full test suite
2763
+ bundle exec rspec
2764
+
2765
+ # Run with documentation format
2766
+ bundle exec rspec --format documentation
2767
+
2768
+ # Run specific file
2769
+ bundle exec rspec spec/fontisan/tables/maxp_spec.rb
2770
+ ----
2771
+
2772
+ === Test fixtures
2773
+
2774
+ All required font fixtures are automatically downloaded before tests run. The
2775
+ test suite uses a centralized fixture configuration system that ensures all
2776
+ necessary fonts are available.
2777
+
2778
+ [source,shell]
2779
+ ----
2780
+ # Manual fixture management (if needed)
2781
+ bundle exec rake fixtures:download # Download all test fonts
2782
+ bundle exec rake fixtures:clean # Remove downloaded fonts
2783
+ ----
2784
+
2785
+
2786
+ === Reference corpus and benchmarks
2787
+
2788
+ `corpus/` holds the golden outputs of the pure-Ruby engine (fontist/fontisan#157).
2789
+ The fonts themselves are not in git: `corpus/manifest.json` pins each source
2790
+ by URL and SHA-256, and `rake corpus:fetch` downloads and verifies them into
2791
+ `corpus/fonts/`. `corpus:verify` and `bench` run the fetch themselves, so a
2792
+ fresh clone needs no manual step.
2793
+
2794
+ [source,shell]
2795
+ ----
2796
+ bundle exec rake corpus:fetch # download + checksum the ci tier (TIER=ci|large|all)
2797
+ bundle exec rake corpus:verify # compare read goldens; never writes
2798
+ bundle exec rake bench # run the benches, print the report, write BENCHMARKS.md
2799
+ ----
2800
+
2801
+ Goldens are compared, never regenerated, by the tests. `corpus:regenerate` is
2802
+ the one explicit rewrite and belongs in a PR that shows the golden diff.
2803
+ Baseline numbers are in link:BENCHMARKS.md[BENCHMARKS.md]; the `Perf Gate`
2804
+ workflow fails a PR that makes an operation more than 25% slower than its base.
2805
+
2806
+ == Copyright and license
2807
+
2808
+ Copyright https://www.ribose.com[Ribose].
2809
+
2810
+ Fontisan is licensed under the Ribose 3-Clause BSD License. See the LICENSE file
2811
+ for details.