نام (NAME)

asciidoctor - تبدیل اسناد اسکیداک (AsciiDoc) به فرمتهای خروجی HTML، DocBook و سایر فرمتها

خلاصه دستور (SYNOPSIS)

asciidoctor [گزینه]... فایل...

توضیحات (DESCRIPTION)

دستور asciidoctor(1) فایل(های) منبع اسکی‌داک (فایل) را به HTML5، DocBook 5، صفحه راهنما (man page) و دیگر فرمت‌های خروجی سفارشی تبدیل می‌کند.

اگر فایل برابر - باشد، منبع اسکی‌داک از ورودی استاندارد خوانده می‌شود.

گزینه‌ها (OPTIONS)

تنظیمات امنیتی (Security Settings)

-B, --base-dir=DIR

دایرکتوری پایه حاوی سند و منابع. پیش‌فرض، دایرکتوری حاوی فایل منبع است؛ یا اگر منبع از یک جریان ورودی خوانده شود، دایرکتوری کاری جاری خواهد بود. هنگامی که با تنظیم حالت امن (safe mode) ترکیب شود، می‌تواند برای chroot کردن اجرای برنامه به کار رود.

-S, --safe-mode=SAFE_MODE

تنظیم سطح حالت امن: unsafe، safe، server، یا secure. ماکروهای بالقوه خطرناک را در فایل‌های منبع، مانند include::[] غیرفعال می‌کند. اگر تنظیم نشود، در صورت فراخوانی Asciidoctor با این اسکریپت، سطح حالت امن به صورت پیش‌فرض unsafe خواهد بود.

--safe

تنظیم سطح حالت امن روی safe. دستورالعمل‌های include را فعال می‌کند، اما از دسترسی به مسیرهای والد فایل منبع جلوگیری می‌کند. جهت سازگاری با دستور asciidoc ارائه شده است. اگر تنظیم نشود، در صورت فراخوانی Asciidoctor با این اسکریپت، سطح حالت امن به صورت پیش‌فرض unsafe خواهد بود.

تنظیمات سند (Document Settings)

-a, --attribute=ATTRIBUTE

تعریف، بازنویسی (override)، یا لغو یک صفت (attribute) سند. صفت‌های خط فرمان بر صفت‌های تعریف‌شده در فایل منبع اولویت دارند، مگر اینکه نام یا مقدار به @ ختم شود. هیچ جایگزینی روی مقدار اعمال نمی‌شود.

ATTRIBUTE معمولاً به صورت یک جفت کلید-مقدار، در قالب NAME=VALUE ساختاربندی می‌شود. شکل‌های دیگر عبارتند از NAME (که در آن مقدار VALUE به طور پیش‌فرض یک رشته خالی است)، NAME! (صفت NAME را لغو می‌کند)، و NAME=VALUE@ (یا NAME@=VALUE) (که در آن چنانچه صفت NAME از قبل در سند منبع تعریف شده باشد، مقدار VALUE آن را بازنویسی نمی‌کند). مقداری که شامل فاصله باشد باید درون گیومه قرار گیرد، به شکل NAME="VALUE WITH SPACES".

این گزینه می‌تواند بیش از یک بار مشخص شود.

-b, --backend=BACKEND

فرمت خروجی پردازشگر پسین (backend): فرمت‌های html5، docbook5 و manpage به صورت توکار پشتیبانی می‌شوند. همچنین می‌توانید از نام‌های مستعار بکند مانند html (نام مستعار برای html5) یا docbook (نام مستعار برای docbook5) استفاده کنید. مقادیر دیگر نیز می‌توانند ارسال شوند، اما اگر Asciidoctor نتواند بکند را به یک مبدل مطابقت دهد، با شکست مواجه خواهد شد. پیش‌فرض html5 است.

-d, --doctype=DOCTYPE

نوع سند: article، book، manpage، یا inline. عنصر ریشه را هنگام استفاده از بکند docbook و کلاس استایل را روی عنصر body در HTML هنگام استفاده از بکند html تنظیم می‌کند. نوع سند book امکان استفاده از چندین عنوان بخش سطح ۰ (level-0) را در یک سند واحد فراهم می‌کند. نوع سند manpage تجزیه فراداده‌های لازم برای تولید صفحه راهنما را فعال می‌کند. نوع سند inline امکان قالب‌بندی و بازگرداندن محتوای یک پاراگراف منفرد را بدون محصور کردن آن در یک عنصر دربرگیرنده فراهم می‌سازد. پیش‌فرض article است.

تبدیل سند (Document Conversion)

-D, --destination-dir=DIR

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

-E, --template-engine=NAME

موتور قالب مورد استفاده برای قالب‌های سفارشی مبدل. جم (gem) هم‌نام با موتور به طور خودکار بارگذاری خواهد شد. این نام همچنین برای ساخت مسیر کامل به قالب‌های سفارشی مبدل به کار می‌رود. اگر موتور قالبی مشخص نشود، بر اساس پسوند فایلِ قالب‌های سفارشی مبدلِ یافت‌شده به طور خودکار تشخیص داده می‌شود.

-e, --embedded

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

-I, --load-path=DIRECTORY

افزودن دایرکتوری مشخص‌شده به مسیر بارگذاری (load path)، تا گزینه -r بتواند افزونه‌ها را از خارج از مسیر پیش‌فرض بارگذاری روبی بارگذاری کند. این گزینه می‌تواند بیش از یک بار مشخص شود.

