'\" t
.\"     Title: xmlto
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: November 2011
.\"    Manual: Reference
.\"    Source: xmlto 0.0.25
.\"  Language: English
.\"
.TH "XMLTO" "1" "November 2011" "xmlto 0.0.25" "Reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
xmlto \- اِعمال یک شیوه‌برگه XSL روی یک سند XML
.SH "خلاصه دستور (SYNOPSIS)"
.HP \w'\fBxmlto\fR\ 'u
\fBxmlto\fR [\fB\-o\fR\ \fIoutput_dir\fR] [\fB\-x\fR\ \fIcustom_xsl\fR] [\fB\-m\fR\ \fIxsl_fragment\fR] [\fB\-v\fR] [\fB\-p\fR\ \fIpostprocessor_opts\fR] [\fB\-\-extensions\fR] [\fB\-\-searchpath\fR\ \fIpath\fR] [\fB\-\-skip\-validation\fR] [\fB\-\-stringparam\fR\ \fIparamname\fR=\fIparamvalue\fR] [\fB\-\-noclean\fR] [\fB\-\-noautosize\fR] [\fB\-\-noextensions\fR] [\fB\-\-profile\fR] [\fB\-\-with\-fop\fR] [\fB\-\-with\-dblatex\fR] {\fIformat\fR} {\fIfile\fR}
.HP \w'\fBxmlto\fR\ 'u
\fBxmlto\fR {[\-\-help] | [\-\-version]}
.SH "توضیحات (DESCRIPTION)"
.PP
هدف
\fBxmlto\fR
تبدیل یک
\fIfile\fR
XML به
\fIformat\fR
مطلوب با استفاده از هر ابزار لازم است\&. این فرایند ممکن است شامل دو مرحله باشد:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
اِعمال یک شیوه‌برگه XSL مناسب با استفاده از یک پردازشگر XSL\-T\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
پردازش بیشتر با سایر ابزارها\&. این مرحله ممکن است ضروری نباشد\&.
.RE
.PP
برای تصمیم‌گیری در این باره که از کدام شیوه‌برگه استفاده شود و چه کاری (در صورت نیاز) برای پس‌پردازش خروجی باید انجام گیرد،
\fBxmlto\fR
از اسکریپت‌های قالب (format scripts) استفاده می‌کند؛ این‌ها اسکریپت‌های شل ساده‌ای هستند که
\fBxmlto\fR
در حین فرایند تبدیل آن‌ها را فراخوانی می‌کند\&.
.PP
اسکریپت قالب مناسب بر اساس نوع فایل XML و قالب خروجی مطلوب انتخاب می‌شود\&.
\fBxmlto\fR
به همراه چندین اسکریپت قالب برای تبدیل فایل‌های DocBook XML به قالب‌های گوناگون ارائه می‌شود\&. شما می‌توانید با استفاده از یک مسیر مطلق نام فایل برای
\fIformat\fR
در خط فرمان، اسکریپت قالب سفارشی خود را مشخص کنید\&.
.PP
در وهله نخست، اگر به
\fBxmlto\fR
به‌صراحت گفته نشده باشد که از چه شیوه‌برگه‌ای استفاده کند (با گزینه
\fB\-x\fR)،
اسکریپت قالب در حالی فراخوانی می‌شود که
\fB$1\fR
روی
stylesheet
تنظیم شده است\&. متغیر محیطی
\fBXSLT_PROCESSOR\fR
حاوی نام پایه فایل اجرایی است که برای انجام تبدیل XSL\-T استفاده خواهد شد (برای نمونه
xsltproc)\&.
اسکریپت قالب باید نام شیوه‌برگه مورد استفاده را در خروجی استاندارد بنویسد و با موفقیت خارج شود، یا در صورتی که شیوه‌برگه مناسبی وجود نداشته باشد، با یک کد بازگشتی غیرصفر خارج شود (برای نمونه، اگر مشخص باشد تنها شیوه‌برگه موجود با پردازشگر XSL\-T که قرار است به کار رود کار نمی‌کند)\&. اگر هیچ چیزی در خروجی استاندارد نوشته نشود اما اسکریپت با موفقیت خارج شود، هیچ تبدیل XSL\-T انجام نخواهد شد\&.
.PP
در وهله دوم، پس از آنکه یک پردازشگر XSL\-T با استفاده از شیوه‌برگه اجرا شد، اسکریپت قالب بار دیگر فراخوانی خواهد شد؛ این بار با
\fB$1\fR
تنظیم‌شده روی
post\-process\&.
اسکریپت قالب باید هرگونه گام لازم برای تبدیل خروجیِ پردازش‌شده با XSL\-T به قالب خروجی مطلوب را انجام دهد، از جمله کپی کردن خروجی در دایرکتوری خروجی دلخواه\&. برای پس‌پردازش، اسکریپت قالب در یک دایرکتوری موقت اجرا می‌شود که فقط حاوی خروجی پردازش‌شده است (نام این خروجی در
\fBXSLT_PROCESSED\fR
ذخیره شده و نام پایه آن همان نام فایل XML اصلی است که هرگونه پسوند آن با
\&.proc
جایگزین شده است)\&.
\fBINPUT_FILE\fR
روی نام فایل اصلی XML تنظیم شده،
\fBOUTPUT_DIR\fR
روی نام دایرکتوری‌ای تنظیم شده که خروجی (و تنها خروجی) باید در آن قرار گیرد، و
\fBSEARCHPATH\fR
روی فهرستی از دایرکتوری‌های پشتیبان جداشده با دونقطه تنظیم شده است که در آن‌ها باید به دنبال فایل‌های ورودی (برای نمونه تصاویر) گشت\&. چنانچه این مرحله ناموفق باشد، اسکریپت قالب باید با یک کد بازگشتی غیرصفر خارج شود\&..SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-v\fR
.RS 4
نمایش اطلاعات با جزئیات (\fB\-vv\fR
برای جزئیات بسیار زیاد)\&.
.RE
.PP
\fB\-x\fR \fIstylesheet\fR
.RS 4
استفاده از
\fIstylesheet\fR
به‌جای درخواست از اسکریپت قالب‌بندی برای انتخاب آن\&.
.RE
.PP
\fB\-m\fR \fIfragment\fR
.RS 4
استفاده از
\fIfragment\fR
ارائه‌شده از XSL برای اصلاح شیوه‌نامه\&.
.RE
.PP
\fB\-o\fR \fIdirectory\fR
.RS 4
قرار دادن خروجی در
\fIdirectory\fR
تعیین‌شده به‌جای دایرکتوری کاری فعلی\&.
.RE
.PP
\fB\-p\fR \fIpostprocessor_opts\fR
.RS 4
ارسال
\fIpostprocessor_opts\fR
به مراحل پردازش پس از اِعمال شیوه‌نامه (مانند
lynx
یا
links
هنگام تبدیل HTML به متن، یا
xmltex
هنگام تبدیل TeX به DVI)\&. اگر
\fB\-p\fR
برای بار دوم مشخص شود، گزینه‌های تعیین‌شده به مرحله دوم پس‌پردازش ارسال خواهند شد؛ در حال حاضر این ویژگی تنها هنگام تبدیل از طریق
xmltex
و
dvips
به PostScript کاربرد دارد\&.
.RE
.PP
\fB\-\-extensions\fR
.RS 4
فعال کردن افزونه‌های شیوه‌نامه برای زنجیره ابزار مورد استفاده (\fIuse\&.extensions\fR
فعال می‌شود)\&. متغیرهای فعال‌شده همان مواردی هستند که توسط شیوه‌نامه‌های DocBook XSL متعلق به Norman Walsh استفاده می‌شوند\&.
.RE
.PP
\fB\-\-searchpath\fR \fIpath\fR
.RS 4
افزودن فهرست دایرکتوری‌های جداشده با دونقطه در
\fIpath\fR
به‌عنوان دایرکتوری‌های پشتیبان جهت گنجاندن ورودی\&.
.RE
.PP
\fB\-\-skip\-validation\fR
.RS 4
صرف‌نظر کردن از مرحله اعتبارسنجی که به‌طور معمول انجام می‌شود\&.
.RE
.PP
\fB\-\-stringparam\fR \fIparamname\fR=\fIparamvalue\fR
.RS 4
ارسال یک پارامتر با نام
\fIparamname\fR
و مقدار
\fIparamvalue\fR
به شیوه‌نامه از طریق خط فرمان\&.
.RE
.PP
\fB\-\-noclean\fR
.RS 4
فایل‌های موقت حذف نمی‌شوند (نام آن‌ها نشان داده شده و در دایرکتوری tmp نگهداری می‌شوند)\&. این کار می‌تواند به بررسی و تحلیل مشکلات کمک کند\&.
.RE
.PP
\fB\-\-noautosize\fR
.RS 4
به‌طور پیش‌فرض، برخی از متغیرهای XSL توسط تشخیص خودکار بازنویسی می‌شوند (\fIpage\&.width\fR
و
\fIpage\&.height\fR
برای استفاده
paperconf
(libpaper)،
\fIpaper\&.type\fR
برای انتخاب بر پایه لوکال (\fBLC_PAPER\fR))\&. با این گزینه،
\fBxmlto\fR
از این تشخیص خودکار استفاده نمی‌کند و کاربر می‌تواند مقادیر پیش‌فرض را خود تغییر دهد (خواه از طریق تغییر فایل پیش‌فرض
param\&.xsl
یا توسط قطعه‌کد XSL تعریف‌شده توسط کاربر)\&.
.RE
.PP
\fB\-\-noextensions\fR
.RS 4
به‌طور پیش‌فرض،
\fBxmlto\fR
پارامترهای XSL شامل
\fIpassivetex\&.extensions\fR
را برای بک‌اند
passivetex
و
\fIfop\&.extensions\fR
و
\fIfop1\&.extensions\fR
را برای بک‌اند
fop
فعال می‌کند\&. این کار معمولاً نتایج بهتری ایجاد می‌کند\&. اگر بنا به دلایلی مایل به استفاده از این پارامترها نیستید، کافی است آن‌ها را با استفاده از این گزینه غیرفعال کنید\&.
.RE
.PP
\fB\-\-profile\fR
.RS 4
پیش‌پردازش سند XML با استفاده از شیوه‌نامه پروفایل‌سازی\&.
.RE
.PP
\fB\-\-with\-fop\fR
.RS 4
استفاده از
fop
برای قالب‌بندی\&. این یک گزینه آزمایشی است، انتظار دارد
fop
در مکانی مشخص باشد (در زمان پیکربندی شناسایی شده است)، و می‌توان آن را به‌صورت دستی در اسکریپت
\fBxmlto\fR
با تغییر
\fIFOP_PATH\fR
عوض کرد\&.
.RE
.PP
\fB\-\-with\-dblatex\fR
.RS 4
استفاده از
dblatex
برای قالب‌بندی\&. این یک گزینه آزمایشی است، انتظار دارد
dblatex
در مکانی مشخص باشد (در زمان پیکربندی شناسایی شده است)، و می‌توان آن را به‌صورت دستی در اسکریپت
\fBxmlto\fR
با تغییر
\fIDBLATEX_PATH\fR
عوض کرد\&.
.RE
.PP
\fB\-\-help\fR
.RS 4
نمایش یک پیام کوتاه درباره نحوه استفاده\&. این پیام گزینه‌های xmlto و قالب‌های خروجی موجود را توضیح می‌دهد\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
نمایش شماره نسخه xmlto\&.
.RE.SH "محیط (ENVIRONMENT)"
.PP
\fBXSLT_PROCESSOR\fR
.RS 4
نام پایهٔ فایل اجرایی که برای انجام تبدیل XSL\-T استفاده خواهد شد (پیش‌فرض:
\fBxsltproc\fR(1))\&.
.RE
.PP
\fBTMPDIR\fR
.RS 4
دایرکتوری محل ایجاد شیوه‌نامه‌های موقت (پیش‌فرض:
/tmp)\&.
.RE
.SH "خطاها (DIAGNOSTICS)"
.PP
\fB0\fR
.RS 4
همه چیز به درستی انجام شد\&. این کد خروج مورد انتظار است\&.
.RE
.PP
\fB1\fR
.RS 4
دستور
\fBxmlto\fR
با آرگومان‌های ناکافی فراخوانی شد\&.
.RE
.PP
\fB2\fR
.RS 4
دستور
\fBmktemp\fR(1)
در ایجاد یک فایل/دایرکتوری ناموفق بود\&. مطمئن شوید که
/tmp
یا
\fBTMPDIR\fR
قابل نوشتن است\&.
.RE
.PP
\fB3\fR
.RS 4
دستور
\fBxmlto\fR
در یافتن برخی فایل‌های باینری در مکان پیکربندی‌شده ناموفق بود\&. مطمئن شوید که همهٔ بسته‌های مورد نیاز نصب شده‌اند و مسیرها در اسکریپت
xmlto
به‌درستی تنظیم شده‌اند\&.
.RE
.PP
\fB10+(Validation non\-zero error code)\fR
.RS 4
دستور
\fBxmlto\fR
تلاش کرد یک سند xml را اعتبارسنجی کند، اما اعتبارسنجی شکست خورد\&. برای بررسی و عیب‌یابی بهتر، خروجی اعتبارسنجی و کد خروج
xmllint
ارائه شده است\&. سند خود را اصلاح کنید یا از گزینهٔ
\fB\-\-skip\-validation\fR
استفاده نمایید\&.
.RE
.SH "مثال‌ها (EXAMPLES)"
.PP
برای تبدیل یک سند DocBook XML به PDF، از این دستور استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBxmlto pdf mydoc\&.xml\fR
.fi
.if n \{\
.RE
.\}
.PP
برای تبدیل یک سند DocBook XML به HTML و ذخیرهٔ فایل‌های HTML حاصل در یک دایرکتوری جداگانه، از این دستور استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBxmlto \-o html\-dir html mydoc\&.xml\fR
.fi
.if n \{\
.RE
.\}
.PP
برای تبدیل یک سند DocBook XML به یک فایل HTML واحد، از این دستور استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBxmlto html\-nochunks mydoc\&.xml\fR
.fi
.if n \{\
.RE
.\}
.PP
برای تغییر دادن خروجی با استفاده از یک قطعه XSL، از این دستور استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBxmlto \-m ulink\&.xsl pdf mydoc\&.xml\fR
.fi
.if n \{\
.RE
.\}
.PP
برای تعیین اینکه از کدام شیوه‌نامه استفاده شود (نادیده‌گرفتن موردی که اسکریپت قالب‌بندی انتخاب می‌کند)، از این دستور استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBxmlto \-x mystylesheet\&.xsl pdf mydoc\&.xml\fR
.fi
.if n \{\
.RE
.\}.SH "نویسندگان (AUTHORS)"
.PP
\fBTim Waugh\fR <\&twaugh@redhat.com\&>
.RS 4
نویسنده اصلی، نگه‌دارنده تا 0.0.18
.RE
.PP
\fBOndřej Va\(vs\('ik\fR <\&ovasik@redhat.com\&>
.RS 4
نگه‌دارنده از 0.0.19
.RE
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
.br