=head1	NAME

dkfont - List of 35 well-known PS fonts

=head1	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);

=head1	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.

=head2	Fixed font-mapping

=over	2

=item *  char      *dkfont_get_tex_name(size_t n);

returns the LaTeX name of the specified font.

=item * char      *dkfont_get_ps_name(size_t n);

returns the PostScript name of the specified font.

=item * char      *dkfont_get_svg_family_name(size_t n);

returns the font-family for use with SVG.

=item * 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");
  }

=item * dk_font_t *dkfont_get_ps_fonts(void);

returns a pointer to the start of the array containing
the list.

=back

=head2	User-defined font mapping

=over	2

=item	* typedef struct { ... } dk_font_mapping_t;

contains the font mapping data for all the 35 PS fonts.

=item	* typedef struct { ... } dk_one_font_mapping_t;

contains the font mapping data for one PS font.

=item	* typedef struct { ... } dk_font_replacement_t;

contains data for one possible substitute of a PS font.

=item	* 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.

=item	* 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.

=item	* void dk_font_mapping_close(dk_font_mapping_t *);

closes the dk_font_mapping_t structure and releases the memory used by it.

=item	* int dk_font_get_error_code(dk_font_mapping_t *);

returns error code of the last error occured while
dk_font_mapping_add_stream().

=item	* unsigned long dk_font_get_error_lineno(dk_font_mapping_t *);

returns the line number in which the error occured.

=item	* 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.

=item	* void dk_font_set_used(dk_font_mapping_t *, size_t);

marks the specified PS font as ``used by the document''.

=item	* int dk_font_get_used(dk_font_mapping_t *, size_t);

checks whether or not the specified PS font is ``used by the document''.

=item	* 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).

=item	* dk_font_replacement_t *dk_font_one_font_get(dk_one_font_mapping_t *);

retrieves the next dk_font_replacement_t.

=item	* char *dk_font_rep_get_name(dk_font_replacement_t *);

returns the font name of the replacement.

=item	* char *dk_font_rep_get_family(dk_font_replacement_t *);

returns the font family name of the replacement.

=item	* char *dk_font_rep_get_location(dk_font_replacement_t *);

returns the directory part of the URL used to retrieve the replacement font.

=item	* char *dk_font_rep_get_source_name(dk_font_replacement_t *);

returns the filename part of the URL used to retrieve the replacement font.

=item	* char *dk_font_rep_get_font_type(dk_font_replacement_t *);

returns the font type (i.e. ``svg'' or ``pfb'') of the replacement font.

=item	* char *dk_font_rep_get_tex_name(dk_font_replacement_t *);

returns the TeX name of the replacement font.

=item	* int dk_font_rep_get_features(dk_font_replacement_t *);

returns the font features of the replacement font.

=item	* int dk_font_rep_get_source_type(dk_font_replacement_t *);

returns the source type of the replacement, either
B<DK_FONT_RP_TYPE_SYSTEM> for system fonts (ready for use, no download...
necessary) or B<DK_FONT_RP_TYPE_DOWNLOAD> (download, installation and
further setup necessary...).

=item	* int dk_font_rep_check_driver(dk_font_replacement *, char *);

checks whether or not the replacement font can be used with the specified
driver.

=back

=head1	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.

=head1	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 = I<name>''. The remaining lines consists
of key/value pairs, key and value are separated by ``=''.

The following keys can occur:

=over	2

=item	* 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.

=item	* family

specifies the name of the font family.

=item	* features

contains a list of font features:

=over	4

=item	- font classification (``roman'', ``sans-serif'' or
``typewriter'')

=item	- font weight (``bold'' or none)

=item	- ``italic'' or none

=back

=item	* driver list

is a list of output drivers which can use this replacement. The
names are separated by whitespaces.

=item	* directory

specifies the directory part of the download URL.

=item	* file name

contains the file name part of the download URL.

=item	* font type

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

=item	* tex name

specifies the TeX name for the replacement font.

=item	* pfb name

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

=item	* pfb base

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

=item	* ttf name

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

=item	* ttf base

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

=back

=head1	EXAMPLES

=head2	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

=head1	AUTHOR

Dirk Krause

=head1	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.
