# Features

| Unicode Support
| Catalog Support

# Unicode Support

fxp has full support for Unicode and auto-detection of encoding of external XML entities. The supported encodings are currently:

Encoding | Other recognized names
--- | ---
`ASCII` | `ANSI_X3.4-1968`, `ANSI_X3.4-1986`, `US-ASCII`, `US`, `ISO646-US`, `ISO-IR-6`, `ISO_646.IRV:1991`, `IBM367` and `CP367`
`EBCDIC`
`LATIN1` | `ISO_8859-1:1987`, `ISO-8859-1`, `ISO_8859-1`, `ISO-IR-100`, `CP819`, `IBM819`, `L1`
`UCS-4` | `ISO-10646-UCS-4`
`UCS-2` | `ISO-10646-UCS-2`
`UTF-16`
`UTF-8`

# Catalog Support

| Catalogs
| Options by Example
| Summary of Options

## Catalogs

fxp supports the Socat syntax of XML Catalog. Catalogs are used for generating system identifiers from public identifiers (mapping), or for substituting system identifiers by other system identifiers (remapping). Catalogs come in two syntaxes: the Socat syntax is a subset of a catalog syntax used for SGML; the XML syntax is an XML document instance.

#### Syntax

There are five kinds of entries in a catalog:

Type | Socat/XML syntax | Meaning
--- | --- | ---
base | `BASE` uri `<Base HRef="`uri`">` | Specifies a URI to be used as a base for succeeding relative URIs.
extend | `CATALOG` uri `<Extend HRef="`uri`">` | Indicates an alternative catalog to be searched if the actual catalog does not contain a matching entry.
delegate | `DELEGATE` prefix uri `<Delegate PublicId="`prefix`" HRef="`uri`">` | Specifies an alternative catalog, but only for public identifiers beginning with prefix.
map | `PUBLIC` pubid uri `<Map PublicId="`pubid`" HRef="`uri`">` | Maps a public identifier to a URI.
remap | `SYSTEM` src dst `<Remap SystemId="`src`" HRef="`dst`">` | Indicates that URI dst shall be used in the place of the source URI src.

If the XML syntax is used, the catalog is parsed in non-validating mode and everything except for the start-tags of the above five elements is ignored. It is recommended, however, that the catalog be a valid XML document with a document type similar to this.

Relative URIs are treated as relative to the catalog in which they appear, or if there was a preceding base entry, relative to the URI of that entry. The only exception is that the src URI in a remap entry must be mapped exactly, ignoring any specified base.

#### Example in Socat Syntax

If a catalog's file name ends in `.SOC` or `.soc`, fxp assumes it is in Socat syntax, e.g.:

>     BASE     "/pub/dtd/w3c/"
>     PUBLIC   "-//W3C//DTD Specification::19980910//EN" "spec.dtd"
>     SYSTEM   "spec.dtd" "xmlspec.dtd"
>     DELEGATE "ISO" "/pub/dtd/iso/iso.soc"
>     CATALOG  "/pub/entities/ent.soc"
>     PUBLIC   "ISO 8879:1986//ENTITIES Added Latin 1//EN" "/pub/iso/lat1.ent"
>     SYSTEM   "isolat1.ent" "latin1.ent"

#### Example in XML Syntax

For XML syntax, the catalog must be a well-formed, but not necessarily valid XML document. I.e., if the catalog has more than one entry, there must be at least one root element containing all the entries. All textual data and elements other than the five catalog entries are ignored.

>     <Catalog>
>       <Base HRef="/pub/dtd/w3c/"/>
>       <Map  PublicId="-//W3C//DTD Specification::19980910//EN" HRef="spec.dtd"/>
>       <Remap SystemId="spec.dtd" HRef="xmlspec.dtd"/>
>       <Delegate PublicId="ISO" HRef="/pub/dtd/iso/iso.soc"/>
>       <Extend HRef="/pub/entities/ent.soc"/>
>       <Map PublicId="ISO 8879:1986//ENTITIES Added Latin 1//EN" HRef="/pub/iso/lat1.ent"/>
>       <Remap SystemId="isolat1.ent" HRef="latin1.ent"/>
>     </Catalog>

#### Search Order

The search order is breadth-first, i.e., a matching map or remap entry is always preferred to a matching entry in an alternative catalog specified by a preceding delegate or extend entry. E.g., in the example above the public identifier `"ISO 8879:1986//ENTITIES Added Latin 1//EN"` is mapped to `/pub/iso/lat1.ent` even if the catalog `/pub/entities/ent.soc` contains a matching entry for it.

## Catalog Options by Example

#### Catalog Search Path

A catalog to be used for resolving can be specified with the `--catalog` option. Repeating this option several times is equivalent to concatenating all specified catalogs into one. Note that, e.g, a matching entry in the second catalog overrides a match in a catalog specified in a delegate or extend entry in the first one: suppose that `iso.soc` contains the line

