XMLTO(1) Reference XMLTO(1)

xmlto - اِعمال یک شیوه‌برگه XSL روی یک سند XML

xmlto [-o output_dir] [-x custom_xsl] [-m xsl_fragment] [-v] [-p postprocessor_opts] [--extensions] [--searchpath path] [--skip-validation] [--stringparam paramname=paramvalue] [--noclean] [--noautosize] [--noextensions] [--profile] [--with-fop] [--with-dblatex] {format} {file}

xmlto {[--help] | [--version]}

هدف xmlto تبدیل یک file XML به format مطلوب با استفاده از هر ابزار لازم است. این فرایند ممکن است شامل دو مرحله باشد:

1.اِعمال یک شیوه‌برگه XSL مناسب با استفاده از یک پردازشگر XSL-T.
2.پردازش بیشتر با سایر ابزارها. این مرحله ممکن است ضروری نباشد.

برای تصمیم‌گیری در این باره که از کدام شیوه‌برگه استفاده شود و چه کاری (در صورت نیاز) برای پس‌پردازش خروجی باید انجام گیرد، xmlto از اسکریپت‌های قالب (format scripts) استفاده می‌کند؛ این‌ها اسکریپت‌های شل ساده‌ای هستند که xmlto در حین فرایند تبدیل آن‌ها را فراخوانی می‌کند.

اسکریپت قالب مناسب بر اساس نوع فایل XML و قالب خروجی مطلوب انتخاب می‌شود. xmlto به همراه چندین اسکریپت قالب برای تبدیل فایل‌های DocBook XML به قالب‌های گوناگون ارائه می‌شود. شما می‌توانید با استفاده از یک مسیر مطلق نام فایل برای format در خط فرمان، اسکریپت قالب سفارشی خود را مشخص کنید.

در وهله نخست، اگر به xmlto به‌صراحت گفته نشده باشد که از چه شیوه‌برگه‌ای استفاده کند (با گزینه -x)، اسکریپت قالب در حالی فراخوانی می‌شود که $1 روی stylesheet تنظیم شده است. متغیر محیطی XSLT_PROCESSOR حاوی نام پایه فایل اجرایی است که برای انجام تبدیل XSL-T استفاده خواهد شد (برای نمونه xsltproc). اسکریپت قالب باید نام شیوه‌برگه مورد استفاده را در خروجی استاندارد بنویسد و با موفقیت خارج شود، یا در صورتی که شیوه‌برگه مناسبی وجود نداشته باشد، با یک کد بازگشتی غیرصفر خارج شود (برای نمونه، اگر مشخص باشد تنها شیوه‌برگه موجود با پردازشگر XSL-T که قرار است به کار رود کار نمی‌کند). اگر هیچ چیزی در خروجی استاندارد نوشته نشود اما اسکریپت با موفقیت خارج شود، هیچ تبدیل XSL-T انجام نخواهد شد.

در وهله دوم، پس از آنکه یک پردازشگر XSL-T با استفاده از شیوه‌برگه اجرا شد، اسکریپت قالب بار دیگر فراخوانی خواهد شد؛ این بار با $1 تنظیم‌شده روی post-process. اسکریپت قالب باید هرگونه گام لازم برای تبدیل خروجیِ پردازش‌شده با XSL-T به قالب خروجی مطلوب را انجام دهد، از جمله کپی کردن خروجی در دایرکتوری خروجی دلخواه. برای پس‌پردازش، اسکریپت قالب در یک دایرکتوری موقت اجرا می‌شود که فقط حاوی خروجی پردازش‌شده است (نام این خروجی در XSLT_PROCESSED ذخیره شده و نام پایه آن همان نام فایل XML اصلی است که هرگونه پسوند آن با .proc جایگزین شده است). INPUT_FILE روی نام فایل اصلی XML تنظیم شده، OUTPUT_DIR روی نام دایرکتوری‌ای تنظیم شده که خروجی (و تنها خروجی) باید در آن قرار گیرد، و SEARCHPATH روی فهرستی از دایرکتوری‌های پشتیبان جداشده با دونقطه تنظیم شده است که در آن‌ها باید به دنبال فایل‌های ورودی (برای نمونه تصاویر) گشت. چنانچه این مرحله ناموفق باشد، اسکریپت قالب باید با یک کد بازگشتی غیرصفر خارج شود..SH "گزینه‌ها (OPTIONS)"

-v

نمایش اطلاعات با جزئیات (-vv برای جزئیات بسیار زیاد).

-x stylesheet

استفاده از stylesheet به‌جای درخواست از اسکریپت قالب‌بندی برای انتخاب آن.

-m fragment

استفاده از fragment ارائه‌شده از XSL برای اصلاح شیوه‌نامه.

-o directory

قرار دادن خروجی در directory تعیین‌شده به‌جای دایرکتوری کاری فعلی.

-p postprocessor_opts

ارسال postprocessor_opts به مراحل پردازش پس از اِعمال شیوه‌نامه (مانند lynx یا links هنگام تبدیل HTML به متن، یا xmltex هنگام تبدیل TeX به DVI). اگر -p برای بار دوم مشخص شود، گزینه‌های تعیین‌شده به مرحله دوم پس‌پردازش ارسال خواهند شد؛ در حال حاضر این ویژگی تنها هنگام تبدیل از طریق xmltex و dvips به PostScript کاربرد دارد.

--extensions

