//
// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description: 


DOCUMENTATION FOR FNTTRAN.EXE
=======================

(This has been updated as of 041)

Summary
======
FNTTRAN takes multiple arguments; a series of input ASCII files each containing a bitmap font in BDF format, 
followed by a .GD file that details how the bitmap fonts are collected into typefaces. This creates the font store 
file (with extension GDR) that will be put into the \SYSTEM\FONTS directory on 
a machine running EPOC32.

For example: FNTTRAN FONT1.BDF FONT2.BDF FONT3.BDF EON14.GD
will produce EON14.GDR

Version 041 introduced font metric font compression.

Details
====
In general, a font collection will be made up of many individual font bitmaps, each 
described in a separate file. The .GD file adds information about the typefaces
and the final font-store file::

---------------------------------------------------------------------

Typeface Rom 
   Name "Roman" Proportional // The name of the typeface that the user will see
   FontBitmaps
      rom11 // These names must match font bitmap names in the BDF/GDF files
      rom14
   EndFontBitmaps
EndTypeface

FontStoreFile
   CollectionUid 99999999
   CopyrightInfo
        "Copyright xxx"
   EndCopyrightInfo
   Typefaces
      Rom
   EndTypefaces
EndFontStoreFile
----------------------------------------------------------------------

In the above example, only one typeface is included, but this can be extended to 
multiple typefaces, each with a variety of heights and bold/italic characteristics 
(defined in the individual BDF files). The final font-store file collects up the 
individual typefaces, adds a collection uid and copyright information.

BDF Format
=======
This is as BDF V2.2 but without the support for multiple writing directions as this is 
not supported by EPOC32. The characters must be listed in order of Unicode encoding.
The name of the font (following FONT) is the label used to indentify the individual 
font bitmap when the typefaces are constructed. 
Some additional keyword should be supplied in the PROPERTIES section of the BDF 
file however.

STARTPROPERTIES 3
UID 999999      // A uid enabling the font bitmap to be requested 
MAXNORMALCHARWIDTH 12 // The maximum normal width of characters in pixels.
MAXCONSECUTIVEFILLCHARS 0
FONTASCENT 9
FONTDESCENT 2
ENDPROPERTIES

The MAXCONSECUTIVEFILLCHARS is optional and controls whether 
breaks are made between code sections when there are missing characters in the 
input BDF file.

The FONTASCENT and FONTDESCENT keywords are optional (but, if present, BOTH must be present). If present they are used to calculate the font height. If not present it is done using the height of the font bounding box (as it was up until v039). Since the ascent and descent of the font are less likely to vary between stylistic variants of a single typeface at a single size, it is less likely to produce duplicate entries with apparently the same size in the font lists (the variants actually are different fractional values that round to the same integer for display).

The order of any of these keywords within the properties section is irrelevant.

The prescence of other keywords in the properties section is ignored. However, we recommend that you leave them there rather than edit them oout of the file. These keywords are automatically generated by various font foundries with additional font information and the exact set and the exact names vary from one font supplier to another but the values in them may be useful if future developments require us to take account of additional font information (if we are lucky it will be contained in these additional keywords). Any keywords in the properties section that we are not explicitly looking for will be ignored and they will not increase the size of the font files made by FNTTRAN.

GDF Format
=======
This format is deprecated
GDF files are files produced by FONTCOMP from FSC or EFF format.