.\" -*- 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_xsltproc 1 "3 March 2007" "docbook2X 0.8.8" docbook2X
.SH "نام (NAME)"
db2x_xsltproc \- لفاف فراخوانی پردازشگر XSLT
.SH "خلاصه دستور (SYNOPSIS)"
'nh
.fi
.ad l
\fBdb2x_xsltproc\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_xsltproc\fR پردازشگر XSLT 1.0 را برای docbook2X فراخوانی می‌کند.
.PP
این دستور شیوه‌نامه XSLT را 
(که معمولاً توسط گزینه \*(T<\fB\-\-stylesheet\fR\*(T> تعیین می‌شود)
روی سند XML در پرونده \fIxml-document\fR اعمال می‌کند.
نتیجه در خروجی استاندارد نوشته می‌شود (مگر اینکه با 
\*(T<\fB\-\-output\fR\*(T> تغییر یابد). 
.PP
برای خواندن سند XML منبع از ورودی استاندارد،
\*(T<\-\*(T> را به عنوان سند ورودی مشخص کنید.
.SH "گزینه‌ها (OPTIONS)"
.TP 
\*(T<\fB\-\-version\fR\*(T>
نسخه docbook2X را نمایش می‌دهد.
.SS "گزینه‌های خروجی تبدیل (TRANSFORMATION OUTPUT OPTIONS)"
.TP 
\*(T<\fB\-\-output \fR\*(T>\fIfile\fR, \*(T<\fB\-o \fR\*(T>\fIfile\fR
خروجی را به جای خروجی استاندارد، در پرونده (یا URI) مشخص‌شده می‌نویسد.
.SS "گزینه‌های سند منبع (SOURCE DOCUMENT OPTIONS)"
.TP 
\*(T<\fB\-\-xinclude\fR\*(T>, \*(T<\fB\-I\fR\*(T>
دستورالعمل‌های XInclude را در سند منبع پردازش می‌کند.
.TP 
\*(T<\fB\-\-sgml\fR\*(T>, \*(T<\fB\-S\fR\*(T>
مشخص می‌کند که سند ورودی به جای XML یک سند SGML است.
اگر \fIxml-document\fR در واقع یک پرونده SGML باشد، باید این گزینه را تنظیم کنید.

تجزیه SGML با تبدیل به XML از طریق 
\fBsgml2xml\fR(1) از بسته SP (یا 
\fBosx\fR(1) از بسته OpenSP) پیاده‌سازی شده است. تمام نام‌های برچسب‌ها در پرونده SGML
به حروف کوچک یکدست می‌شوند (یعنی گزینه \*(T<\fB\-xlower\fR\*(T>
از 
\fBsgml2xml\fR(1) استفاده می‌شود). ویژگی‌های شناسه (ID) برای
شیوه‌نامه در دسترس هستند (یعنی گزینه \*(T<\fB\-xid\fR\*(T>). علاوه بر این،
هرگونه موجودیت ISO SDATA استفاده‌شده در سند SGML به‌طور خودکار
به معادل‌های یونیکد XML خود تبدیل می‌شوند. (این کار توسط فیلتر
\fBsed\fR انجام می‌شود.)

کدگذاری سند SGML، در صورتی که
\*(T<us\-ascii\*(T> نباشد، باید با متغیرهای محیطی استاندارد
SP مشخص شود: \*(T<\fBSP_CHARSET_FIXED=1
SP_ENCODING=\fIencoding\fB\fR\*(T>.
(توجه داشته باشید که پرونده‌های XML کدگذاری خود را با اعلان XML
\*(T<\fB<?xml version="1.0" encoding="\fIencoding"\fB ?>\fR\*(T>
در بالای پرونده مشخص می‌کنند.)

گزینه‌های تبدیل فوق قابل تغییر نیستند. در صورتی که گزینه‌های تبدیل متفاوتی می‌خواهید،
باید \fBsgml2xml\fR(1) را به‌صورت دستی فراخوانی کرده و سپس
نتایج آن تبدیل را به این برنامه ارسال کنید.
.SS "گزینه‌های بازیابی (RETRIEVAL OPTIONS)"
.TP 
\*(T<\fB\-\-catalogs \fR\*(T>\fIcatalog-files\fR, \*(T<\fB\-C \fR\*(T>\fIcatalog-files\fR
کاتالوگ‌های XML اضافی را برای حل شناسه‌های عمومی رسمی (FPI) یا URIها مشخص می‌کند. کاتالوگ‌های SGML پشتیبانی نمی‌شوند.

این کاتالوگ‌ها برای تجزیه یک سند SGML تحت گزینه \*(T<\fB\-\-sgml\fR\*(T>
به کار \fIنمی‌روند\fR. به جای آن، از
متغیر محیطی \fBSGML_CATALOG_FILES\fR
برای تعیین کاتالوگ‌های تجزیه سند SGML استفاده کنید.
.TP 
\*(T<\fB\-\-network\fR\*(T>, \*(T<\fB\-N\fR\*(T>
دستور \fBdb2x_xsltproc\fR به دلایل امنیتی معمولاً از بارگذاری منابع خارجی
از شبکه خودداری می‌کند. 
اگر می‌خواهید منابع از شبکه بارگذاری شوند، این گزینه را تنظیم کنید.

معمولاً بهتر است DTDهای مربوطه و سایر پرونده‌ها را به‌صورت محلی نصب کرده
و کاتالوگ‌ها را برای آن‌ها پیکربندی کنید، تا اینکه آن‌ها را به‌طور خودکار از شبکه بارگذاری نمایید.
.SS "گزینه‌های شیوه‌نامه (STYLESHEET OPTIONS)"
.TP 
\*(T<\fB\-\-stylesheet \fR\*(T>\fIfile\fR, \*(T<\fB\-s \fR\*(T>\fIfile\fR
نام پرونده (یا URI) شیوه‌نامه مورد استفاده را مشخص می‌کند. 
مقادیر ویژه \*(T<man\*(T> و \*(T<texi\*(T> 
به عنوان نام‌های اختصاری پذیرفته می‌شوند تا مشخص کنند که
\fIxml-document\fR به قالب DocBook است و
باید (به ترتیب) به صفحات راهنما یا Texinfo تبدیل شود.
.TP 
\*(T<\fB\-\-param \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIexpr\fR, \*(T<\fB\-p \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIexpr\fR
یک پارامتر را به شیوه‌نامه اضافه یا ویرایش می‌کند.
\fIname\fR نام پارامتر XSLT است، و
\fIexpr\fR یک عبارت XPath است که به
مقدار مورد نظر برای پارامتر ارزیابی می‌شود. (این بدان معناست که رشته‌ها باید در علامت نقل‌قول قرار گیرند،
\fIعلاوه بر\fR نقل‌قول معمول آرگومان‌های پوسته؛ برای جلوگیری از این مورد از \*(T<\fB\-\-string\-param\fR\*(T> استفاده کنید.)
.TP 
\*(T<\fB\-\-string\-param \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIstring\fR, \*(T<\fB\-g \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIstring\fR
یک پارامتر با مقدار رشته‌ای را به شیوه‌نامه اضافه یا ویرایش می‌کند.

رشته باید با کدگذاری UTF-8 باشد (صرف‌نظر از کدگذاری نویسه‌های محلی).
.SS "اشکال‌زدایی و پروفایلینگ (DEBUGGING AND PROFILING)"
.TP 
\*(T<\fB\-\-debug\fR\*(T>, \*(T<\fB\-d\fR\*(T>
گزارش وقایع مربوط به آنچه در طول تبدیل XSL رخ می‌دهد را در خروجی خطای استاندارد نمایش می‌دهد.
.TP 
\*(T<\fB\-\-nesting\-limit \fR\*(T>\fIn\fR, \*(T<\fB\-D \fR\*(T>\fIn\fR
حداکثر تعداد فراخوانی‌های تو در تو به الگوهای XSL را تغییر می‌دهد که برای
تشخیص حلقه‌های بی‌نهایت احتمالی استفاده می‌شود. 
در صورت عدم تعیین، این محدودیت ۵۰۰ است (پیش‌فرض libxslt).
.TP 
\*(T<\fB\-\-profile\fR\*(T>, \*(T<\fB\-P\fR\*(T>
اطلاعات پروفایلینگ را نمایش می‌دهد: تعداد کل فراخوانی‌ها به هر الگو در شیوه‌نامه و زمان صرف‌شده برای هر یک.
این اطلاعات در خروجی خطای استاندارد ارسال می‌شود.
.TP 
\*(T<\fB\-\-xslt\-processor \fR\*(T>\fIprocessor\fR, \*(T<\fB\-X \fR\*(T>\fIprocessor\fR
پردازشگر XSLT زیربنایی مورد استفاده را انتخاب می‌کند. گزینه‌های ممکن برای
\fIprocessor\fR عبارتند از: \*(T<libxslt\*(T>، \*(T<saxon\*(T>، \*(T<xalan\-j\*(T>.

پردازشگر پیش‌فرض همان گزینه‌ای است که هنگام ساخت docbook2X تنظیم شده است.
پردازشگر libxslt توصیه می‌شود (زیرا سبک و سریع است)،
اما SAXON بسیار پایدارتر است و هنگام اشکال‌زدایی شیوه‌نامه‌ها مفیدتر خواهد بود.

همه پردازشگرها از کاتالوگ‌های XML پشتیبانی می‌کنند.
(docbook2X به آن نیاز دارد.)
اما توجه داشته باشید که تمام گزینه‌های بالا با پردازشگرهایی غیر از libxslt کار نمی‌کنند.
.SH "محیط (ENVIRONMENT)"
.TP 
\fBXML_CATALOG_FILES\fR
کاتالوگ‌های XML را مشخص می‌کند.
در صورت عدم تعیین، کاتالوگ استاندارد
(\*(T<\fI/etc/xml/catalog\fR\*(T>) در صورت وجود بارگذاری می‌شود.
.TP 
\fBDB2X_XSLT_PROCESSOR\fR
پردازشگر XSLT مورد استفاده را مشخص می‌کند.
اثر آن همانند گزینه \*(T<\fB\-\-xslt\-processor\fR\*(T>
است. کاربرد اصلی این متغیر این است که به شما امکان می‌دهد تا پردازشگرهای مختلف XSLT را به سرعت و بدون نیاز به افزودن 
\*(T<\fB\-\-xslt\-processor\fR\*(T> به تک‌تک اسکریپت‌ها یا پرونده‌های make در سیستم ساخت اسناد خود آزمایش کنید.
.SH "سازگاری با استانداردها (CONFORMING TO)"
.URL http://www.w3.org/TR/xslt "زبان شیوه‌نامه XML \(en تبدیلات (XSLT)، نسخه ۱.۰"
، یک توصیه‌نامه W3C.
.SH "نکات (NOTES)"
در نسخه‌های اولیه (< 0.8.4)،
docbook2X برای اجرا به افزونه‌های XSLT نیاز داشت و
\fBdb2x_xsltproc\fR یک پردازشگر ویژه مبتنی بر libxslt بود که این
افزونه‌ها درون آن کامپایل شده بودند. هنگامی که نیاز به افزونه‌های XSLT
برداشته شد، \fBdb2x_xsltproc\fR تبدیل به یک اسکریپت پرل شد که
گزینه‌ها را به قالبی تبدیل می‌کند که توسط نسخه رسمی
\fBxsltproc\fR(1) همراه با libxslt پذیرفته می‌شود.
.PP
دلیل اصلی وجود این اسکریپت، سازگاری عقروعلی با هرگونه اسکریپت
یا پرونده ساخت است که docbook2X را فراخوانی می‌کند. با این حال،
افزودن پشتیبانی برای فراخوانی سایر پردازشگرهای XSLT با یک رابط خط فرمان یکپارچه نیز آسان شد.
در واقع، هیچ چیز اختصاصی برای docbook2X یا حتی DocBook در این اسکریپت وجود ندارد و در صورت تمایل می‌توان از آن برای اجرای انواع دیگر شیوه‌نامه‌ها استفاده کرد. قطعاً نویسنده ترجیح می‌دهد از این دستور استفاده کند، زیرا قالب فراخوانی آن منطقی بوده و استفاده از آن آسان است (برای مثال نیازی به تایپ نام‌های طولانی کلاس‌ها برای پردازشگرهای مبتنی بر جاوا نیست!).
.SH "نویسنده (AUTHOR)"
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.
.SH "همچنین ببینید (SEE ALSO)"
راهنمای docbook2X (در قالب Texinfo یا HTML) چگونگی تبدیل DocBook به صفحات راهنما و Texinfo را به‌طور کامل شرح می‌دهد.
.PP
اطلاعات به‌روز درباره این برنامه
در وب‌سایت زیر
قابل دسترسی است:
.URL http://docbook2x.sourceforge.net "وب‌سایت docbook2X"
\&.
.PP
شاید مایل باشید مستندات ارائه‌شده همراه با libxslt، SAXON یا Xalan را مطالعه کنید. مشخصات W3C XSLT 1.0 برای نوشتن شیوه‌نامه‌ها مفید خواهد بود.