
This file describes how to set up face mappings for Screen and
PostScript fonts via resource configuration. The system described
below is most likely overkill; it was designed in an attempt to handle
especially complex X font mappings.

As an implementor for a MrEd-based program, you may find that it's
easier to use the `set-screen-name', `set-post-script-name', and
`set-afm-name' methods provided by `the-font-name-directory'. As a
user of a MrEd-based program, resources provide a back door for
setting default mappings.

Whether a programmer or a user, see `font-name-directory<%>' in _PLT
MrEd: Graphical Toolbox Manual_ for an overview of the font mapping
system. The information in the manual is rechnically incorrect,
because it does not explain how resources can affect font mappings.



Resources
=========

The 'setup-file argument to `find-graphical-system-path' returns the
name of a file used to define resources. Under X, in addition to this
file, resources can be defined via the standard resource database
(e.g., through an ".Xresources" file).

The format of a resource entry depends on the platform. Windows
resources use the standard .INI format, with a "mred" section. X
resources use the standard X resource format, with a "mred"
family. MacOS resource entires consist of the resource name, a colon,
and the reource value, terminated by a newline.



Font Resources
==============

To find a font name for a family in the resource, MrEd looks for a
resource item named by:

  <dest><type><weight><style>

where

  <dest> is either "Screen" or "PostScript"
  <type> is either "Default", "Decorative", "Roman", "Script",
         "Swiss", "Modern"", "System", or "Symbol" for a mapping
         defining the default font for a family. Otherwise, it is a
         face name prefixed with "@"
  <weight> is either "Medium", "Bold", or "Light"
  <style> is either "Straight", "Italic", or "Slant"

Furthermore, any of the latter three parts can be wilcarded with "_",
as described below.

The value of the resource is parsed as desribed in _PLT MrEd:
Graphical Toolbox Manual_ for parsing face names, except that the
string can contain references and other tricks described below.


Wildcards
---------

Building items names by <dest><type><weight><style> can create a large
number of resource entires, and the <weight><style> part is only
useful for X Windows screen fonts. To avoid an explosion of resource
entires, MrEd finds resource items via a wildcarding search.

The <type>, <weight>, and <style> parts of a resource name can
be wildcarded by using "_". Thus, to set the default font for all
types, weights, and styles, use this X resource entry:

 mred.Screen___: +-*-*-medium-r-normal-*-*-%d-*-*-*-*-*-*

Wildcarded resource entires are used only when un-wildcarded values
cannot be found. If two resource names both match for some search,
then the one with the "earliest" (i.e., closest to the beginning of
the resource name) non-wildcarded part will prevail.

The default MrEd resource file for Windows uses wildcarding to
specify the basic font mapping:

 [mred]
 ScreenSystem__=MS Sans Serif
 ScreenRoman__=Times New Roman
 ScreenDecorative__=Modern
 ...

Wildcarding in the resource name naturally leads to references,
parameterizations, and wildcarding References in the resource value.

References
- - - - - 

Suppose we define the mapping for variants of "Default", and then we
want "Roman" to use this setting, too. We could copy the resource
entry, as in the following example:

 mred.ScreenDefault__: +-*-*-medium-r-normal-*-*-%d-*-*-*-*-*-*
 mred.ScreenRoman__: +-*-*-medium-r-normal-*-*-%d-*-*-*-*-*-*

but the MrEd font-reading system provides a better syntax for
referencing another resource entry. When a resource value contains
"${x}", then the "${x}" fragment is replaced by the resource value of
"x". Thus, the above can be re-written:

 mred.ScreenDefault__: +-*-*-medium-r-normal-*-*-%d-*-*-*-*-*-*
 mred.ScreenRoman__: ${ScreenDefault__}

Parameterizations
- - - - - - - - -

Parameterization can be used with referencing to parameterize default
values based on the weight and style that is needed.  When a resource
value contains "$[weight]", then "$[weight]" is replaced with a string
for the desired font weight. Similarly, "$[style]" is replaced with
the desired style. Parameterizing expressions can be embedded within 
referencing expressions, as in the following example:

  mred.ScreenDefault__: +-*-*-${Def$[weight]}-r-normal-*-*-%d-*-*-*-*-*-*
  mred.DefMedium: medium
  mred.DefBold: bold
  mred.DefLight: medium

Now, when the "ScreenDefault__" resource is used for different weights,
it will return different values; the "${Def$[weight]}~ expression will
turn into "${DefMedium}" for a medium-weight lookup, or "${DefBold}"
for a bold-weight lookup. These references will in turn give either
"medium" or "bold".

Wildcarding References
- - - - - - - - - - - 

Consider the following resource configuration:

  MrEd.ScreenDefault__: +-*-*-medium-r-normal-*-*-%d-*-*-*-*-*-*
  MrEd.ScreenDefaultBold_: +-*-*-bold-r-normal-*-*-%d-*-*-*-*-*-*
  MrEd.ScreenRoman__: ${ScreenDefault__}

The effect of this statement is probably not what was intended; when a
bold version of the "Roman" font is needed, "ScreenRoman__" references
"ScreenDefault__", which does not specify a bold font.  We could try
to remedy the situation as follows:

  MrEd.ScreenDefault__: +-*-*-medium-r-normal-*-*-%d-*-*-*-*-*-*
  MrEd.ScreenDefaultBold_: +-*-*-bold-r-normal-*-*-%d-*-*-*-*-*-*
  MrEd.ScreenRoman__: ${ScreenDefault$[weight]_}

