.\" -*- coding: us-ascii -*-

.if \n(.g .ds T< \\FC

.if \n(.g .ds T> \\F[\n[.fam]]

.de URL

\\$2 \(la\\$1\(ra\\$3

..

.if \n(.g .mso www.tmac

.TH utf8trans 1 "3 March 2007" "docbook2X 0.8.8" docbook2X

.SH NAME

utf8trans \- Transliterate UTF-8 characters according to a table

.SH SYNOPSIS

'nh

.fi

.ad l

\fButf8trans\fR \kx

.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)

'in \n(.iu+\nxu

\fIcharmap\fR [\fIfile\fR]\&...

'in \n(.iu-\nxu

.ad b

'hy

.SH DESCRIPTION

\fButf8trans\fR transliterates characters in the specified files (or 

standard input, if they are not specified) and writes the output to

standard output. All input and output is in the UTF-8 encoding. 

.PP

This program is usually used to render characters in Unicode text files

as some markup escapes or ASCII transliterations.

(It is not intended for general charset conversions.)

It provides functionality similar to the character maps

in XSLT 2.0 (XML Stylesheet Language \(en Transformations, version 2.0).

.SH OPTIONS

.TP 

\*(T<\fB\-m\fR\*(T>, \*(T<\fB\-\-modify\fR\*(T>

Modifies the given files in-place with their transliterated output,

instead of sending it to standard output.

This option is useful for efficient transliteration of many files

at once.

.TP 

\*(T<\fB\-\-help\fR\*(T>

Show brief usage information and exit.

.TP 

\*(T<\fB\-\-version\fR\*(T>

Show version and exit.

.SH USAGE

The translation is done according to the rules in the \(oqcharacter

map\(cq, named in the file \fIcharmap\fR. It

has the following format:

.TP 0.4i

1.

Each line represents a translation entry, except for

blank lines and comment lines, which are ignored.

.TP 0.4i

2.

Any amount of whitespace (space or tab) may precede 

the start of an entry.

.TP 0.4i

3.

Comment lines begin with \*(T<#\*(T>.

Everything on the same line is ignored.

.TP 0.4i

4.

Each entry consists of the Unicode codepoint of the

character to translate, in hexadecimal, followed

\fIone\fR space or tab, followed by the translation

string, up to the end of the line.

.TP 0.4i

5.

The translation string is taken literally, including any

leading and trailing spaces (except the delimeter between the codepoint

and the translation string), and all types of characters. The newline

at the end is not included. 

.PP

The above format is intended to be restrictive, to keep

\fButf8trans\fR simple. But if a XML-based format is desired,

there is a \*(T<\fIxmlcharmap2utf8trans\fR\*(T> script that 

comes with the docbook2X distribution, that converts character

maps in XSLT 2.0 format to the \fButf8trans\fR format.

.SH LIMITATIONS

.TP 0.2i

\(bu

\fButf8trans\fR does not work with binary files, because malformed

UTF-8 sequences in the input are substituted with

U+FFFD characters. However, null characters in the input

are handled correctly. This limitation may be removed in the future.

.TP 0.2i

\(bu

There is no way to include a newline or null in the substitution string.

.SH AUTHOR

Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.