>     DELEGATE "ISO 8879:1986//ENTITIES" "8879.soc"

`8879.soc` contains

>     PUBLIC   "ISO 8879:1986//ENTITIES Added Latin 1//EN" "/pub/iso/lat1.ent"

and `ents.soc` contains

>     PUBLIC   "ISO 8879:1986//ENTITIES Added Latin 1//EN" "isolat1.ent"

Specifying `--catalog=iso.soc --catalog=ents.soc` makes `"ISO 8879:1986//ENTITIES Added Latin 1//EN"` resolve to `isolat1.ent`, and not to `/pub/iso/lat1.ent`.

#### Resolving Strategy

A catalog may be used for several reasons: as a fall-back, i.e., for generating system identifiers if the information in the XML document itself is not sufficient; or as the default, overriding the system identifiers specified in the DTD. By default, fxp tries to resolve an external identifier as follows:

1. if a public identifier is present, then it is tried to be mapped to a system identifier using the catalog; if this fails or no public identifier was given, the declared system identifier is used;
2. the system identifier obtained by step 1 is tried to be remapped by a matching catalog entry.

This can be affected by the `--catalog-priority` option. This option takes one of the following arguments:

`map` | the default behaviour; for succeeding relative URIs.
`remap` | first try to remap the declared system identifier; only if that fails proceed with step 1.
`sys` | if a system identifier is given, don't consider the catalog at all; if there is no system identifier, proceed to steps 1 and 2. Note that in well-formed documents an external identifier must always contain a system identifier. Therefore this applies only to external identifiers declared for notations.

E.g., suppose you have the following declarations in the DTD:

>     <ENTITY % isolat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN" "isolat1.ent">
>     <NOTATION ps PUBLIC "PostScript Level 3">

By default, the external identifier for `isolat1` is mapped to `/pub/iso/lat1.ent`. With `--catalog-priority=remap` remapping of the declared system identifier comes first and yields `latin1.ent` (which is modified to `/pub/dtd/w3c/latin1.ent` due to the base entry in the catalog's first line). Giving option `--catalog-priority=sys` totally disables the catalog for this external identifier because it has a system identifier. For notation `ps`, however, the catalog is still consulted because its declaration lacks a system identifier.

Since remapping should be used with caution in publicly available catalogs it can be disabled with `--catalog-remap=no`. E.g., resolving public identifier `"-//W3C//DTD Specification::19980910//EN"` first results in the URI `spec.dtd`. By default, this is remapped to `xmlspec.dtd`, but with `--catalog-remap=no` it is returned as is.

#### Catalog syntax and encoding

A catalog is used for resolving system identifiers in XML documents. A system identifier is a URI and may, according to RFC 2396, only contain ASCII characters. Due to an inaccuracy in the XML recommendation, however, arbitrary Unicode characters may occur in system identifiers. Since system identifiers in catalogs are matched literally, it is desirable to specify them identically both in the catalog and in the XML document. Therefore catalogs are Unicode documents and can be written in all encodings supported for XML documents. Though XML recommends encoding non-ASCII characters in system identifiers in UTF-8 and escaping the resulting bytes in the URI, matching of system identifiers in catalogs is performed on the Unicode representation. Therefore, system identifier `"entité"` does not match `"entit%C3%A9"`, though both decode to the same URI.

Catalogs in Socat syntax, however, have no encoding declaration. Therefore fxp only checks for a byte-order mark at the beginning of a catalog in order to auto-detect a UTF-16 encoding. If it doesn't find one it assumes a default encoding. Because catalogs are usually written by hand, this is by default LATIN1. The `--catalog-encoding` option tells fxp to use another default encoding.

fxp tries to guess the syntax of catalog by means of the suffix of its file name. A suffix of `.soc` or `.SOC` suggests to use Socat syntax, whereas for suffixes `.xml` and `.XML` the XML syntax is chosen. For files having none of these suffices, fxp assumes XML syntax. This can be changed with `--catalog-syntax=soc`.

## Summary of Catalog Options

`-C uri`
`--catalog=uri`
  Use `uri` as a catalog. Several catalogs can be specified by repeating this option.
`--catalog-syntax=(soc|xml)`
  For catalogs with unknown suffix, specifies whether to assume Socat syntax or XML syntax. Defaults to `xml`.
`--catalog-encoding=enc`
  Use encoding `enc` for reading a catalog unless it starts with a byte order mark. `enc` must be a supported encoding. Defaults to `LATIN1`.
`--catalog-remap=[(yes|no)]`
  Turn on or off support for remapping system identifiers. Defaults to `yes`.
`--catalog-priority=(map|remap|sys)`
  Controls the resolving strategy in catalogs. `map` means that mapping the public identifier has highest priority; `remap` means that remapping the system identifier comes first; `sys` means that the catalog is used only if no system identifier is present. Defaults to `map`.