'\" t
@comment TROFF INPUT: .TH HEX2OTF 1 2022-03-19 "GNU Unifont"

@node hex2otf
@section hex2otf
@c DEBUG: print_menu("@section")

@menu
* hex2otf NAME::
* hex2otf SYNOPSIS::
* hex2otf DESCRIPTION::
* hex2otf OPTIONS::
* hex2otf OPERANDS::
* hex2otf FONTFORGE NOTE::
* hex2otf EXAMPLE::
* hex2otf EXIT STATUS::
* hex2otf SEE ALSO::
* hex2otf AUTHOR::
* hex2otf LICENSE::

@end menu


@comment TROFF INPUT: .SH NAME

@node hex2otf NAME
@subsection hex2otf NAME
@c DEBUG: print_menu("hex2otf NAME")

hex2otf @minus{} Convert a GNU Unifont .hex file to an OpenType font
@comment TROFF INPUT: .SH SYNOPSIS

@node hex2otf SYNOPSIS
@subsection hex2otf SYNOPSIS
@c DEBUG: print_menu("hex2otf SYNOPSIS")

@comment TROFF INPUT: .B hex2otf
@b{hex2otf}
[@minus{}@minus{}help] [@minus{}@minus{}version]
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .B hex2otf
@b{hex2otf}
@i{operand} @dots{}
@comment TROFF INPUT: .SH DESCRIPTION

@node hex2otf DESCRIPTION
@subsection hex2otf DESCRIPTION
@c DEBUG: print_menu("hex2otf DESCRIPTION")

The
@comment TROFF INPUT: .B hex2otf
@b{hex2otf}
utility generates an OpenType font from a GNU Unifont .hex file.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .B hex2otf
@b{hex2otf}
reads a file in Unifont .hex file format, as specified with the
@t{hex=}@i{filename.hex} operand, and creates an OpenType
file as specified with the @t{out=}@i{filename.otf} operand.
A combining character offset file may optionally be specified
with the @t{pos=}@i{combining-file} operand.
@comment TROFF INPUT: .PP

TrueType and OpenType ID fields are specified with operands
of the form @i{id}=@i{string}.
@comment TROFF INPUT: .PP

A dummy GPOS table can be generated with the @t{gpos} option.
The following subsection describes why this is beneficial.
@comment TROFF INPUT: .SS "GPOS RATIONALE"

@node GPOS RATIONALE
@subsubsection GPOS RATIONALE

A dummy GPOS table is useful for positioning combining characters consistently.
For example,
HarfBuzz will perform fallback mark positioning on certain conditions,
trying to put combining marks closer to their base characters.
But it does not work well with the blank outlines generated by this utility,
because blank outlines do not have relevant glyph extent values.
The dummy GPOS table contains no useful position information,
but its presence is enough for HarfBuzz to skip the fallback positioning.
However, 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.
@comment TROFF INPUT: .SS "OUTPUT FORMAT CONSIDERATIONS"

@node OUTPUT FORMAT CONSIDERATIONS
@subsubsection OUTPUT FORMAT CONSIDERATIONS

The font format should be carefully chosen.
In general, using the @b{cff} and @b{gpos} operands
together will produce good results on GNU/Linux, *nix, Windows, and
macOS systems.  The current status of different formats is as follows:
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
@comment TROFF INPUT: .TP 6

@c ---------------------------------------------------------------------
@table @code
@item CFF outline
May cause rendering issues in the Windows Command Prompt program.
@comment TROFF INPUT: .TP

@item CFF 2 outline
Not recognized by Windows.
@comment TROFF INPUT: .TP

@item 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.
@comment TROFF INPUT: .TP

@item Bitmap-only
Contrary to the OpenType specification,
a bitmap-only font has to be accompanied by blank outlines to be recognized.
@comment TROFF INPUT: .RE

@end table

@c ---------------------------------------------------------------------

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SS "FUTURE DIRECTIONS"

