##
##  fontface -- Font Preparation for Web usage via CSS @font-face
##  Copyright (c) 2010-2015 Ralf S. Engelschall <rse@engelschall.com>
##  Licensed under GPL <http://www.gnu.org/licenses/gpl.txt>
##  fontface.pod: Tool Manual Page (language: Perl/POD)
##

=pod

=head1 NAME

fontface - Font Preparation for Web usage via CSS @font-face

=head1 SYNOPSIS

B<fontface>
[B<-t>, B<--trace>]
[B<-v>, B<--verbose>]
[B<-o>, B<--outputdir> I<directory>]
[B<-O>, B<--outputformat> I<format>[,I<format>[,...]]
[B<-u>, B<--unicode> I<unicode-range>[,I<unicode-range>[,...]]]
[B<-x>, B<--scale> I<em-units>]
[B<-r>, B<--round>]
[B<-h>, B<--autohint>]
[B<-i>, B<--autoinst>]
[B<-s>, B<--simplify> I<em-units>]
[B<-k>, B<--nokerning>]
[B<-l>, B<--nolocal>]
[B<-f>, B<--family> I<name>]
[B<-F>, B<--fullfamily>]
[B<-p>, B<--prefix> I<name>]
[B<-W>, B<--force-weight> I<weight>]
[B<-Y>, B<--force-style> I<style>]
[B<-S>, B<--force-stretch> I<stretch>]
[B<-V>, B<--force-variant> I<variant>]
[B<--specimen> I<path-to-specimen>]
[B<--fontforge> I<path-to-fontforge>]
[B<--fontfixname> I<path-to-fontfixname>]
[B<--fontmodname> I<path-to-fontmodname>]
[B<--ttf2eot> I<path-to-ttf2eot>]
[B<--ttfautohint> I<path-to-ttfautohint>]
[B<--woff2compress> I<path-to-woff2compress>]
[B<--gzip> I<path-to-gzip>]
I<input-font>

=head1 DESCRIPTION

B<fontface> is a Unix command-line tool (and a small companion
JavaScript library) for converting an OpenType Font (OTF) or TrueType
Font (TTF) into appropriate formats for cross-browser use on the Web via
the CSS C<@font-face> selector. B<fontface> requires the font conversion
tools B<fontforge>(1), B<font-fixname>(1), B<ttf2eot>(1),
B<ttfautohint>(1), B<woff2_compress>(1) and the compression utility B<gzip>(1).

=head1 OPTIONS

=over 4

=item B<-t>, B<--trace>

Display the actually executed B<fontforge>(1) and B<ttf2eot>(1)
commands for performing the actual conversions.

=item B<-v>, B<--verbose>

Display verbose messages showing the processing steps.

=item B<-o>, B<--outputdir> I<directory>

Write all generated files to I<directory> instead of
the current working directory.

=item B<-O>, B<--outputformat> I<format>[,I<format>[,...]]

Generate various output formats. Default is C<ttf,eot,woff,svgz,css,html>.
The C<ttf> format is the regular and mandatory TrueType (TTF) font format.
The C<eot> format is the optional Embedded-OpenType (EOT) font format.
The C<woff> format is the optional Web-Open-Font-Format (WOFF) font format.
The C<svgz> format is the optional Scalable-Vector-Graphics (SVG compressed) font format.
The C<css> format is the optional Cascading-Style-Sheet (CSS) format for referencing
the font in the various formats.
The C<html> format is the optional Hyper-Text-Markup-Language (HTML) format for showing
the font in the specimen.

=item B<-u>, B<--unicode> I<unicode-range>[,I<unicode-range>[,...]]

Subset the I<input-font> by using only the glyphs corresponding the
specified Unicode ranges. The argument I<unicode-range> has to use
the syntax "I<n>C<->I<n>" or "I<n>". Examples: "C<00-7F>" (ASCII only),
"C<00-FF>" (ISO-Latin-1, the default) or "C<0000-FFFF>" (full
Unicode range, not recommended).

=item B<-x>, B<--scale> I<em-units>

Scale the font to I<em-units> instead of using the scaling of the
original I<input-font>. Example: "C<2048>".

=item B<-r>, B<--round>

Rounds all points/hints/reference-offsets to be integers. Useful
in combination with B<--scale>.

=item B<-h>, B<--autohint>

Throw away any existing hints for the glyphs and guess new ones
with the help of B<ttfautohint>(1).

=item B<-i>, B<--autoinst>

Produce TrueType instructions based on Type1 hints.
If the source is not a Type1 font, B<--autohint> is
usually also required as B<--autoinst> needs the hinting
information.

=item B<-s>, B<--simplify> I<em-units>

Simplify I<input-font> by reducing the number of curves as long as the
result is still within a treshold of I<em-units> maximum derivation to
the original. Example: "C<2>".

=item B<-k>, B<--nokerning>

Remove all kerning information.

=item B<-l>, B<--nolocal>

Do not output any CSS C<local('...')> specifiers with font names
(only the IE workaround specifier C<local('*')> is omitted).

=item B<-f>, B<--family> I<name>

Set the font encoded family names to I<name>. This is usually wished to
remove extra style information in family names, which is unnecessary
because this information is already present in dedicated fields.

=item B<-F>, B<--fullfamily>

Break the intentions of CSS and make C<font-family> fully qualified
by appending a 4-character "E<lt>style-weight-stretch-variantE<gt>"
extension to its end. This workarounds a bug in Opera and some Internet
Explorer which overload fonts of the same font family (last one or
first one just wins). Alternatively, and even better, you can use the
C<fontface.js> JavaScript library to fix the problem under run-time.

=item B<-p>, B<--prefix> I<name>

Prefix the font encoded names with "I<name> " and the font file name
with "I<name>C<->". This is usually a requirement imposed by certain
licenses, like the Open Font License (OFL) which considers a format
conversion to be a font modification and as a consequence requires a
name change.

=item B<-W>, B<--force-weight> I<weight>

Force the C<@font-face> attribute C<font-weight> to I<weight> in case it
cannot be determined correctly from the encoded information in the font
file.

=item B<-Y>, B<--force-style> I<style>

Force the C<@font-face> attribute C<font-style> to I<style> in case it
cannot be determined correctly from the encoded information in the font
file.

=item B<-S>, B<--force-stretch> I<stretch>

Force the C<@font-face> attribute C<font-stretch> to I<stretch> in case it
cannot be determined correctly from the encoded information in the font
file.

=item B<-V>, B<--force-variant> I<variant>

Force the C<@font-face> attribute C<font-variant> to I<variant> in case it
cannot be determined correctly from the encoded information in the font
file.

=item B<--specimen> I<path-to-specimen>

Use the HTML specimen template under path I<path-to-specimen>.

=item B<--fontforge> I<path-to-fontforge>

Use B<FontForge> (C<fontforge>) found under path I<path-to-fontforge>.

=item B<--fontfixname> I<path-to-fontfixname>

Use B<font-optimizer>'s C<font-fixname> under path I<path-to-fontfixname>.

=item B<--fontmodname> I<path-to-fontmodname>

Use B<font-optimizer>'s C<font-modify-names> under path I<path-to-fontmodname>.
(Only required for option B<--prefix>)

=item B<--ttf2eot> I<path-to-ttf2eot>

Use B<TTF2EOT> (C<ttf2eot>) found under path I<path-to-ttf2eot>.

=item B<--ttfautohint> I<path-to-ttfautohint>

Use TTFAutoHint (C<ttfautohint> found under path I<path-to-ttfautohint>.

=item B<--woff2compress> I<path-to-woff2compress>

Use WOFF2-Compress (C<woff2_compress> found under path I<path-to-woff2compress>.

=item B<--gzip> I<path-to-gzip>

Use B<GNU zip> (C<gzip>) found under path I<path-to-gzip>.

=back

=head1 EXAMPLE

 $ fontface --nolocal --unicode=U+00-FF --simplify=2 --outputdir=fonts Vera-Regular.ttf
 $ fontface --nolocal --unicode=U+00-FF --simplify=2 --outputdir=fonts Vera-Bold.ttf
 $ fontface --nolocal --unicode=U+00-FF --simplify=2 --outputdir=fonts Vera-Italic.ttf
 $ fontface --nolocal --unicode=U+00-FF --simplify=2 --outputdir=fonts Vera-BoldItalicttf

 $ cat sample.html
 <!DOCTYPE html>
 <html>
   <head>
     <link rel="stylesheet" type="text/css" href="fonts/Vera-Regular.css"/>
     <link rel="stylesheet" type="text/css" href="fonts/Vera-Bold.css"/>
     <link rel="stylesheet" type="text/css" href="fonts/Vera-Italic.css"/>
     <link rel="stylesheet" type="text/css" href="fonts/Vera-BoldItalic.css"/>
     <script type="text/javascript" src="fontface.js"></script>
     <style type="text/css">
     body {
         font-family: "Bitstream Vera Sans";
     }
     </style>
   </head>
   <body>
      <h1>Lorem Ipsum Dolor Sit Amet Quux</h1>
   </body>
 </head>

=head1 SEE ALSO

fontforge(1), font-fixname(1), font-modify-names(1), ttf2eot(1), ttfautohint(1), woff2_compress(1).

=head1 AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut

