.\" -*- 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 db2x_texixml 1 "3 March 2007" "docbook2X 0.8.8" docbook2X
.SH "نام (NAME)"
db2x_texixml \- ساخت فایل‌های Texinfo از Texi-XML
.SH "خلاصه دستور (SYNOPSIS)"
'nh
.fi
.ad l
\fBdb2x_texixml\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[گزینه‌ها]\&... [\fIxml-document\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH "توضیحات (DESCRIPTION)"
دستور \fBdb2x_texixml\fR یک سند Texi-XML را به یک یا چند سند Texinfo تبدیل می‌کند.
.PP
اگر \fIxml-document\fR مشخص نشود، سندی که باید تبدیل شود از ورودی استاندارد خوانده خواهد شد.
.PP
نام فایل‌های اسناد Texinfo توسط نشانه‌گذاری‌های موجود در منبع Texi-XML تعیین می‌شود. (اگر نام فایل‌ها در نشانه‌گذاری مشخص نشده باشد، \fBdb2x_texixml\fR تلاش می‌کند آن‌ها را از نام فایل ورودی استنتاج کند. با این حال، منبع Texi-XML باید نام فایل را مشخص کند، زیرا در صورت وجود چندین فایل خروجی یا زمانی که منبع Texi-XML از ورودی استاندارد تأمین شود، این روش کار نخواهد کرد.)
.SH "گزینه‌ها (OPTIONS)"
.TP 
\*(T<\fB\-\-encoding=\fR\*(T>\fIencoding\fR
کدگذاری نویسهٔ مورد استفاده برای فایل‌های خروجی را انتخاب می‌کند.
کدگذاری‌های دردسترس همان موارد
\fBiconv\fR(1)
هستند.
کدگذاری پیش‌فرض \*(T<us\-ascii\*(T> است.

منبع XML ممکن است حاوی نویسه‌هایی باشد که در کدگذاری انتخابی شما قابل نمایش نیستند؛ در این حالت، برنامه در طول پردازش با خطا مواجه شده و متوقف می‌شود، و شما باید کدگذاری دیگری را انتخاب کنید.
(تضمین می‌شود که این اتفاق در هیچ‌یک از کدگذاری‌های یونیکد مانند UTF-8 رخ ندهد، اما متأسفانه همه قادر به پردازش متن‌های یونیکد نیستند.)

اگر از نسخهٔ گنو \fBiconv\fR(1) استفاده می‌کنید، می‌توانید
\*(T<//TRANSLIT\*(T> را به انتهای نام کدگذاری اضافه کنید
تا برای نویسه‌های غیرقابل‌تبدیل در خروجی، تلاش برای نویسه‌گردانی (transliteration) صورت گیرد.
با این حال، آگاه باشید که نویسه‌هایی که واقعاً غیرقابل‌تبدیل هستند به یکی دیگر از آن علامت سؤال‌های کلافه‌کننده تبدیل خواهند شد. (از این موضوع خسته نشده‌اید؟)

افزودن پسوند \*(T<//TRANSLIT\*(T>
به یک کدگذاری یونیکد \(em به‌ویژه \*(T<utf\-8//TRANSLIT\*(T> \(em
بدین معناست که فایل‌های خروجی در قالب یونیکد باقی می‌مانند،
اما تبدیل نویسه‌ها در سطح نشانه‌گذاری با استفاده از \fButf8trans\fR
همچنان انجام خواهد شد. بنابراین در بیشتر موارد، یک سند انگلیسی‌زبان که با
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fButf\-8//TRANSLIT\fR\*(T>
تبدیل می‌شود در واقع به عنوان یک سند US-ASCII به پایان می‌رسد،
اما هر نویسهٔ غیرقابل‌ترجمه
بدون هیچ‌گونه هشداری به صورت UTF-8 باقی خواهد ماند.
(توجه: از نظر دقیق فنی، این یک \(lqنویسه‌گردانی\(rq نیست.)
این روش تبدیل، مصالحه‌ای در برابر پردازش سخت‌گیرانهٔ
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fBus\-ascii\fR\*(T>
است که در صورت برخورد با هر نویسهٔ غیرقابل‌ترجمه متوقف می‌شود.

توجه داشته باشید که صفحات راهنما (man pages) و اسناد Texinfo
در کدگذاری‌های غیر ASCII (شامل UTF-8)
ممکن است در سیستم‌های قدیمی‌تر (غیر بین‌المللی‌سازی‌شده) قابل حمل نباشند،
و به همین دلیل است که مقدار پیش‌فرض این گزینه
\*(T<us\-ascii\*(T> است.

برای جلوگیری از هرگونه نگاشت خودکار نویسه یا تبدیل کدگذاری،
گزینهٔ
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fButf\-8\fR\*(T>
را ارسال کنید.
.TP 
\*(T<\fB\-\-list\-files\fR\*(T>
علاوه بر پردازش عادی، فهرستی از تمامی فایل‌های خروجی را در خروجی استاندارد می‌نویسد.
.TP 
\*(T<\fB\-\-output\-dir=\fR\*(T>\fIdir\fR
دایرکتوری محل قرارگیری فایل‌های خروجی را مشخص می‌کند.
پیش‌فرض، دایرکتوری کاری فعلی است.

اگر قرار باشد خروجی در خروجی استاندارد نوشته شود (که با گزینهٔ
\*(T<\fB\-\-to\-stdout\fR\*(T>
فعال می‌شود)، این گزینه نادیده گرفته می‌شود.
.TP 
\*(T<\fB\-\-to\-stdout\fR\*(T>
خروجی را به جای فایل‌های جداگانه در خروجی استاندارد می‌نویسد.

اگر از این گزینه استفاده شود، حتی زمانی که قرار است چندین سند خروجی وجود داشته باشد،
همه چیز به‌صورت متوالی در خروجی استاندارد ادغام می‌شود.
اما توجه داشته باشید که بیشتر برنامه‌های دیگر این خروجی ادغام‌شده را قبول نخواهند کرد.

بدیهی است که این گزینه با
\*(T<\fB\-\-list\-files\fR\*(T>
ناسازگار است.
.TP 
\*(T<\fB\-\-info\fR\*(T>
خروجی Texinfo را به
\fBmakeinfo\fR(1)
هدایت (pipe) می‌کند و به‌جای فایل‌های Texinfo، مستقیماً فایل‌های Info ایجاد می‌کند.
.TP 
\*(T<\fB\-\-plaintext\fR\*(T>
خروجی Texinfo را به \fBmakeinfo
\*(T<\fB\-\-no\-headers\fR\*(T>\fR هدایت می‌کند، و در نتیجه فایل‌های متنی ساده ایجاد می‌کند.
.TP 
\*(T<\fB\-\-help\fR\*(T>
نمایش اطلاعات مختصر کاربرد و خروج.
.TP 
\*(T<\fB\-\-version\fR\*(T>
نمایش نسخه و خروج.
.PP
این برنامه برای انجام عملیات خود از برنامه‌های خاص دیگری استفاده می‌کند.
اگر آن‌ها در مکان‌های پیش‌فرض نصب خود نیستند، از گزینه‌های زیر برای تعیین مکان آن‌ها استفاده کنید:
.TP 
\*(T<\fB\-\-utf8trans\-program=\fR\*(T>\fIpath\fR, \*(T<\fB\-\-utf8trans\-map=\fR\*(T>\fIcharmap\fR
از جدول نگاشت نویسهٔ \fIcharmap\fR
همراه با برنامهٔ \fButf8trans\fR(1) (همراه با docbook2X ارائه شده است) که در مسیر
\fIpath\fR
یافت می‌شود، استفاده می‌کند.
.TP 
\*(T<\fB\-\-iconv\-program=\fR\*(T>\fIpath\fR
مکان برنامهٔ
\fBiconv\fR(1)
که برای تبدیل‌های کدگذاری استفاده می‌شود.
.SH "نکات (NOTES)"
\fBسازگاری با زبان Texinfo\fR. 
فایل‌های Texinfo تولیدشده توسط \fBdb2x_texixml\fR گاهی اوقات برای کارکرد درست به Texinfo نسخهٔ 4.7 (جدیدترین نسخه) نیاز دارند.
به‌ویژه:
.TP 0.2i
\(bu
دستور \fBdb2x_texixml\fR به \fBmakeinfo\fR
متکی است تا علائم نگارشی را پس از یک \*(T<@ref\*(T>
در صورتی که از قبل وجود نداشته باشد به‌طور خودکار اضافه کند. در غیر این صورت پیوند در نرم‌افزار خوانندهٔ Info
کار نخواهد کرد (اگرچه \fBmakeinfo\fR هیچ خطایی صادر نمی‌کند).
.TP 0.2i
\(bu
دستور جدید \*(T<@comma{}\*(T> برای ویرگول‌هایی (\*(T<,\*(T>)
که درون فهرست آرگومان‌های دستورهای Texinfo می‌آیند استفاده می‌شود تا از ویرگولی که برای جداسازی آرگومان‌های مختلف به کار می‌رود متمایز شود. در غیر این صورت تنها جایگزین ممکن،
تبدیل \*(T<,\*(T> به
\*(T<\&.\*(T>
می‌بود که مسلماً نامطلوب است (اما نسخه‌های پیشین docbook2X این کار را انجام می‌دادند).

اگر نمی‌توانید از نسخهٔ 4.7
برنامهٔ \fBmakeinfo\fR استفاده کنید، همچنان می‌توانید از یک اسکریپت
\fBsed\fR برای انجام دستی مراحل توضیح‌داده‌شده استفاده کنید.
.PP
\fBارتباط Texi-XML با قالب خروجی XML در makeinfo\fR. 
قالب Texi-XML استفاده‌شده توسط docbook2X، با قالب XML تولیدشده توسط
\fBmakeinfo\fR(1)
با گزینهٔ \*(T<\fB\-\-xml\fR\*(T>، \fIمتفاوت\fR و ناسازگار است.
این وضعیت تا حدی به این دلیل پیش آمد که قالب Texi-XML در docbook2X پیش از ظهور قالب XML برنامهٔ
\fBmakeinfo\fR
به‌طور مستقل طراحی و پیاده‌سازی شده بود.
همچنین Texi-XML بسیار متمرکز بر این است که \fIبه‌طور ماشینی از سایر قالب‌های XML تولید شود\fR،
در حالی که به نظر می‌رسد کاربرد غیربدیهی خاصی برای قالب XML برنامهٔ \fBmakeinfo\fR وجود ندارد.
بنابراین در حال حاضر هیچ دلیلی وجود ندارد که docbook2X
به جای Texi-XML از قالب XML برنامهٔ \fBmakeinfo\fR
استفاده کند.
.SH "گزارش باگ‌ها (BUGS)"
.TP 0.2i
\(bu
شکستن خطوط متن در منوها برای متون غیر ASCII کاملاً خراب است.
احتمالاً در همه‌جای دیگر خروجی نیز خراب است، اما این تقصیر \fBmakeinfo\fR خواهد بود.
.TP 0.2i
\(bu
گزینهٔ \*(T<\fB\-\-list\-files\fR\*(T> ممکن است در کنار
\*(T<\fB\-\-info\fR\*(T> به درستی کار نکند. به‌ویژه، زمانی که فایل Info خروجی
بیش از حد بزرگ شود، \fBmakeinfo\fR تصمیم می‌گیرد آن را به بخش‌هایی با نام‌های
\*(T<\fIabc.info\-1\fR\*(T>،
\*(T<\fIabc.info\-2\fR\*(T>،
\*(T<\fIabc.info\-3\fR\*(T> و غیره تقسیم کند.
برنامهٔ \fBdb2x_texixml\fR دقیقاً نمی‌داند چه تعداد از این فایل‌ها وجود دارد، هرچند می‌توانید برای بررسی آن از دستور \fBls\fR استفاده کنید.
.SH "نویسندگان (AUTHORS)"
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.
.SH "همچنین ببینید (SEE ALSO)"
راهنمای docbook2X (در قالب Texinfo یا HTML) چگونگی تبدیل DocBook به صفحات راهنما (man pages) و Texinfo را به‌طور کامل شرح می‌دهد.
.PP
اطلاعات به‌روز دربارهٔ این برنامه را می‌توان در
.URL http://docbook2x.sourceforge.net "وب‌سایت docbook2X"
یافت.
.PP
ورودی \fBdb2x_texixml\fR توسط XML DTD
موجود در مسیر \*(T<\fIdtd/Texi\-XML\fR\*(T> در توزیع docbook2X
تعریف شده است.