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

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

اگر از نسخهٔ گنو (GNU) ابزار
\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>
است که در صورت برخورد با هر نویسهٔ غیرقابل ترجمه، پردازش را متوقف می‌کند.

توجه داشته باشید که صفحات راهنما و اسناد Texinfo
در کدگذاری‌های غیر ASCII (شامل UTF-8)
ممکن است به سیستم‌های قدیمی‌تر (غیر بین‌المللی‌سازی‌شده) قابل انتقال (portable) نباشند،
به همین دلیل مقدار پیش‌فرض این گزینه
\*(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>
خروجی را به جای فایل‌های مجزا در خروجی استاندارد می‌نویسد.

اگر از این گزینه استفاده شود، حتی زمانی که قرار است چندین سند خروجی تولید شوند، همه چیز در خروجی استاندارد الحاق (concatenate) می‌شود.
اما توجه داشته باشید که بیشتر برنامه‌های دیگر این خروجی الحاق‌شده را نمی‌پذیرند.

مشخصاً این گزینه با \*(T<\fB\-\-list\-files\fR\*(T>
ناسازگار است.
.TP 
\*(T<\fB\-\-help\fR\*(T>
نمایش اطلاعات مختصر دربارهٔ نحوهٔ استفاده و خروج.
.TP 
\*(T<\fB\-\-version\fR\*(T>
نمایش نسخه و خروج.
.PP
برخی از صفحات راهنما ممکن است به جای تنها یک نام، تحت دو یا چند نام ارجاع داده شوند. برای نمونه،
\fBstrcpy\fR(3)
و
\fBstrncpy\fR(3)
اغلب به یک صفحهٔ راهنمای یکسان اشاره دارند که هر دو تابع را با هم شرح می‌دهد.
یکی از گزینه‌های زیر را برای انتخاب نحوهٔ تولید چنین صفحاتی انتخاب کنید:
.TP 
\*(T<\fB\-\-symlinks\fR\*(T>
برای هر یک از نام‌های جایگزینِ یک صفحهٔ راهنما، پیوندهای نمادین (symbolic links) به فایلی که حاوی محتوای واقعی صفحه است ایجاد می‌کند.
.TP 
\*(T<\fB\-\-solinks\fR\*(T>
برای نام‌های جایگزین، صفحه‌های موقت/ارجاعی (با استفاده از درخواست‌های roff از نوع \*(T<.so\*(T>) ایجاد می‌کند که به محتوای واقعی صفحهٔ راهنما اشاره دارند.
.TP 
\*(T<\fB\-\-no\-links\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)"
صفحات راهنمای تولیدشده باید با بیشتر پیاده‌سازی‌های troff و سایر ابزارهایی که صفحات راهنما را پردازش می‌کنند سازگار باشند.
برخی از افزونه‌های سازگار با گذشتهٔ
\fBgroff\fR(1)
به کار رفته‌اند تا خروجی جلوهٔ بهتری داشته باشد.
.SH "نویسندگان (AUTHORS)"
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.
.SH "همچنین ببینید (SEE ALSO)"
راهنمای docbook2X (در قالب‌های Texinfo یا HTML) نحوهٔ تبدیل DocBook به صفحات راهنما و Texinfo را به طور کامل شرح می‌دهد.
.PP
اطلاعات به‌روز دربارهٔ این برنامه را می‌توان در
.URL http://docbook2x.sourceforge.net "وبگاه docbook2X"
یافت.
.PP
ورودی \fBdb2x_manxml\fR توسط XML DTD موجود در مسیر \*(T<\fIdtd/Man\-XML\fR\*(T> در بستهٔ توزیعی docbook2X تعریف شده است.