.\" -*- coding: utf-8 -*-
.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 \- نویسه‌گردانی نویسه‌های UTF-8 بر اساس یک جدول
.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 نویسه‌ها را در فایل‌های مشخص‌شده (یا در صورت مشخص نشدن، ورودی استاندارد) نویسه‌گردانی کرده و خروجی را در خروجی استاندارد می‌نویسد. تمامی ورودی‌ها و خروجی‌ها با کدگذاری UTF-8 هستند.
.PP
این برنامه معمولاً برای تبدیل نویسه‌ها در فایل‌های متنی یونیکد به برخی توالی‌های گریز نشانه‌گذاری یا نویسه‌گردانی‌های ASCII استفاده می‌شود.
(این ابزار برای تبدیل عمومی مجموعه‌های نویسه در نظر گرفته نشده است.)
این برنامه قابلیتی مشابه نگاشت‌های نویسه (character maps) در XSLT 2.0 (XML Stylesheet Language \(en Transformations, version 2.0) ارائه می‌دهد.
.SH "گزینه‌ها (OPTIONS)"
.TP 
\*(T<\fB\-m\fR\*(T>, \*(T<\fB\-\-modify\fR\*(T>
تغییر مستقیم و درجا (in-place) فایل‌های داده‌شده با خروجی نویسه‌گردانی‌شده آن‌ها، به‌جای ارسال خروجی به خروجی استاندارد.

این گزینه برای نویسه‌گردانی کارآمد چندین فایل به صورت هم‌زمان مفید است.
.TP 
\*(T<\fB\-\-help\fR\*(T>
نمایش اطلاعات خلاصه نحوه استفاده و خروج.
.TP 
\*(T<\fB\-\-version\fR\*(T>
نمایش نسخه و خروج.
.SH "نحوه استفاده (USAGE)"
ترجمه بر اساس قوانین موجود در \(oqنگاشت نویسه\(cq (character map) که در فایل \fIcharmap\fR نام برده شده است انجام می‌شود. این فایل دارای قالب زیر است:
.TP 0.4i
1.
هر خط نشان‌دهنده یک مدخل ترجمه است، به‌جز خطوط خالی و خطوط توضیح که نادیده گرفته می‌شوند.
.TP 0.4i
2.
ابتدای هر مدخل می‌تواند با هر تعداد فضای خالی (فاصله یا تب) آغاز شود.
.TP 0.4i
3.
خطوط توضیح با \*(T<#\*(T> آغاز می‌شوند.
همه چیز در همان خط نادیده گرفته می‌شود.
.TP 0.4i
4.
هر مدخل شامل نقطه کد یونیکد (Unicode codepoint) نویسه مورد نظر برای ترجمه در مبنای شانزده، به دنبال آن \fIیک\fR فاصله یا تب، و سپس رشته ترجمه تا انتهای خط است.
.TP 0.4i
5.
رشته ترجمه دقیقاً همان‌گونه که هست در نظر گرفته می‌شود، شامل هرگونه فاصله در ابتدا و انتها (به‌جز جداکننده میان نقطه کد و رشته ترجمه) و تمامی انواع نویسه‌ها. نویسه خط جدید در انتها شامل آن نمی‌شود.
.PP
قالب فوق به‌گونه‌ای محدود طراحی شده است تا \fButf8trans\fR ساده باقی بماند. اما در صورت تمایل به قالبی مبتنی بر XML، یک اسکریپت به نام \*(T<\fIxmlcharmap2utf8trans\fR\*(T> همراه با توزیع docbook2X ارائه شده است که نگاشت‌های نویسه را از فرمت XSLT 2.0 به فرمت \fButf8trans\fR تبدیل می‌کند.
.SH "محدودیت‌ها (LIMITATIONS)"
.TP 0.2i
\(bu
دستور \fButf8trans\fR با فایل‌های باینری کار نمی‌کند، زیرا دنباله‌های نامعتبر UTF-8 در ورودی با نویسه‌های U+FFFD جایگزین می‌شوند. با این حال، نویسه‌های تهی (null) در ورودی به‌درستی پردازش می‌شوند. این محدودیت ممکن است در آینده برطرف شود.
.TP 0.2i
\(bu
هیچ راهی برای گنجاندن یک خط جدید یا نویسه تهی در رشته جایگزینی وجود ندارد.
.SH "نویسندگان (AUTHORS)"
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.