dklibs(3)

NAME
dkfont - List of 35 well-known PS fonts

SYNOPSIS
  #include <dkfont.h>

  char      *dkfont_get_tex_name(size_t n);
  char      *dkfont_get_ps_name(size_t n);
  char      *dkfont_get_svg_family_name(size_t n);
  int        dkfont_get_features(size_t n);
  dk_font_t *dkfont_get_ps_fonts(void);

DESCRIPTION
The dkfont module contains a list of the 35 well-known PS fonts. The font listing contains LaTeX name, PS name and feature list for each font.

The enumeration order is the same as in the Fig file format specification.

Starting with dklibs version 1.11.0 there are data structures and functions for user-defined font mapping.

  Fixed font-mapping

*  char      *dkfont_get_tex_name(size_t n);
    returns the LaTeX name of the specified font.

* char      *dkfont_get_ps_name(size_t n);
    returns the PostScript name of the specified font.

* char      *dkfont_get_svg_family_name(size_t n);
    returns the font-family for use with SVG.

* int        dkfont_get_features(size_t n);
    returns the feature list of the specified font.

      size_t fontno;
      int i;
      fontno = 0; /* 0...34 */
      i = dkfont_get_features(fontno);
      switch(i & DK_FONT_FEATURE_FAMILY) {
        case DK_FONT_FEATURE_RM: {
          printf("Roman font.\n");
        } break;
        case DK_FONT_FEATURE_SF: {
          printf("Sans-serif font.\n");
        } break;
        case DK_FONT_FEATURE_TT: {
          printf("Type writer font.\n");
        } break;
        default: {
          printf("ERROR: Unknown font type\n");
        } break;
      }
      if(i & DK_FONT_FEATURE_BD) {
        printf("Bold/Oblique font.\n");
      }
      if(i & DK_FONT_FEATURE_IT) {
        printf("Italic font.\n");
      }

* dk_font_t *dkfont_get_ps_fonts(void);
    returns a pointer to the start of the array containing the list.

  User-defined font mapping

* typedef struct { ... } dk_font_mapping_t;
    contains the font mapping data for all the 35 PS fonts.

* typedef struct { ... } dk_one_font_mapping_t;
    contains the font mapping data for one PS font.

* typedef struct { ... } dk_font_replacement_t;
    contains data for one possible substitute of a PS font.

* dk_font_mapping_t *dk_font_mapping_open(void),
    creates a new empty dk_font_mapping_t structure. When finished with it, use dk_font_mapping_close() to release ressources.

* int dk_font_mapping_add_stream(dk_font_mapping_t *, dk_stream_t *);
    adds the contents of a font configuration file to the mapping data.

* void dk_font_mapping_close(dk_font_mapping_t *);
    closes the dk_font_mapping_t structure and releases the memory used by it.

* int dk_font_get_error_code(dk_font_mapping_t *);
    returns error code of the last error occured while dk_font_mapping_add_stream().

* unsigned long dk_font_get_error_lineno(dk_font_mapping_t *);
    returns the line number in which the error occured.

* dk_one_font_mapping_t *dk_font_get_one_font(dk_font_mapping_t *, size_t);
    retrieves a pointer to a dk_one_font_mapping_t structure for the PS font specified by number.

* void dk_font_set_used(dk_font_mapping_t *, size_t);
    marks the specified PS font as ``used by the document''.

* int dk_font_get_used(dk_font_mapping_t *, size_t);
    checks whether or not the specified PS font is ``used by the document''.

* void dk_font_one_font_reset(dk_one_font_mapping_t *);
    prepares the dk_one_font_mapping_t for traversing (retrieving all dk_font_replacement_t step by step).

* dk_font_replacement_t *dk_font_one_font_get(dk_one_font_mapping_t *);
    retrieves the next dk_font_replacement_t.

* char *dk_font_rep_get_name(dk_font_replacement_t *);
    returns the font name of the replacement.

* char *dk_font_rep_get_family(dk_font_replacement_t *);
    returns the font family name of the replacement.

* char *dk_font_rep_get_location(dk_font_replacement_t *);
    returns the directory part of the URL used to retrieve the replacement font.