but this does not work either. It works fine for bold "Roman", now, 
but medium "Roman" will cause a reference to "ScreenDefaultMedium_",
which doesn't exist. The problem is that our reference does not use
wildcarding like the original medium "Roman" lookup did.

Wildcarding can be specified in a reference by separating each
wildcardable field with a comma. The following resource specification
does what we want:

  MrEd.ScreenDefault__: +-*-*-medium-r-normal-*-*-%d-*-*-*-*-*-*
  MrEd.ScreenDefaultBold_: +-*-*-bold-r-normal-*-*-%d-*-*-*-*-*-*
  MrEd.ScreenRoman__: ${ScreenDefault,$[weight],_}

Since "$[weight]" is between commas, it can be wildcarded if no name
exactly matching "SchemeDefault$[weight]_" is found. In this case
"SchemeDefault" and "_" can also be wildcarded, but this will have no
effect.

The wildcarding used in references need not reflect the wildcarding
MrEd initial uses for finding fonts. In other words, an number of
comma-separated selects can appear between the curly braces.


Internal Resources
------------------

The initial font setup is built into MrEd through a built-in resource
table. The table is shown at the end of this file. When font
information is computed, it is *almost* as if this table were
installed into your resources file; the difference is that resource
specifications in your file override specifications in the built-in
table, even when the wildcarding of your resource provides a weaker
match.


Lookup Failures
-------------------

When no information is available for mapping a face name to a font,
MrEd falls back to the system described in _PLT MrEd: Graphical
Toolbox Manual_. (Since a mapping is built into MrEd for every family,
information is always available for the default font of a family.)



Built-in Resources
==================

  PostScriptMediumStraight: 
  PostScriptMediumItalic: -Oblique
  PostScriptMediumSlant: -Oblique
  PostScriptLightStraight: 
  PostScriptLightItalic: -Oblique
  PostScriptLightSlant: -Oblique
  PostScriptBoldStraight: -Bold
  PostScriptBoldItalic: -BoldOblique
  PostScriptBoldSlant: -BoldOblique

  PostScript___: ${PostScript$[family],$[weight],$[style]}

  PostScriptSystem__: ${PostScriptTimes,$[weight],$[style]}
  PostScriptDefault__: ${PostScriptTimes,$[weight],$[style]}
  PostScriptRoman__: ${PostScriptTimes,$[weight],$[style]}
  PostScriptDecorative__: ${PostScriptTimes,$[weight],$[style]}
  PostScriptScript__: ${PostScriptTimes,$[weight],$[style]}

  PostScriptTimesMedium: 
  PostScriptTimesLight: 
  PostScriptTimesBold: Bold

  PostScriptTimes__: Times${PostScript$[weight]$[style]}
  PostScriptTimesMediumStraight: Times-Roman
  PostScriptTimesLightStraight: Times-Roman
  PostScriptTimes_Slant: Times-${PostScriptTimes$[weight]}Italic
  PostScriptTimes_Italic: Times-${PostScriptTimes$[weight]}Italic

  PostScriptSwiss__: Helvetica${PostScript$[weight]$[style]}
  PostScriptModern__: Courier${PostScript$[weight]$[style]}
  PostScriptSymbol__: Symbol

X only:

  ScreenMedium: medium
  ScreenBold: bold
  ScreenLight: light
  ScreenStraight: r
  ScreenItalic: i
  ScreenSlant: o

  ScreenSystemBase: *-lucida
  ScreenDefaultBase: *-lucida
  ScreenRomanBase: *-times
  ScreenDecorativeBase: *-helvetica
  ScreenModernBase: *-courier
  ScreenSwissBase: *-lucida
  ScreenScriptBase: *-zapfchancery
  ScreenSymbolBase: *-symbol

  ScreenStdSuffix: -${Screen$[weight]}-${Screen$[style]}-normal-*-*-%d-*-*-*-*-*-*

  ScreenSystem__: +-${ScreenSystemBase}${ScreenStdSuffix}
  ScreenDefault__: +-${ScreenDefaultBase}${ScreenStdSuffix}
  ScreenRoman__: +-${ScreenRomanBase}${ScreenStdSuffix}
  ScreenDecorative__: +-${ScreenDecorativeBase}${ScreenStdSuffix}
  ScreenModern__: +-${ScreenModernBase}${ScreenStdSuffix}
  ScreenSwiss__: +-${ScreenSwissBase}${ScreenStdSuffix}
  ScreenScript__: +-${ScreenScriptBase}${ScreenStdSuffix}
  ScreenSymbol__: +-${ScreenSymbolBase}-medium-r-normal-*-*-%d-*-*-*-*-*-*

Windows only:

  ScreenSystem__: MS Sans Serif
  ScreenDefault__: MS Sans Serif
  ScreenRoman__: Times New Roman
  ScreenDecorative__: Arial
  ScreenModern__: Courier New
  ScreenSwiss__: Arial
  ScreenScript__: Arial
  ScreenSymbol__: Symbol

MacOS only:

  ScreenDefault__: applicationfont
  ScreenSystem__: systemfont
  ScreenRoman__: times
  ScreenDecorative__: geneva
  ScreenModern__: monaco
  ScreenSwiss__: helvetica
  ScreenScript__: geneva
  ScreenSymbol__: symbol