@node FUTURE DIRECTIONS
@subsubsection FUTURE DIRECTIONS

Some font parameters are hard coded into the source code for convenience.
Other approaches may be preferable.
@comment TROFF INPUT: .PP

The generated fonts may produce incorrect result for vertical layout.
More font parameters might be necessary if such a need arises.
@comment TROFF INPUT: .PP

Font size may be reduced by using @i{e.g.} CFF subroutines and TrueType font
programs.
@comment TROFF INPUT: .SH OPTIONS

@node hex2otf OPTIONS
@subsection hex2otf OPTIONS
@c DEBUG: print_menu("hex2otf OPTIONS")

@comment TROFF INPUT: .TP 10
@comment TROFF INPUT: .B --help

@c ---------------------------------------------------------------------
@table @code
@item @b{@minus{}@minus{}help}
Print a brief help message and exit.
@comment TROFF INPUT: .TP
@comment TROFF INPUT: .B --version

@item @b{@minus{}@minus{}version}
Print program version information and exit.
@comment TROFF INPUT: .SH OPERANDS

@end table

@c ---------------------------------------------------------------------

@node hex2otf OPERANDS
@subsection hex2otf OPERANDS
@c DEBUG: print_menu("hex2otf OPERANDS")

@comment TROFF INPUT: .TP 10

@c ---------------------------------------------------------------------
@table @code
@item @b{hex}=@i{file}
Specify the input hex file pathname.
@comment TROFF INPUT: .TP

@item @b{pos}=@i{file}
Optional. Specify the combining position file pathname.
@comment TROFF INPUT: .TP

@item @b{out}=@i{file}
Specify the output pathname.
@comment TROFF INPUT: .TP

@item @b{format}=@i{word}[,@i{word }@dots{}]
Specify the font format.
Each
@comment TROFF INPUT: .I word
@i{word}
shall be one of the following:
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
@comment TROFF INPUT: .TP 12
@comment TROFF INPUT: .B cff

@c ---------------------------------------------------------------------
@table @code
@item @b{cff}
Generate CFF outlines.
@comment TROFF INPUT: .TP
@comment TROFF INPUT: .B cff2

@item @b{cff2}
Generate CFF 2 outlines.
@comment TROFF INPUT: .TP
@comment TROFF INPUT: .B truetype

@item @b{truetype}
Generate TrueType outlines.
@comment TROFF INPUT: .TP
@comment TROFF INPUT: .B blank

@item @b{blank}
Generate blank outlines.
Generating a font with only blank outlines is not allowed.
@comment TROFF INPUT: .TP
@comment TROFF INPUT: .B bitmap

@item @b{bitmap}
Generate embedded bitmap.
Required if no outlines are generated.
@comment TROFF INPUT: .TP
@comment TROFF INPUT: .B gpos

@item @b{gpos}
Generate dummy GPOS table.
See the ``GPOS RATIONALE'' section above.