* char *dk_font_rep_get_source_name(dk_font_replacement_t *);
    returns the filename part of the URL used to retrieve the replacement font.

* char *dk_font_rep_get_font_type(dk_font_replacement_t *);
    returns the font type (i.e. ``svg'' or ``pfb'') of the replacement font.

* char *dk_font_rep_get_tex_name(dk_font_replacement_t *);
    returns the TeX name of the replacement font.

* int dk_font_rep_get_features(dk_font_replacement_t *);
    returns the font features of the replacement font.

* int dk_font_rep_get_source_type(dk_font_replacement_t *);
    returns the source type of the replacement, either DK_FONT_RP_TYPE_SYSTEM for system fonts (ready for use, no download... necessary) or DK_FONT_RP_TYPE_DOWNLOAD (download, installation and further setup necessary...).

* int dk_font_rep_check_driver(dk_font_replacement *, char *);
    checks whether or not the replacement font can be used with the specified driver.

RETURN VALUE
Functions returning pointers return a valid pointer on success. A NULL pointer is returned to indicate that no matching character or substring was found.

FILES
The dk_font_mapping_add_stream() functions initializes a dk_font_mapping_t structure from a font configuration file. This configuration file consists of up to 35 sections, one section for each of the 35 PostScript fonts.

Each section is started by the PS font name in square brackets, the list of possible replacement fonts descriptions follows.

At the start of the a replacement font description there is a line ``name = name''. The remaining lines consists of key/value pairs, key and value are separated by ``=''.

The following keys can occur:

* source type
    specifies how applications can find the font. The source type is either ``system'' or ``download''. System fonts are installed on the system ready for use, applications can access these fonts by simply specifying the name. Download fonts are specified by URL.

* family
    specifies the name of the font family.

* features
    contains a list of font features:

    - font classification (``roman'', ``sans-serif'' or ``typewriter'')
    - font weight (``bold'' or none)
    - ``italic'' or none
* driver list
    is a list of output drivers which can use this replacement. The names are separated by whitespaces.

* directory
    specifies the directory part of the download URL.

* file name
    contains the file name part of the download URL.

* font type
    is used to specify the font type, i.e. ``svg'' or ``pfb''.

* tex name
    specifies the TeX name for the replacement font.

* pfb name
    specifies the file name (without leading directory) of a PFB font file.

* pfb base
    specifies the directory where to find the PFB font file. The directory may be either a local directory or a http://... URL.

* ttf name
    specifies the file name (without leading directory) of a TTF font file.

* ttf base
    specifies the directory where to find the TTF font file. The directory may be either a local directory or a http://... URL.

EXAMPLES

  Font configuration file example
The following excerpt from ``combfont.cfg'' shows how to configure font substituion for the PS fonts ``Times-Roman'' and ``Times-Italic'' on Windows systems. For both fonts applications should try Windows fonts first. If these fonts are not found, SVG viewers can attempt to use SVG variants of the GhostScript fonts.

        [Times-Roman]
        name    =       Times New Roman
                source type     =       system
                features        =       roman
                family          =       Times New Roman
                driver          =       *
        name    =       NimbusRomanNo9L-Regu
                source type     =       download
                directory       =       ./urw-svg
                file name       =       n021003l.svg
                features        =       roman
                family          =       Nimbus Roman No9 L
                driver          =       svg
                font type       =       svg
                pfb name        =       n021003l.pfb
                pfb base        =       http://my-server.my-domain.com/gs-fonts
        [Times-Italic]
        name    =       Times New Roman Kursiv
                source type     =       system
                features        =       roman italic
                family          =       Times New Roman
                driver          =       *
        name    =       NimbusRomNo9L-ReguItal
                source type     =       download
                directory       =       ./urw-svg
                file name       =       n021023l.svg
                features        =       roman italic
                family          =       Nimbus Roman No9 L
                driver          =       svg
                font type       =       svg
                pfb name        =       n021023l.pfb
                pfb base        =       http://my-server.my-domain.com/gs-fonts

AUTHOR
Dirk Krause

COPYRIGHT AND LICENSE
Copyright (c) 2001-2009, Dirk Krause All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.