فعال کردن افزونه‌های شیوه‌نامه برای زنجیره ابزار مورد استفاده (use.extensions فعال می‌شود). متغیرهای فعال‌شده همان مواردی هستند که توسط شیوه‌نامه‌های DocBook XSL متعلق به Norman Walsh استفاده می‌شوند.

--searchpath path

افزودن فهرست دایرکتوری‌های جداشده با دونقطه در path به‌عنوان دایرکتوری‌های پشتیبان جهت گنجاندن ورودی.

--skip-validation

صرف‌نظر کردن از مرحله اعتبارسنجی که به‌طور معمول انجام می‌شود.

--stringparam paramname=paramvalue

ارسال یک پارامتر با نام paramname و مقدار paramvalue به شیوه‌نامه از طریق خط فرمان.

--noclean

فایل‌های موقت حذف نمی‌شوند (نام آن‌ها نشان داده شده و در دایرکتوری tmp نگهداری می‌شوند). این کار می‌تواند به بررسی و تحلیل مشکلات کمک کند.

--noautosize

به‌طور پیش‌فرض، برخی از متغیرهای XSL توسط تشخیص خودکار بازنویسی می‌شوند (page.width و page.height برای استفاده paperconf (libpaper)، paper.type برای انتخاب بر پایه لوکال (LC_PAPER)). با این گزینه، xmlto از این تشخیص خودکار استفاده نمی‌کند و کاربر می‌تواند مقادیر پیش‌فرض را خود تغییر دهد (خواه از طریق تغییر فایل پیش‌فرض param.xsl یا توسط قطعه‌کد XSL تعریف‌شده توسط کاربر).

--noextensions

به‌طور پیش‌فرض، xmlto پارامترهای XSL شامل passivetex.extensions را برای بک‌اند passivetex و fop.extensions و fop1.extensions را برای بک‌اند fop فعال می‌کند. این کار معمولاً نتایج بهتری ایجاد می‌کند. اگر بنا به دلایلی مایل به استفاده از این پارامترها نیستید، کافی است آن‌ها را با استفاده از این گزینه غیرفعال کنید.

--profile

پیش‌پردازش سند XML با استفاده از شیوه‌نامه پروفایل‌سازی.

--with-fop

استفاده از fop برای قالب‌بندی. این یک گزینه آزمایشی است، انتظار دارد fop در مکانی مشخص باشد (در زمان پیکربندی شناسایی شده است)، و می‌توان آن را به‌صورت دستی در اسکریپت xmlto با تغییر FOP_PATH عوض کرد.

--with-dblatex

استفاده از dblatex برای قالب‌بندی. این یک گزینه آزمایشی است، انتظار دارد dblatex در مکانی مشخص باشد (در زمان پیکربندی شناسایی شده است)، و می‌توان آن را به‌صورت دستی در اسکریپت xmlto با تغییر DBLATEX_PATH عوض کرد.

--help

نمایش یک پیام کوتاه درباره نحوه استفاده. این پیام گزینه‌های xmlto و قالب‌های خروجی موجود را توضیح می‌دهد.

--version

نمایش شماره نسخه xmlto.

XSLT_PROCESSOR

نام پایهٔ فایل اجرایی که برای انجام تبدیل XSL-T استفاده خواهد شد (پیش‌فرض: xsltproc(1)).

TMPDIR

دایرکتوری محل ایجاد شیوه‌نامه‌های موقت (پیش‌فرض: /tmp).

0

همه چیز به درستی انجام شد. این کد خروج مورد انتظار است.

1

دستور xmlto با آرگومان‌های ناکافی فراخوانی شد.

2

دستور mktemp(1) در ایجاد یک فایل/دایرکتوری ناموفق بود. مطمئن شوید که /tmp یا TMPDIR قابل نوشتن است.

3

دستور xmlto در یافتن برخی فایل‌های باینری در مکان پیکربندی‌شده ناموفق بود. مطمئن شوید که همهٔ بسته‌های مورد نیاز نصب شده‌اند و مسیرها در اسکریپت xmlto به‌درستی تنظیم شده‌اند.

10+(Validation non-zero error code)

دستور xmlto تلاش کرد یک سند xml را اعتبارسنجی کند، اما اعتبارسنجی شکست خورد. برای بررسی و عیب‌یابی بهتر، خروجی اعتبارسنجی و کد خروج xmllint ارائه شده است. سند خود را اصلاح کنید یا از گزینهٔ --skip-validation استفاده نمایید.

برای تبدیل یک سند DocBook XML به PDF، از این دستور استفاده کنید:

xmlto pdf mydoc.xml

برای تبدیل یک سند DocBook XML به HTML و ذخیرهٔ فایل‌های HTML حاصل در یک دایرکتوری جداگانه، از این دستور استفاده کنید:

xmlto -o html-dir html mydoc.xml

برای تبدیل یک سند DocBook XML به یک فایل HTML واحد، از این دستور استفاده کنید:

xmlto html-nochunks mydoc.xml

برای تغییر دادن خروجی با استفاده از یک قطعه XSL، از این دستور استفاده کنید:

xmlto -m ulink.xsl pdf mydoc.xml

برای تعیین اینکه از کدام شیوه‌نامه استفاده شود (نادیده‌گرفتن موردی که اسکریپت قالب‌بندی انتخاب می‌کند)، از این دستور استفاده کنید:

xmlto -x mystylesheet.xsl pdf mydoc.xml

Tim Waugh <twaugh@redhat.com>

نویسنده اصلی، نگه‌دارنده تا 0.0.18

Ondřej Vaík <ovasik@redhat.com>

نگه‌دارنده از 0.0.19

November 2011 xmlto 0.0.25