-n, --section-numbers

شماره‌گذاری خودکار عناوین بخش‌ها. مترادف با --attribute sectnums.

-o, --out-file=OUT_FILE

نوشتن خروجی در فایل OUT_FILE. پیش‌فرض، نام پایه فایل ورودی با پسوند backend است. مسیر فایل نسبت به دایرکتوری کاری جاری سنجیده می‌شود. اگر ورودی از ورودی استاندارد یا یک لوله نام‌گذاری‌شده (fifo) خوانده شود، فایل خروجی به صورت پیش‌فرض stdout خواهد بود. اگر OUT_FILE برابر - باشد، فایل خروجی در خروجی استاندارد نوشته می‌شود.

-R, --source-dir=DIR

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

-r, --require=LIBRARY

فراخوانی کتابخانه مشخص‌شده پیش از اجرای پردازشگر، با استفاده از require استاندارد روبی. این گزینه می‌تواند بیش از یک بار مشخص شود.

-s, --no-header-footer

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

-T, --template-dir=DIR

دایرکتوری حاوی قالب‌های سفارشی مبدل که یک یا چند قالب از مجموعه پیش‌فرض توکار را بازنویسی می‌کند. (نیازمند جم tilt)

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

این گزینه می‌تواند بیش از یک بار مشخص شود. قالب‌های منطبق یافت‌شده در دایرکتوری‌های بعدی، قالب‌های قبلاً کشف‌شده را بازنویسی می‌کنند.

اطلاعات پردازش (Processing Information)

--failure-level=LEVEL

تنظیم حداقل سطح ثبت گزارش (پیش‌فرض: FATAL) که منجر به کد خروجی غیرصفر (یعنی شکست) می‌شود. اگر این گزینه تنظیم نشود، حتی در صورت ثبت هشدارها یا خطاها در لاگ، برنامه با کد خروجی صفر خاتمه می‌یابد.

-q, --quiet

بی‌صدا کردن پیام‌های لاگ برنامه و هشدارهای اسکریپت.

--trace

گنجاندن اطلاعات ردگیری پشته (backtrace) هنگام گزارش خطاها.

-v, --verbose

تنظیم سطح لاگ روی DEBUG تا پیام‌های برنامه که در سطح INFO یا DEBUG ثبت شده‌اند در stderr چاپ شوند.

-w, --warnings

فعال کردن هشدارهای اسکریپت (روی کد اجراشده اعمال می‌شود).

-t, --timings

چاپ گزارش زمان‌بندی در stderr (زمان خواندن، تجزیه و تبدیل).

اطلاعات برنامه (Program Information)

-h, --help [TOPIC]

چاپ پیام راهنما. اگر TOPIC مشخص نشده یا ناشناخته باشد، نحوه استفاده از دستور را نمایش می‌دهد. اگر TOPIC برابر manpage باشد، صفحه راهنمای Asciidoctor را (در قالب troff/groff) چاپ می‌کند. اگر TOPIC برابر syntax باشد، یک برگه راهنمای سریع نحو اسکی‌داک (به زبان AsciiDoc) چاپ می‌کند.

-V, --version

چاپ شماره نسخه برنامه.

اگر هیچ فایل منبعی مشخص نشده باشد، می‌توان از -v نیز استفاده کرد.

محیط (ENVIRONMENT)

Asciidoctor از متغیر محیطی SOURCE_DATE_EPOCH پیروی می‌کند. اگر به این متغیر یک مقدار عدد صحیح اختصاص داده شود، از آن مقدار به عنوان مبدأ زمانی (epoch) تمام اسناد ورودی و به عنوان تاریخ و زمان محلی استفاده می‌شود. برای اطلاعات بیشتر درباره این متغیر محیطی، به https://reproducible-builds.org/specs/source-date-epoch مراجعه کنید.

کد خروجی (EXIT STATUS)

0

موفقیت‌آمیز.

1

شکست (خطای نحوی یا خطای نحوه استفاده؛ خطای پیکربندی؛ شکست در پردازش سند؛ خطای غیرمنتظره).

اشکالات (BUGS)

به سامانه پیگیری اشکالات Asciidoctor در نشانی https://github.com/asciidoctor/asciidoctor/issues?q=is%3Aopen مراجعه کنید.

نویسندگان (AUTHORS)

Asciidoctor توسط Dan Allen و Sarah White هدایت و نگهداری می‌شود و مشارکت‌هایی از سوی افراد متعددی در جامعه Asciidoctor دریافت کرده است. این پروژه در سال 2012 توسط Ryan Waldron بر پایه پیش‌نمونه‌ای که Nick Hengeveld برای وب‌سایت Git نوشته بود، آغاز شد. Jason Porter نخستین پیاده‌سازی رابط خط فرمان (CLI) ارائه‌شده توسط این دستور را نوشت.

AsciiDoc.py توسط Stuart Rackham ایجاد شده و مشارکت‌هایی از افراد زیادی در جامعه AsciiDoc.py دریافت کرده است.

منابع (RESOURCES)

وب‌گاه پروژه: https://asciidoctor.org

مستندات پروژه: https://docs.asciidoctor.org

گفتگوی انجمن: https://chat.asciidoctor.org

مخزن سورس‌کد: https://github.com/asciidoctor/asciidoctor

بایگانی فهرست پستی: https://discuss.asciidoctor.org