@item @b{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 @i{not}
to obtain Thai glyphs from the Unicode Private Use Area.
@comment TROFF INPUT: .RE

@end table

@c ---------------------------------------------------------------------

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .TP

@item @i{id}=@i{text}
Specify font attributes.
@comment TROFF INPUT: .B id
@b{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>.
@comment TROFF INPUT: .I text
@i{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.
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
@comment TROFF INPUT: .TP 6
@comment TROFF INPUT: .B ID

@c ---------------------------------------------------------------------
@page{}
@table @code
@item @b{ID}
@comment TROFF INPUT: .B Meaning and Notes
@b{Meaning and Notes}
@comment TROFF INPUT: .TP

@item 0
Copyright notice.
@comment TROFF INPUT: .TP

@item 1
Font family name.
@comment TROFF INPUT: .TP

@item 2
Font subfamily name.  Should be ``Regular''.
@comment TROFF INPUT: .TP

@item 3
Unique font identifier.
@comment TROFF INPUT: .TP

@item 4
Full font name.
@comment TROFF INPUT: .TP

@item 5
Version string.  Should begin with ``Version @i{number.number}'',
where each
@comment TROFF INPUT: .I number
@i{number}
is in the range of 0 to 65535.
@comment TROFF INPUT: .TP

@item 6
PostScript name.  Less than 64 printable ASCII characters except those in
``@i{[]()@{@}<>/%}''
@comment TROFF INPUT: .TP

@item 7
Trademark.
@comment TROFF INPUT: .TP

@item 8
Manufacturer name.
@comment TROFF INPUT: .TP

@item 9
Designer.
@comment TROFF INPUT: .TP

@item 10
Description.
@comment TROFF INPUT: .TP

@item 11
Vendor URL.
@comment TROFF INPUT: .TP

@item 12
Designer URL.
@comment TROFF INPUT: .TP

@item 13
License description, in plain language.
@comment TROFF INPUT: .TP

@item 14
License info URL.
@comment TROFF INPUT: .TP

@item 18
Compatible full name; Macintosh only.
@comment TROFF INPUT: .TP

@item 19
Sample text.
@comment TROFF INPUT: .RE

@end table

@c ---------------------------------------------------------------------

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH EXAMPLE

@end table

@c ---------------------------------------------------------------------

@node hex2otf FONTFORGE NOTE
@subsection hex2otf FONTFORGE NOTE

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 @code{format=cff} option).  This is caused by
the presence of the file @code{Adobe-Identity-0.cidmap}, which FontForge
interprets incorrectly to determine Unicode code point glyph mappings
if present.  This file is located in @code{/usr/share/fontforge/cidmap}
or a similar directory on GNU/Linux systems.  Removing or renaming
@code{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.

@c ---------------------------------------------------------------------

@node hex2otf EXAMPLE
@subsection hex2otf EXAMPLE
@c DEBUG: print_menu("hex2otf EXAMPLE")

Sample usage:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
@comment TROFF INPUT: .HP 6
@comment .HP 6
@code{hex2otf hex=unifont.hex pos=combining.txt \}
@comment TROFF INPUT: .br
@comment .br

@code{format=cff,gpos,gsub out=unifont.otf}
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "EXIT STATUS"

@node hex2otf EXIT STATUS
@subsection hex2otf EXIT STATUS
@c DEBUG: print_menu("hex2otf EXIT STATUS")

Status values are defined in @t{<stdlib.h>}.
The program exits with status EXIT@t{_}SUCCESS upon successful font generation,
or EXIT@t{_}FAILURE if an error occurred.  If an error condition is encountered,
@b{hex2otf} writes a brief diagnostic message to STDERR; in this event,
the state of the output font file will be undefined.
@comment TROFF INPUT: .SH SEE ALSO

@node hex2otf SEE ALSO
@subsection hex2otf SEE ALSO
@c DEBUG: print_menu("hex2otf SEE ALSO")

@comment TROFF INPUT: .BR unifont (5),
@b{unifont}@r{(5),}
@comment TROFF INPUT: .BR hex2bdf (1)
@b{hex2bdf}@r{(1)}
@comment TROFF INPUT: .SH AUTHOR

@node hex2otf AUTHOR
@subsection hex2otf AUTHOR
@c DEBUG: print_menu("hex2otf AUTHOR")

@comment TROFF INPUT: .B hex2otf
@b{hex2otf}
was written by
@image{he-zhixiang, 28pt, 8pt, He Zhixiang, .png}(He Zhixiang).
@comment TROFF INPUT: .SH LICENSE

@node hex2otf LICENSE
@subsection hex2otf LICENSE
@c DEBUG: print_menu("hex2otf LICENSE")

@comment TROFF INPUT: .B hex2otf
@b{hex2otf}
is Copyright @copyright{} 2022
@image{he-zhixiang, 28pt, 8pt, He Zhixiang, .png}(He Zhixiang).
@comment TROFF INPUT: .PP

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.

