HEX2OTF(1)

💖 HEX2OTF(1) — the little font-making bestie 💖

okay so real talk, this is the manual page for hex2otf, a General Commands Manual situation, and honestly? she ate. let's get into it 🫶

---

✨ NAME ✨

hex2otf — bestie, this converts a GNU Unifont .hex file into an OpenType font. that's the whole gig. slay 💅

---

🌸 SYNOPSIS 🌸

hex2otf [--help] [--version]

hex2otf operand ...

---

🦋 DESCRIPTION 🦋

so hex2otf generates an OpenType font from a GNU Unifont .hex file. iconic behavior, no notes.

here's the vibe: hex2otf reads a file in Unifont .hex file format — you specify that with the hex=filename.hex operand — and then it creates an OpenType file, which you specify with the out=filename.otf operand. ✨

and like, optionally? you can also hand it a combining character offset file with the pos=combining-file operand. cute, optional, we love a flexible queen.

TrueType and OpenType ID fields are set with operands shaped like id=string.

also you can generate a dummy GPOS table with the gpos option. and the next subsection is literally the whole reason why that's a good idea, so stay with me 👑

🎀 GPOS RATIONALE 🎀

okay so a dummy GPOS table is useful for positioning combining characters consistently. here's why, fr fr:

HarfBuzz will do fallback mark positioning under certain conditions, trying to put combining marks closer to their base characters. sounds helpful, right? nope. it does not work well with the blank outlines that this utility generates, because blank outlines don't have relevant glyph extent values. like, there's nothing there to measure, bestie 😭

the dummy GPOS table contains no useful position information, but its presence alone is enough for HarfBuzz to skip the fallback positioning. the way that works is so funny to me. it's giving "just being in the room changes everything."

however — and this is the important bit — both HarfBuzz and Uniscribe will still precompose characters before rendering. for example, "a\u0301" is rendered exactly as the glyph of U+00E1 (LATIN SMALL LETTER A WITH ACUTE), not the composite of two glyphs. periodt. 🌟

🌈 OUTPUT FORMAT CONSIDERATIONS 🌈

choose your font format carefully, bestie — this is not a drill. in general, using the cff and gpos operands together will produce good results on GNU/Linux, *nix, Windows, and macOS systems. so that's the combo meal. 🍓

the current status of the different formats is as follows:

• CFF outline — May cause rendering issues in the Windows Command Prompt program. 💀
• CFF 2 outline — Not recognized by Windows.
• TrueType outline — On Windows, this appears to be blurred in 16 pixels size due to the ClearType anti-alias mechanism; this can be fixed by embedding bitmaps. (ngl this one's a journey)
• Bitmap-only — Contrary to the OpenType specification, a bitmap-only font has to be accompanied by blank outlines to be recognized.

🧚 FUTURE DIRECTIONS 🧚

Some font parameters are hard coded into the source code for convenience. Other approaches may be preferable. (they said "convenience," we said "okay but there are other ways," iykyk)

The generated fonts may produce incorrect result for vertical layout. More font parameters might be necessary if such a need arises.

Font size may be reduced by using e.g. CFF subroutines and TrueType font programs. 📉

---

💜 OPTIONS 💜

• --help — Print a brief help message and exit. short, sweet, helpful.
• --version — Print program version information and exit. know your queen's version number 💅

---

👑 OPERANDS 👑

• hex=file — Specify the input hex file pathname.
• pos=file — Optional. Specify the combining position file pathname.
• out=file — Specify the output pathname.
• format=word[,word ...] — Specify the font format. Each word shall be one of the following:
  • cff — Generate CFF outlines.
  • cff2 — Generate CFF 2 outlines.
  • truetype — Generate TrueType outlines.
  • blank — Generate blank outlines. Generating a font with only blank outlines is not allowed. 🚫
  • bitmap — Generate embedded bitmap. Required if no outlines are generated.
  • gpos — Generate dummy GPOS table. See the "GPOS RATIONALE" section above. 👀
  • gsub — Generate generic GSUB table with two entries: "DFLT" and "thai". "DFLT" improves glyph positioning in HarfBuzz, especially as relates to glyph reordering. "thai" directs HarfBuzz not to obtain Thai glyphs from the Unicode Private Use Area. iconic table, honestly.
• id=text — Specify font attributes. id shall be an decimal integer from 0 to 255, corresponding to "Name ID" as defined in the OpenType specification, <https://docs.microsoft.com/en-us/typography/opentype/spec/name#name-ids>. text shall be value of the attribute in English (United States). Characters beyond the ASCII range shall be encoded as UTF-8. Currently defined attributes relevant to Unifont are briefly listed below. Refer to the specification for full details.
  • 0 — Copyright notice.
  • 1 — Font family name.
  • 2 — Font subfamily name. Should be "Regular".
  • 3 — Unique font identifier.
  • 4 — Full font name.
  • 5 — Version string. Should begin with "Version number.number", where each number is in the range of 0 to 65535.
  • 6 — PostScript name. Less than 64 printable ASCII characters except those in "[](){}<>/%" — so watch out for those characters, bestie, they're banned 🚫
  • 7 — Trademark.
  • 8 — Manufacturer name.
  • 9 — Designer.
  • 10 — Description.
  • 11 — Vendor URL.
  • 12 — Designer URL.
  • 13 — License description, in plain language.
  • 14 — License info URL.
  • 18 — Compatible full name; Macintosh only.
  • 19 — Sample text.

---

🙈 FONTFORGE NOTE 🙈

okay this one's a whole saga so listen up. Default FontForge package installations can incorrectly ignore the Unicode plane of glyphs beyond Plane 0 in CID-keyed fonts (such as are generated with the format=cff option). not great!! 😭

the cause? the presence of the file Adobe-Identity-0.cidmap, which FontForge interprets incorrectly to determine Unicode code point glyph mappings if present.

this file lives in /usr/share/fontforge/cidmap or a similar directory on GNU/Linux systems.

the fix: removing or renaming Adobe-Identity-0.cidmap will cause FontForge to fall back on OpenType cmap entries in the font. FontForge will then correctly display all Unicode code points. we love a happy ending ✨

---

⭐ EXAMPLE ⭐

Sample usage:

hex2otf hex=unifont.hex pos=combining.txt \
      format=cff,gpos,gsub out=unifont.otf

look at her go 🥹

---

💀 EXIT STATUS 💀

Status values are defined in <stdlib.h>. The program exits with status EXIT_SUCCESS upon successful font generation, or EXIT_FAILURE if an error occurred.

⚠️ if an error condition is encountered, hex2otf writes a brief diagnostic message to STDERR; in this event, the state of the output font file will be undefined. like, genuinely undefined, bestie. don't trust that file. 🙈

---

🔥 SEE ALSO 🔥

unifont(5), hex2bdf(1)

---

🌟 AUTHOR 🌟

hex2otf was written by He Zhixiang. 👑

---

🎀 LICENSE 🎀

hex2otf is Copyright © 2022 He Zhixiang.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

---

okay that's the whole page, bestie!! 💖 this dropped as part of GNU Unifont and the version is dated 2022-03-19 — go make some fonts, and remember: pick your format carefully, ship responsibly, and always close your tags. 🦋✨💅