.\" -*- 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 docbook2man 1 "3 March 2007" "docbook2X 0.8.8" docbook2X
.SH "نام (NAME)"
docbook2man \- تبدیل اسناد DocBook به صفحات راهنما (man pages)
.SH "خلاصه دستور (SYNOPSIS)"
'nh
.fi
.ad l
\fBdocbook2man\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)"
دستور \fBdocbook2man\fR سند DocBook XML داده‌شده را به صفحات راهنما تبدیل می‌کند.
به‌طور پیش‌فرض، صفحات راهنما در دایرکتوری جاری خروجی داده می‌شوند.
.PP
تنها محتوای \*(T<refentry\*(T>
در سند DocBook تبدیل می‌شود.
(برای تبدیل محتوای خارج از یک \*(T<refentry\*(T>،
سفارشی‌سازی شیوه‌نامه مورد نیاز است. برای جزئیات به بسته docbook2X مراجعه کنید.)
.PP
دستور \fBdocbook2man\fR یک اسکریپت لفاف (wrapper)
برای یک فرایند تبدیل دومرحله‌ای است.
برای جزئیات، بخش «فرایند تبدیل» (CONVERSION PROCESS)
را در ادامه ببینید.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های موجود اساساً اجتماع گزینه‌های
\fBdb2x_xsltproc\fR(1) و \fBdb2x_manxml\fR(1) هستند.
.PP
برخی از گزینه‌های پرکاربرد در ادامه فهرست شده‌اند:
.TP 
\*(T<\fB\-\-encoding=\fR\*(T>\fIencoding\fR
کدگذاری نویسه‌های خروجی را تعیین می‌کند.
.TP 
\*(T<\fB\-\-string\-param \fR\*(T>\fIparameter\fR\*(T<\fB=\fR\*(T>\fIvalue\fR
یک پارامتر شیوه‌نامه را تنظیم می‌کند (گزینه‌هایی که بر ظاهر خروجی تأثیر می‌گذارند).
برای پارامترهایی که می‌توان تنظیم کرد، بخش «پارامترهای شیوه‌نامه» را در ادامه ببینید.
.TP 
\*(T<\fB\-\-sgml\fR\*(T>
یک سند منبع SGML را به جای XML به عنوان ورودی می‌پذیرد.
.TP 
\*(T<\fB\-\-solinks\fR\*(T>
صفحات ساختگی (stub) را برای نام‌های جایگزین یک صفحه راهنمای خروجی ایجاد می‌کند.
.SS "پارامترهای شیوه‌نامه (STYLESHEET PARAMETERS)"
.TP 
\*(T<uppercase\-headings\*(T>
\fBخلاصه\fR. عنوان‌ها با حروف بزرگ باشند؟

\fBتنظیم پیش‌فرض\fR. \*(T<1\*(T> (درست منطقی)

عنوان‌ها در محتوای صفحه راهنما باید با حروف بزرگ نوشته شوند یا خیر.
.TP 
\*(T<manvolnum\-cite\-numeral\-only\*(T>
\fBخلاصه\fR. ارجاع به بخش صفحه راهنما تنها باید از عدد استفاده کند

\fBتنظیم پیش‌فرض\fR. \*(T<1\*(T> (درست منطقی)

هنگام ارجاع به سایر صفحات راهنما، بخش صفحه راهنما یا همان‌طور که هست ارائه می‌شود،
یا حروف آن حذف شده و تنها شماره بخش ارجاع داده می‌شود (برای مثال بخش \*(T<3x\*(T> تبدیل به
\*(T<3\*(T> می‌شود). این گزینه سبک مورد نظر را مشخص می‌کند. 
.TP 
\*(T<quotes\-on\-literals\*(T>
\fBخلاصه\fR. نمایش نقل‌قول در اطراف عناصر \*(T<literal\*(T>؟

\fBتنظیم پیش‌فرض\fR. \*(T<0\*(T> (نادرست منطقی)

اگر درست باشد، عناصر \*(T<literal\*(T>
با علامت نقل‌قول در اطراف آن‌ها نمایش داده می‌شوند.
.TP 
\*(T<show\-comments\*(T>
\fBخلاصه\fR. نمایش عناصر \*(T<comment\*(T>؟

\fBتنظیم پیش‌فرض\fR. \*(T<1\*(T> (درست منطقی)

اگر درست باشد، توضیحات نمایش داده می‌شوند؛ در غیر این صورت پنهان می‌گردند.
توضیحات در اینجا به عنصر \*(T<comment\*(T> اشاره دارد،
که در DocBook V4.0 به \*(T<remark\*(T> تغییر نام می‌یابد،
نه توضیحات XML (<-- مانند این -->) که در دسترس نیستند.
.TP 
\*(T<function\-parens\*(T>
\fBخلاصه\fR. درج پرانتز پس از نام تابع؟

\fBتنظیم پیش‌فرض\fR. \*(T<0\*(T> (نادرست منطقی)

اگر درست باشد، قالب‌بندی
یک عنصر \*(T<<function>\*(T> شامل
پرانتز تولیدشده خواهد بود.
.TP 
\*(T<xref\-on\-link\*(T>
\fBخلاصه\fR. آیا \*(T<link\*(T> باید یک ارجاع متقابل ایجاد کند؟

\fBتنظیم پیش‌فرض\fR. \*(T<1\*(T> (درست منطقی)

صفحات راهنما قادر به نمایش پیوندهای فرامتنی ایجادشده توسط \*(T<link\*(T> نیستند. اگر این گزینه فعال باشد،
شیوه‌نامه یک ارجاع متقابل به مقصد پیوند ایجاد می‌کند.
(این کار ممکن است شلوغی متن را کاهش دهد). در غیر این صورت، تنها محتوای \*(T<link\*(T> نمایش داده شده و خود پیوند
نادیده گرفته می‌شود.
.TP 
\*(T<header\-3\*(T>
\fBخلاصه\fR. متن سربرگ سوم

\fBتنظیم پیش‌فرض\fR. (خالی)

متن سربرگ سوم صفحه راهنما را تعیین می‌کند،
که معمولاً تاریخ صفحه راهنما است. در صورت خالی بودن، محتوای \*(T<date\*(T> مربوط به \*(T<refentry\*(T> استفاده می‌شود.
.TP 
\*(T<header\-4\*(T>
\fBخلاصه\fR. متن سربرگ چهارم

\fBتنظیم پیش‌فرض\fR. (خالی)

متن سربرگ چهارم یک صفحه راهنما را مشخص می‌کند.
در صورت خالی بودن، محتوای \*(T<refmiscinfo\*(T> مربوط به
\*(T<refentry\*(T> استفاده می‌شود.
.TP 
\*(T<header\-5\*(T>
\fBخلاصه\fR. متن سربرگ پنجم

\fBتنظیم پیش‌فرض\fR. (خالی)

متن سربرگ پنجم یک صفحه راهنما را مشخص می‌کند.
در صورت خالی بودن، «نام راهنما»، یعنی عنوان
ظرف نگه‌دارنده \*(T<book\*(T> یا \*(T<reference\*(T> استفاده می‌شود.
.TP 
\*(T<default\-manpage\-section\*(T>
\fBخلاصه\fR. بخش پیش‌فرض صفحه راهنما

\fBتنظیم پیش‌فرض\fR. \*(T<1\*(T>

سند منبع معمولاً مشخص می‌کند که هر صفحه راهنما
باید به چه بخشی تعلق داشته باشد (با \*(T<manvolnum\*(T> در
\*(T<refmeta\*(T>). در صورتی که سند منبع
بخش‌های صفحه راهنما را مشخص نکرده باشد، این گزینه مقدار پیش‌فرض را تعیین می‌کند.
.TP 
\*(T<custom\-localization\-file\*(T>
\fBخلاصه\fR. شناسه URI مربوط به سند XML حاوی داده‌های بومی‌سازی سفارشی

\fBتنظیم پیش‌فرض\fR. (خالی)

این پارامتر شناسه URI یک سند XML را مشخص می‌کند
که ترجمه‌های متنی (و سایر اطلاعات مختص به زبان/محل)
مورد نیاز شیوه‌نامه برای پردازش سند DocBook را توصیف می‌کند.

ترجمه‌های متنی که توسط این پارامتر مشخص می‌شوند همواره
جایگزین ترجمه‌های متنی پیش‌فرض می‌شوند 
(از پارامتر داخلی \*(T<localization\-file\*(T>).
اگر ترجمه خاصی در اینجا وجود نداشته باشد،
ترجمه پیش‌فرض متناظر 
به‌عنوان جایگزین به کار می‌رود.

این پارامتر عمدتاً برای تغییر نویسه‌های نگارشی خاص
مورد استفاده در قالب‌بندی سند منبع است.
تنظیمات نویسه‌های نگارشی اغلب مختص
سند منبع هستند، اما می‌توانند به محل (locale) نیز وابسته باشند.

برای عدم استفاده از ترجمه‌های متنی سفارشی، این پارامتر را 
یک رشته خالی بگذارید.
.TP 
\*(T<custom\-l10n\-data\*(T>
\fBخلاصه\fR. سند XML حاوی داده‌های بومی‌سازی سفارشی

\fBتنظیم پیش‌فرض\fR. \*(T<document($custom\-localization\-file)\*(T>

این پارامتر سند XML را مشخص می‌کند
که ترجمه‌های متنی (و سایر اطلاعات مختص محل)
مورد نیاز شیوه‌نامه برای پردازش سند DocBook را توصیف می‌کند.

این پارامتر داخلی شیوه‌نامه است.
برای اشاره به یک سند XML خارجی با یک URI یا یک نام پرونده، 
باید به جای آن از پارامتر \*(T<custom\-localization\-file\*(T>
استفاده کنید.

با این حال، در داخل یک شیوه‌نامه سفارشی 
(\fIنه در خط فرمان\fR)
این پارامتر می‌تواند روی عبارت XPath زیر تنظیم شود:
\*(T<document('')\*(T>،
که باعث می‌شود ترجمه‌های سفارشی 
که مستقیماً درون شیوه‌نامه سفارشی تعبیه شده‌اند خوانده شوند.
.TP 
\*(T<author\-othername\-in\-middle\*(T>
\fBخلاصه\fR. آیا \*(T<othername\*(T> در \*(T<author\*(T> نام میانی است؟

\fBتنظیم پیش‌فرض\fR. \*(T<1\*(T>

اگر درست باشد، \*(T<othername\*(T> یک \*(T<author\*(T>
بین \*(T<firstname\*(T> و
\*(T<surname\*(T> ظاهر می‌شود. در غیر این صورت، \*(T<othername\*(T>
پنهان می‌گردد.
.SH "مثال‌ها (EXAMPLES)"
.nf
\*(T<\fB$ \fRdocbook2man \-\-solinks manpages.xml
\fB$ \fRdocbook2man \-\-solinks \-\-encoding=utf\-8//TRANSLIT manpages.xml
\fB$ \fRdocbook2man \-\-string\-param header\-4="Free Recode 3.6" document.xml
\*(T>.fi
.SH "فرایند تبدیل (CONVERSION PROCESS)"
.SS "تبدیل به صفحات راهنما"
اسناد DocBook در دو مرحله به صفحات راهنما تبدیل می‌شوند:
.TP 0.4i
1.
منبع DocBook توسط یک شیوه‌نامه XSLT به یک 
قالب XML میانی، یعنی Man-XML، تبدیل می‌شود.

قالب Man-XML ساده‌تر از DocBook و نزدیک‌تر به قالب صفحات راهنما است؛
هدف از آن آسان‌تر کردن وظیفه شیوه‌نامه‌ها است.

شیوه‌نامه مربوط به این هدف در
\*(T<\fIxslt/man/docbook.xsl\fR\*(T> قرار دارد.
به منظور سازگاری و حمل‌پذیری، همیشه باید با استفاده از
شناسه URI زیر به آن ارجاع داده شود:

.nf
http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl
.fi

این شیوه‌نامه را با \fBdb2x_xsltproc\fR(1) اجرا کنید.

\fBسفارشی‌سازی\fR. 
همچنین می‌توانید خروجی را با ایجاد شیوه‌نامه XSLT اختصاصی خود
\(em تغییر پارامترها یا افزودن الگوهای جدید \(em
و وارد کردن (import) \*(T<\fIxslt/man/docbook.xsl\fR\*(T> سفارشی‌سازی کنید.
.TP 0.4i
2.
سند Man-XML توسط \fBdb2x_manxml\fR(1) به صفحات راهنمای واقعی تبدیل می‌شود.
.PP
دستور \fBdocbook2man\fR هر دو مرحله را به‌طور خودکار انجام می‌دهد،
اما در صورت بروز هرگونه مشکل، اگر هر مرحله را جداگانه انجام دهید،
می‌توانید خطاها را واضح‌تر مشاهده کنید:

.nf
\*(T<\fB$ \fRdb2x_xsltproc \-s man \fImydoc\fR.xml \-o \fImydoc\fR.mxml
\fB$ \fRdb2x_manxml \fImydoc\fR.mxml
\*(T>.fi
.PP
گزینه‌های مربوط به شیوه‌نامه تبدیل در مرجع شیوه‌نامه‌های صفحات راهنما
توضیح داده شده است.
.PP
\fBتبدیل خالص با XSLT\fR. 
یک جایگزین برای اسکریپت پرل \fBdb2x_manxml\fR، شیوه‌نامه XSLT در 
\*(T<\fIxslt/backend/db2x_manxml.xsl\fR\*(T> است.
این شیوه‌نامه عملکرد مشابهی برای تبدیل Man-XML به صفحات راهنمای واقعی ارائه می‌دهد.
اگر راه‌حل صرفاً مبتنی بر XSLT را برای تبدیل صفحات راهنما ترجیح می‌دهید، مفید است.
البته، کیفیت تبدیل با این شیوه‌نامه هیچ‌گاه به خوبی اسکریپت پرل \fBdb2x_manxml\fR
نخواهد بود و کندتر اجرا می‌شود. 
به‌ویژه، نسخه خالص XSLT در حال حاضر از جدول‌ها در صفحات راهنما پشتیبانی نمی‌کند،
در حالی که همتای پرل آن پشتیبانی می‌کند.
.SS "تبدیل مجموعه نویسه‌ها"
هنگام تبدیل XML به قالب‌های قدیمی مبتنی بر ASCII با پشتیبانی ضعیف از یونیکد (مانند صفحات راهنما و Texinfo)،
همواره این مشکل وجود دارد که نویسه‌های یونیکد موجود در
سند منبع نیز باید به نحوی تبدیل شوند.
.PP
یک تبدیل ساده مجموعه نویسه‌ها از یونیکد کافی نیست،
زیرا مجموعه نویسه‌های مقصد، که معمولاً US-ASCII یا ISO Latin-1 است،
حاوی نویسه‌های رایجی همچون خط تیره (dash) و علامت‌های نقل‌قول جهت‌دار
که به‌طور گسترده در اسناد XML به کار می‌روند نیستند. اما قالب‌بندهای اسناد (man و Texinfo)
اجازه می‌دهند چنین نویسه‌هایی با یک دنباله گریز (markup escape) وارد شوند:
برای مثال، \*(T<\e(lq\*(T> برای نقل‌قول جهت‌دار چپ 
\*(T<\(lq\*(T>.
و اگر گریز در سطح نشانه‌گذاری در دسترس نباشد،
ممکن است نویسه‌گردانی (transliteration) اسکی استفاده شود: برای مثال،
استفاده از علامت کوچکتری در اسکی \*(T<<\*(T> برای 
نقل‌قول زاویه‌ای \*(T<\(la\*(T>.
.PP
بنابراین مشکل نویسه‌های یونیکد را می‌توان در دو مرحله حل کرد:
.TP 0.4i
1.
برنامه \fButf8trans\fR(1)، گنجانده‌شده در docbook2X، نویسه‌های یونیکد را به
دنباله‌های گریز در سطح نشانه‌گذاری یا نویسه‌گردانی نگاشت می‌کند.

از آنجا که لزوماً نگاشت ثابت و رسمی برای نویسه‌های یونیکد وجود ندارد،
\fButf8trans\fR می‌تواند نگاشت‌های نویسه‌ای قابل تغییر توسط کاربر 
که در پرونده‌های متنی بیان شده‌اند را خوانده و اعمال کند (برخلاف اکثر مبدل‌های مجموعه نویسه‌ها).

در \*(T<\fIcharmaps/man/roff.charmap\fR\*(T>
و \*(T<\fIcharmaps/man/texi.charmap\fR\*(T>
نگاشت‌های نویسه‌ای وجود دارند که می‌توانند برای تبدیل صفحات راهنما و Texinfo استفاده شوند.
برنامه‌های \fBdb2x_manxml\fR(1) و \fBdb2x_texixml\fR(1) این نگاشت‌های نویسه‌ای،
یا نگاشت نویسه‌ای دیگری را که کاربر مشخص کرده است، به‌طور خودکار اعمال خواهند کرد.
.TP 0.4i
2.
بقیه متن یونیکد به یک مجموعه نویسه (کدگذاری) دیگر تبدیل می‌شود.
برای مثال، یک سند فرانسوی با نویسه‌های دارای اعراب 
(مانند \*(T<\('e\*(T>) ممکن است به ISO Latin 1 تبدیل شود.

این مرحله پس از نگاشت نویسه‌ای \fButf8trans\fR با استفاده از 
ابزار تبدیل کدگذاری \fBiconv\fR(1) اعمال می‌شود.
هر دو برنامه \fBdb2x_manxml\fR(1) و \fBdb2x_texixml\fR(1) می‌توانند
هنگام تولید خروجی خود، \fBiconv\fR(1) را به‌طور خودکار فراخوانی کنند.
.SH "فایل‌ها (FILES)"
\*(T<\fI/usr/local/share/docbook2X/xslt/man/docbook.xsl\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/xslt/backend/db2x_manxml.xsl\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/xslt/catalog.xml\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/charmaps/roff.charmap\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/charmaps/roff.charmap.xml\fR\*(T>
.PP
پرونده‌های فوق توسط بسته docbook2X توزیع و نصب می‌شوند.
.SH "نکات (NOTES)"
دستور \fBdocbook2man\fR یا \fBdocbook2texi\fR 
شرح داده‌شده در این صفحه راهنما
از بسته docbook2X می‌آیند.
این دستور را نباید با دستوری با همین نام از بسته قدیمی و منسوخ‌شده docbook-utils اشتباه گرفت.
.SH "محدودیت‌ها (LIMITATIONS)"
.TP 0.2i
\(bu
در درون برنامه، یک خط لوله طولانی از برنامه‌ها وجود دارد که سند شما از آن عبور می‌کند.
اگر هر بخشی از این خط لوله با شکست مواجه شود (حتی به شکل جزئی، مانند تایپ نادرست گزینه‌های برنامه)، 
کشف علت خطاهای حاصل ممکن است دشوار باشد \(em در این صورت، سعی کنید بخش‌های docbook2X را
به‌صورت جداگانه اجرا کنید.
.SH "نویسنده (AUTHOR)"
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.
.SH "همچنین ببینید (SEE ALSO)"
\fBdb2x_xsltproc\fR(1), \fBdb2x_manxml\fR(1), \fButf8trans\fR(1)
.PP
راهنمای docbook2X (در قالب Texinfo یا HTML) چگونگی تبدیل DocBook به صفحات راهنما و Texinfo را به‌طور کامل شرح می‌دهد.
.PP
اطلاعات به‌روز درباره این برنامه
در وب‌سایت زیر
قابل دسترسی است:
.URL http://docbook2x.sourceforge.net "وب‌سایت docbook2X"
\&.