/**
@page xml_font Font XML files.
@author Paul D Turner

Font files can define one of two types of font:
- A FreeType font, which is based upon standard font files - such as .ttf
  files - where glyphs get dynamically rendered to an internal cache as needed.
- A Pixmap font, which is based on an Imageset that contains the predrawn bitmap
  representations of the character glyphs the font will render.

<br>
@section xml_font_overview Overview
The reference for each element is arranged into sections, as described below:
- Purpose:
    - This section describes what the elements general purpose is within the
      specifications.

- Attributes:
    - This section describes available attributes for the elements, and whether
      they are required or optional.

- Usage:
    - Describes where the element may appear, whether the element may have
      sub-elements, and other important usage information.

- Examples:
    - For many elements, this section will contain brief examples showing the
      element used in context.

<br>
@section xml_font_font \<Font\> Element
- Purpose:
    - The \<Font\> element is the root element in XML font definition files.

- Attributes:
    - @c Type: Specifies the type of font being defined.  This should be one of
      the following values:
        - @c FreeType: Indicates a font based upon a standard font file (such as
          a true-type '.ttf' font).
        - @c Pixmap: Indicates a font based upon an Imageset which defines
          Images for the font glyphs.
    - @c Name: Specifies the name that will be used to identify the Font within
      the CEGUI system.  Required attribute.
    - @c Filename: Specifies the path to the associated resource for the font.
      Required attribute.
        - For FreeType type fonts this should reference a standard font file
          loadable by the freetype2 library (such as a .ttf file, or similar).
        - For Pixmap type fonts this should reference an an Imageset.
    - @c ResourceGroup: Specifies the resource group identifier to pass to the
      ResourceProvider when loading the file given in the @c Filename attribute.
      For Pixmap type fonts, this may be the special value @c "*" to indicate
      the Imagseset specified in @c Filename is actually the name of an already
      loaded Imagesest rather than the name of an Imageset XMl file to be
      loaded.  Optional attribute.
    - @c Size: Specifies the point size for a FreeType type font.  This is
      ignored for Pixmap type fonts.  Optional attribute, default is 12.
    - @c AntiAlias: Boolean attribute that states whether the font should be
      rendered anti-aliased.  This setting only affects FreeType type fonts.
      Optional attribute, default is true.
    - @c AutoScaled: Boolean attribute that states whether to scale imagery so
      it appears the same @e physical size at any resolution.  The specified
      native resolution values indicate the resolution that will result in a
      one-to-one (i.e. unscaled) mapping from source to destination.  At
      resolutions higher than the native, the imagery will be scaled @e up to
      take up more space, and at resolutions lower than the native, the imagery
      will be scaled @e down to take up less space.
      Optional attribute, default is false.
    - @c NativeHorzRes: When AutoScaled is enabled, specifies the horizontal
      screen resolution that will result in an unscaled, one-to-one mapping of
      pixels from the source image to the destination surface.
      Optional attribute, default is 640.
    - @c NativeVertRes: When AutoScaled is enabled, specifies the vertical
      screen resolution that will result in an unscaled, one-to-one mapping of
      pixels from the source image to the destination surface.
      Optional attribute, default is 480.
    - @c LineSpacing: Specifies a line spacing value to be used in preference
      to what is extracted from the underlying font file (useful if the font
      file is made with a bad line spacing value).  If set to zero, the value
      from the underlying font file is used instead.  This setting only affects
      FreeType type fonts.
      Optional attribute, default is 0.

- Usage:
    - The \<Font> element is the root element for font files.
    - The \<Font> element may contain any number of \<Mapping> elements.
    - No element may contain a \<Font> element as a sub-element.

- Examples:

<br>
@section xml_font_mapping \<Mapping\> Element
- Purpose:
    - The \<Mapping\> element is used only with Pixmap type fonts and defines a
      mapping between a UTF32 codepoint value and an Image defined on the
      associated Imageset.  A Mapping must be supplied for each codepoint that
      the font is to have available for rendering.

- Attributes:
    - @c Codepoint: Specifies the Unicode codepoint to produce a mapping for.
      Required attribute.
    - @c Image: Specifies the name of the image to map to the codepoint
      specified in @c Codepoint.  This named image must be defined for the
      Imageset identified in the @c Filename attribute of the containing
      \<Font\> element.
    - @c HorzAdvance: Specifies a number of pixels to advance the 'pen' position
      after rendering the image specified in this mapping.  A value of -1 will
      cause an appropriate value to be auto-calculated.
      Optional attribute, default is -1.

- Usage:
    - The \<Mapping\> element may only appear as a sub-element of the \<Font>
      element.
    - The \<Mapping\> element may not contain any sub-elements.

- Examples:


*/
