RTF files need to specify which encoding a font to be used is using and what properties it has. This is used by a rendering application to determine the best matching font on a platform where the exact specified font is not available. Additionally, the encoding a font is in is used by the rendering application to correctly interpret the characters found in the RTF file.
However, this mechanism does not support custom fonts with a special mapping of their constituing characters to a Unicode codepoint. This is what the stdfonts.config file is for. upCast comes with a default file embedded in the application JAR. You may extend and/or override it by providing a custom stdfonts.config file, to be located in the {Encodings Folder}. Here, you can specify standard font properties based on the font name, specifically any custom encoding resp. codepage this font uses..
stdfonts.config can be found at the following location in the package hierarchy in the downcast.jar JAR file:
{JAR Resource Location Path}/config/stdfonts.config
You can modify this file to your liking and requirements, or supply an override file in the location mentioned above. Follows an informal description of the file format and the necessary properties, followed by the search algorithm used by upCast to find the properties for a given font in a CSS-like rule.
The following special properties are used in the stdfonts.config file:
Determines the general RTF font family a font belongs to based on its design. An RTF rendering application will use this information to find a font with similar appearance when an exact match cannot be found.
Supported values: roman, swiss, symbol, modern, script, decor, tech, bidi
This indicates the Windows codepage the font uses for its encoding.
Supported values: codepageAsInteger, -1, 10000, -1000, -1001, -1002, -1004
The special values have the following meaning:
Uses the default encoding. This is the best choice for normal fonts.
Identifies the Mac Roman encoding.
Identifies the Private Use Area mapper.
Identifies the standard encoding of the Symbol font.
Identifies the encoding of the Wingdings font.
Identifies the encoding of the Zapf Dingbats font.
Specifies the Unicode codepoint offset for this particular font. On platforms like Macintosh and Windows, fonts that have no Unicode mapping defined like Webdings or Hoefler Text Ornaments, will be mapped 1:1 into the PUA. Normally, this is the area of U+F000…U+F0FF, but by using the U-xxxx notation below, you can set the offset anywhere you require.
Supported values: normal | private | U-xxxx
with private being equivalent to U-F000, which is the Unicode codepoint offset (should be in the Private Use Area (PUA)) where this mapping starts, and normal being equivalent to U-0000, which is also the default if the property is not specified.
This property is only relevant for downCast, upCast's companion product.
When downCast encounters a Unicode character to render to RTF, it first looks whether this character is part of the encoding of the current font. If it is, it is written according to RTF specifications. However, when this Unicode character is not part of the encoding of the current font, downCast tries to look up a font in the names specified using the @font-search-list option in order. The first one it finds will be used to write the character to RTF. However, for a subsequent RTF reader to pick this up correctly, downCast must write a switch of font for this specific character. This property specifies which method downCast should use for this, if possible:
downCast will write a simple RTF font switch {\fx c}.
downCast will write the character using a SYMBOL field. This is only possible for single-byte-fonts.
downCast decides how to best write the character.
This property is only relevant for downCast, upCast's companion product.
When downCast needs to write a character, it can do it in two ways: either just the character for the current font's encoding, or additionally as the original Unicode codepoint. By specifying one of the following values for a font, you can tell upCast which method it should use )if possible):
downCast will always write the character in the current encoding and its Unicode equivalent
downCast will not write the Unicode equivalent
downCast decides how to best write the character.
This property is only relevant for downCast, upCast's companion product.
The following general options are available:
lets you specify a comma-separated list of font names in which downCast will search for an incoming Unicode character to be output to RTF if it is not part of the current encoding. This lets you specify precedences, e.g. you may want to list the actually installed fonts on your particular system first. If downCast does not find a match in the listed fonts, it will try all fonts defined in stdfonts.config. If it then still does not find a match, it will use Unicode notation with an underscore '_' as replacement character.
The file structure is line based. Each line identifies a set of font names with a set of properties:
fontlist ::= propertyset
fontlist ::= font ( ', ' font)*
font ::= fontname | '"' fontname '"'
propertyset ::= '\-ilx-rtf-font-family: ' ffval '; \-ilx-codepage: ' [0-9]+ ';'
' \-ilx-unicode-offset: ' uoval '; \-ilx-renderhint-fontswitch: ' rhfs '; \-ilx-renderhint-unicode: ' rhuc ';'
ffval ::= 'roman' | 'swiss' | 'symbol' | 'modern' | 'script' | 'decor' | 'tech' | 'bidi'
uoval ::= 'normal' | 'private' | 'U-' [0-9A-F]{4}
rhfs ::= 'font' | 'field' | 'auto'
rhuc ::= 'always' | 'never' | 'auto'
fontname ::= name of fontNote that you must use CSS style escapes (or numerical character entities of the form &#...;) to generate Unicode characters for specifying font names using characters outside the ASCII range. Examples for this can be seen in the file packaged default stdfonts.config file.
All lines starting with // denote a comment line, as do empty lines.
To avoid having to explicitly define every font in the stdfonts.config file which might ever occur in a stylesheet, upCast employs a multi-stage search algorithm for a matching property definition entry as follows:
First, a potentially existing user supplied stdfonts.config is prepended to the default one supplied by upCast. Within this concatenated, big file, the following search algorithm is employed:
A search for the exact name (considering case) is performed. The first matching entry is is used if it exists.
A search for the exact name, but ignoring case, is performed. The first matching entry is is used if it exists.
A search for a font name is performed that matches the start of the actual name. So if the characteristics for "Univers Bold" are requested, and there is an entry "Univers" in stdfonts.config, then its properties are used. Case is ignored.
A search for a font name is performed that is contained in the actual name. So if the characteristics for "L Univers 44" are requested, and there is an entry "Univers" in stdfonts.config, then its properties are used because the string "Univers" is contained in the actual font name. Case is ignored.
upCast comes complete with virtually all default encodings you can use in RTF resp. Word, including many two-byte ones. This means that normally, you do not need to provide a custom encoding.
The default encodings are hard-coded with optimizations done for each specific encoding to provide efficient access, since the mapping functions are called for each character that passes through upCast. These default encodings are therefore not directly user-accessible. However, there are sometimes occasions where you'll need to use a custom encoding, especially when you are using custom fonts.
upCast provides a custom encoding loader and handler which lets you specify your own mappings from character codepoint in the font to Unicode by means of a simple text file. Both, one-byte and two-byte encodings can be specified in this way.
To create a custom encoding, you need to create an ASCII text file with the extension .encoding which specifies both the mapping of the individual codepoints to Unicode and also states which codepage it implements. You can also give it a name for easily spotting it in the UI portions of the application. upCast looks for custom encoding files in the {Encodings Folder} at startup. All encodings it finds are added to the internal set of default encodings. By specifying a codepage in a custom encoding that has a default equivalent, you may override any of the factory-supplied encodings.
Since the mapping is built on the fly, specific optimizations cannot be performed and the use of custom encodings may slow-down processing slightly.
A custom encoding per se is not tied to anything but the codepage it implements. To tie a codepage to a specific font, you need to extend or override the stdfonts.config file. In this mapping file, you simply list the font's name and associate it with a codepage using the keywords as described.
It is recommended to use codepage values greater than 40000 for custom encodings, as upCast will not use these codepages internally. Which you use for custom encodings is up to you. upCast reserves the range from 32000 to 35000 for internal use, so you should not use these. Also note that when you override a default encoding, every font that is specified to use that encoding will use the custom one.
File names can be arbitrary, must however have an extension of .encoding. They should be placed into the {Encodings Folder} for downCast to scan and load them automatically at startup.
The file structure is simple: one mapping entry per line, and all lines starting with #, // or ; are treated as comments. To create a two-byte encoding, separate the two bytes by a comma.
A mapping entry has the form (notation similar to BNF):
mapping ::= <srcbyte> [',' <srcbyte>] '=' <unicodechar>
with:
srcbyte ::= hexNumber | decimalNumber
unicodechar ::= hexNumber | decimalNumber
hexNumber ::= ('0x' | '0X' | '$')[0-9A-Fa-f]+
decimalNumber ::= [0-9]+Follows a rather silly example, which maps what in codepage 1252 fonts is a space to the at-sign:
@codepage 42001 @encodingname Silly Encoding $20=$40
Options. Two special options are supported:
This specifies the codepage this encoding represents.
You can specify either an existing encoding to override its definition, or create custom codepages for specific fonts, in which case you should choose codepage number higher than 40000.
This is a descriptive name for the encoding so you can easily spot it in downCast's UI.
It is recommended to use codepage values greater than 40000 for custom encodings, as upCast will not use these codepages internally. Which you use for custom encodings is up to you.
upCast reserves the range from 32000 to 35000 for internal use, so you should not use these. Also note that when you override a default encoding, every font that is specified to use that encoding will use the custom one.
upCast has a built-in mechanism for converting any Unicode character to any other Unicode character or even entity notation on export. This is done by means of a Unicode translation map, which is a plain ASCII text file. You can specify a Unicode translation map in various export filters as the final stage a character needs to pass before actually getting written to the output file or stream.
The file structure is simple: one conversion entry per line, and all lines starting with #, // or ; are treated as comments.
A conversion entry has the form (notation similar to BNF):
conversion ::= unicodeNumber '=' replacement
with:
unicodeNumber ::= hexNumber | decimalNumber
replacement ::= string | hexNumber | decimalNumber
hexNumber ::= ('0x' | '0X' | '$')[0-9A-Fa-f]+
decimalNumber ::= [0-9]+
string ::= '"' (asciiChar)* '"'
asciiChar ::= a one-byte character in the range from 32 to 127, excluding '"'Follows a rather silly example, with the effect added in comments:
// First, we simply convert all spaces to a dot: 32="." // Then, we convert all capital letter A's to a // full, empty tag: <letter_a /> 65="<letter_a />" // And then, we discard all small // letters 'u' completely: 0x75=""
Options. There is one special option to specify default behaviour:
This specifies how a certain range of codes should be preset. This saves you typing if you need some range of characters not be specified in UTF-8 encoding, but e.g. as character references.
You can specify this option anywhere in a Unicode translation map, it takes effect at that specific location. You may use this to initialize a certain coderange and then overwrite selected codepoints by specifying additional, normal translation rules as described above, which will then override the initialization performed by this option.
An integer value specifying the start codepoint of the code range.
An integer value specifying the end codepoint of the range.
A string constant identifying the algorithm to use for filling the specified code range.
The code range is filled with character entities in decimal notation, e.g. Ӓ .
The code range is filled with character entities in decimal notation, e.g. Ӓ .
@option-default-mapping 128 32767 decimalNumericalEntities
This line fills the Unicode translation map fro all codepoints from 128 to 32767 (incl.) with numerical character entities.
This table associates arbitrary CSS <length> properties with a pair of unit and precision information. This is useful when the created style information in either the CSS stylesheet or the style overrides in the XML output should be human readable, in which case you would provide a table with a unit of measurement that people are most familiar with (inches or centimeters, e.g.), and a reasonable precision like 2 decimal digits.
The default table uses cm as default unit, with a precision of 1 or 2 decimal digits, and pt for special properties like font-size.
The file structure is simple: one unit association entry per line, and all lines starting with // are treated as comments.
Options. There are two special options to specify default behaviour:
This specifies the default unit to use for all <length> units not specified explicitly in the unit table.
This specifies the default precision to be used for all <length> units not specified explicitly in the unit table.
These options must be specified before any unit association for a specific CSS property.
Here's an example of a CSS property unit table similar to the one used as the default table in upCast:
@option-default-length-unit:mm @option-default-length-precision:2 font-size:pt,1 border-top-width:pt,1 border-right-width:pt,1 border-bottom-width:pt,1 border-left-width:pt,1 -ilx-border-vertical-inside-width:pt,1 -ilx-border-horizontal-inside-width:pt,1 text-indent:mm,1 width:mm,1 height:mm,1 margin-left:mm,1 margin-right:mm,1 margin-top:mm,1 margin-bottom:mm,1 padding-left:mm,1 padding-right:mm,1 padding-top:mm,1 padding-bottom:mm,1 line-height:pt,1 border-spacing:pt,2 letter-spacing:pt,2 -ilx-list-marker-offset:tw,0 -ilx-header-offset:mm,1 size:mm,1 -ilx-column-width:mm,1 -ilx-column-gap:mm,1 -ilx-footer-offset:mm,1 size:mm,1
An association entry has the form (notation similar to BNF):
association ::= propertyName ':' unit ',' precision
with:
propertyName ::= CSS-property-name-identifier unit ::= 'm' | 'cm' | 'mm' | 'pt' | 'in' | 'pc' | 'px' | 'emu' | 'tw' | 'hp' precision ::= [0-9]+
tw is a twip and the basic length unit used in RTF; 1tw = 0.05pt
emu is a unit used in RTF shape objects; 1cm=360,000emu
hp is a half-point and the unit used in RTF for specifying font sizes; 1hp = 0.5pt
upCast supports the use of a Catalog file. A Catalog file is in its simplest idea a mapping definition between PUBLIC DTD identifiers and the location of a physical copy of that specific DTD (or more general, Entity). The upCast application supports the Catalog file format as defined in http://www.oasis-open.org/specs/tr9401.html as well as XML Catalogs.
upCast will ask you at first launch whether you want to install a default catalog file (if there isn't already one installed). It is highly recommended to have this default installed, as it places a copy of the upCast DTD locally on your machine and lets you validate the XML (upCast DTD) filter output without requiring an active connection to the internet.
During this initial procedure, you get also the choice to specify a different default XML Catalog to use by upCast. Choose the respective option in the presented dialog and pick the catalog using a standard file chooser.
You can also change the XML Catalog used by selecting > any time during executing upCast.
You may wish to add an entry to the catalog for the XHTML 1.0 strict DTD as well and place a copy on your local machine to be able to validate also XHTML files without requiring an internet connection. Such an entry might look like this:
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "file:///localpath/to/xhtml1-strict.dtd"
The recommended procedure to add new DTDs to upCast's catalog system is to create a new catalog file and include upCast's default catalog file in it by reference. This way, you may repeatedly call without having to worry or edit the possibly manually edited default catalog file when it is created anew.
So the basic pattern to use a customized catalog is as follows:
Create a new catalog file anywhere outside upCast's {Application Support Folder} folder structure. This may be either an OASIS catalog or an XML Catalog.
Include upCast's default catalog file in this new catalog, using the CATALOG keyword (OASIS catalog).
Add references to other catalogs or create mappings as desired.
Tell upCast to use the modified catalog using the command.
You'll have to pick that custom catalog file each time you delete upCast's preferences (which you normally should not do) or you call upCast's command.