'\" t
.\"     Title: asciidoctor
.\"    Author: Dan Allen, Sarah White
.\" Generator: Asciidoctor 2.0.25
.\"      Date: 2018-03-20
.\"    Manual: Asciidoctor Manual
.\"    Source: Asciidoctor 2.0.26
.\"  Language: Persian
.\"
.TH "ASCIIDOCTOR" "1" "2018-03-20" "Asciidoctor 2.0.26" "راهنمای Asciidoctor"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
asciidoctor \- تبدیل اسناد اسکیداک (AsciiDoc) به فرمتهای خروجی HTML، DocBook و سایر فرمتها
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBasciidoctor\fP [\fIگزینه\fP].\|.\|. \fIفایل\fP.\|.\|.
.SH "توضیحات (DESCRIPTION)"
.sp
دستور \fBasciidoctor\fP(1) فایل(های) منبع اسکی‌داک (\fIفایل\fP) را به HTML5، DocBook 5، صفحه راهنما (man page) و دیگر فرمت‌های خروجی سفارشی تبدیل می‌کند.
.sp
اگر \fIفایل\fP برابر \fI\-\fP باشد، منبع اسکی‌داک از ورودی استاندارد خوانده می‌شود.
.SH "گزینه‌ها (OPTIONS)"
.SS "تنظیمات امنیتی (Security Settings)"
.sp
\fB\-B, \-\-base\-dir\fP=\fIDIR\fP
.RS 4
دایرکتوری پایه حاوی سند و منابع.
پیش‌فرض، دایرکتوری حاوی فایل منبع است؛ یا اگر منبع از یک جریان ورودی خوانده شود، دایرکتوری کاری جاری خواهد بود.
هنگامی که با تنظیم حالت امن (safe mode) ترکیب شود، می‌تواند برای chroot کردن اجرای برنامه به کار رود.
.RE
.sp
\fB\-S, \-\-safe\-mode\fP=\fISAFE_MODE\fP
.RS 4
تنظیم سطح حالت امن: \fIunsafe\fP، \fIsafe\fP، \fIserver\fP، یا \fIsecure\fP.
ماکروهای بالقوه خطرناک را در فایل‌های منبع، مانند \f(CRinclude::[]\fP غیرفعال می‌کند.
اگر تنظیم نشود، در صورت فراخوانی Asciidoctor با این اسکریپت، سطح حالت امن به صورت پیش‌فرض \fIunsafe\fP خواهد بود.
.RE
.sp
\fB\-\-safe\fP
.RS 4
تنظیم سطح حالت امن روی \fIsafe\fP.
دستورالعمل‌های include را فعال می‌کند، اما از دسترسی به مسیرهای والد فایل منبع جلوگیری می‌کند.
جهت سازگاری با دستور asciidoc ارائه شده است.
اگر تنظیم نشود، در صورت فراخوانی Asciidoctor با این اسکریپت، سطح حالت امن به صورت پیش‌فرض \fIunsafe\fP خواهد بود.
.RE
.SS "تنظیمات سند (Document Settings)"
.sp
\fB\-a, \-\-attribute\fP=\fIATTRIBUTE\fP
.RS 4
تعریف، بازنویسی (override)، یا لغو یک صفت (attribute) سند.
صفت‌های خط فرمان بر صفت‌های تعریف‌شده در فایل منبع اولویت دارند، مگر اینکه نام یا مقدار به \fI@\fP ختم شود.
هیچ جایگزینی روی مقدار اعمال نمی‌شود.
.sp
\fIATTRIBUTE\fP معمولاً به صورت یک جفت کلید\-مقدار، در قالب \fINAME=VALUE\fP ساختاربندی می‌شود.
شکل‌های دیگر عبارتند از \fINAME\fP (که در آن مقدار \fIVALUE\fP به طور پیش‌فرض یک رشته خالی است)، \fINAME!\fP (صفت \fINAME\fP را لغو می‌کند)، و \fINAME=VALUE@\fP (یا \fINAME@=VALUE\fP) (که در آن چنانچه صفت \fINAME\fP از قبل در سند منبع تعریف شده باشد، مقدار \fIVALUE\fP آن را بازنویسی نمی‌کند).
مقداری که شامل فاصله باشد باید درون گیومه قرار گیرد، به شکل \fINAME="VALUE WITH SPACES"\fP.
.sp
این گزینه می‌تواند بیش از یک بار مشخص شود.
.RE
.sp
\fB\-b, \-\-backend\fP=\fIBACKEND\fP
.RS 4
فرمت خروجی پردازشگر پسین (backend): فرمت‌های \fIhtml5\fP، \fIdocbook5\fP و \fImanpage\fP به صورت توکار پشتیبانی می‌شوند.
همچنین می‌توانید از نام‌های مستعار بکند مانند \fIhtml\fP (نام مستعار برای \fIhtml5\fP) یا \fIdocbook\fP (نام مستعار برای \fIdocbook5\fP) استفاده کنید.
مقادیر دیگر نیز می‌توانند ارسال شوند، اما اگر Asciidoctor نتواند بکند را به یک مبدل مطابقت دهد، با شکست مواجه خواهد شد.
پیش‌فرض \fIhtml5\fP است.
.RE
.sp
\fB\-d, \-\-doctype\fP=\fIDOCTYPE\fP
.RS 4
نوع سند: \fIarticle\fP، \fIbook\fP، \fImanpage\fP، یا \fIinline\fP.
عنصر ریشه را هنگام استفاده از بکند \fIdocbook\fP و کلاس استایل را روی عنصر body در HTML هنگام استفاده از بکند \fIhtml\fP تنظیم می‌کند.
نوع سند \fIbook\fP امکان استفاده از چندین عنوان بخش سطح ۰ (level-0) را در یک سند واحد فراهم می‌کند.
نوع سند \fImanpage\fP تجزیه فراداده‌های لازم برای تولید صفحه راهنما را فعال می‌کند.
نوع سند \fIinline\fP امکان قالب‌بندی و بازگرداندن محتوای یک پاراگراف منفرد را بدون محصور کردن آن در یک عنصر دربرگیرنده فراهم می‌سازد.
پیش‌فرض \fIarticle\fP است.
.RE
.SS "تبدیل سند (Document Conversion)"
.sp
\fB\-D, \-\-destination\-dir\fP=\fIDIR\fP
.RS 4
دایرکتوری مقصد خروجی.
پیش‌فرض، دایرکتوری حاوی فایل منبع است؛ یا اگر منبع از یک جریان خوانده شود، دایرکتوری کاری خواهد بود.
در صورت مشخص شدن، مسیر دایرکتوری نسبت به دایرکتوری کاری جاری در نظر گرفته می‌شود.
.RE
.sp
\fB\-E, \-\-template\-engine\fP=\fINAME\fP
.RS 4
موتور قالب مورد استفاده برای قالب‌های سفارشی مبدل.
جم (gem) هم‌نام با موتور به طور خودکار بارگذاری خواهد شد.
این نام همچنین برای ساخت مسیر کامل به قالب‌های سفارشی مبدل به کار می‌رود.
اگر موتور قالبی مشخص نشود، بر اساس پسوند فایلِ قالب‌های سفارشی مبدلِ یافت‌شده به طور خودکار تشخیص داده می‌شود.
.RE
.sp
\fB\-e, \-\-embedded\fP
.RS 4
تولید یک سند قابل‌تعبیه (embeddable) که سربرگ (header)، پابرگ (footer) و هر آنچه خارج از بدنه سند است را حذف می‌کند.
این گزینه برای تولید اسنادی که قرار است درون یک قالب خارجی درج شوند بسیار مفید است.
.RE
.sp
\fB\-I, \-\-load\-path\fP=\fIDIRECTORY\fP
.RS 4
افزودن دایرکتوری مشخص‌شده به مسیر بارگذاری (load path)، تا گزینه \fI\-r\fP بتواند افزونه‌ها را از خارج از مسیر پیش‌فرض بارگذاری روبی بارگذاری کند.
این گزینه می‌تواند بیش از یک بار مشخص شود.
.RE
.sp
\fB\-n, \-\-section\-numbers\fP
.RS 4
شماره‌گذاری خودکار عناوین بخش‌ها.
مترادف با \fB\-\-attribute sectnums\fP.
.RE
.sp
\fB\-o, \-\-out\-file\fP=\fIOUT_FILE\fP
.RS 4
نوشتن خروجی در فایل \fIOUT_FILE\fP.
پیش‌فرض، نام پایه فایل ورودی با پسوند \fIbackend\fP است.
مسیر فایل نسبت به دایرکتوری کاری جاری سنجیده می‌شود.
اگر ورودی از ورودی استاندارد یا یک لوله نام‌گذاری‌شده (fifo) خوانده شود، فایل خروجی به صورت پیش‌فرض stdout خواهد بود.
اگر \fIOUT_FILE\fP برابر \fI\-\fP باشد، فایل خروجی در خروجی استاندارد نوشته می‌شود.
.RE
.sp
\fB\-R, \-\-source\-dir\fP=\fIDIR\fP
.RS 4
دایرکتوری منبع.
در حال حاضر فقط در صورتی استفاده می‌شود که دایرکتوری مقصد نیز مشخص شده باشد.
برای حفظ ساختار دایرکتوری فایل‌های تبدیل‌شده درون این دایرکتوری در دایرکتوری مقصد به کار می‌رود.
در صورت مشخص شدن، مسیر دایرکتوری نسبت به دایرکتوری کاری سنجیده می‌شود.
.RE
.sp
\fB\-r, \-\-require\fP=\fILIBRARY\fP
.RS 4
فراخوانی کتابخانه مشخص‌شده پیش از اجرای پردازشگر، با استفاده از require استاندارد روبی.
این گزینه می‌تواند بیش از یک بار مشخص شود.
.RE
.sp
\fB\-s, \-\-no\-header\-footer\fP
.RS 4
تولید یک سند قابل‌تعبیه، که سربرگ، پابرگ و همه چیز خارج از بدنه سند را حذف می‌کند.
این گزینه برای تولید اسنادی که می‌توانند درون یک قالب خارجی درج شوند کاربردی است.
.RE
.sp
\fB\-T, \-\-template\-dir\fP=\fIDIR\fP
.RS 4
دایرکتوری حاوی قالب‌های سفارشی مبدل که یک یا چند قالب از مجموعه پیش‌فرض توکار را بازنویسی می‌کند.
(نیازمند جم \fItilt\fP)
.sp
اگر زیرپوشه‌ای وجود داشته باشد که با نام موتور (در صورت مشخص بودن) مطابقت کند، آن پوشه به انتهای مسیر دایرکتوری قالب الحاق می‌شود.
به همین ترتیب، اگر زیرپوشه‌ای در دایرکتوری قالب حاصل وجود داشته باشد که با نام بکند مطابقت داشته باشد، آن پوشه به انتهای مسیر دایرکتوری قالب الحاق می‌شود.
.sp
این گزینه می‌تواند بیش از یک بار مشخص شود.
قالب‌های منطبق یافت‌شده در دایرکتوری‌های بعدی، قالب‌های قبلاً کشف‌شده را بازنویسی می‌کنند.
.RE
.SS "اطلاعات پردازش (Processing Information)"
.sp
\fB\-\-failure\-level\fP=\fILEVEL\fP
.RS 4
تنظیم حداقل سطح ثبت گزارش (پیش‌فرض: FATAL) که منجر به کد خروجی غیرصفر (یعنی شکست) می‌شود.
اگر این گزینه تنظیم نشود، حتی در صورت ثبت هشدارها یا خطاها در لاگ، برنامه با کد خروجی صفر خاتمه می‌یابد.
.RE
.sp
\fB\-q, \-\-quiet\fP
.RS 4
بی‌صدا کردن پیام‌های لاگ برنامه و هشدارهای اسکریپت.
.RE
.sp
\fB\-\-trace\fP
.RS 4
گنجاندن اطلاعات ردگیری پشته (backtrace) هنگام گزارش خطاها.
.RE
.sp
\fB\-v, \-\-verbose\fP
.RS 4
تنظیم سطح لاگ روی DEBUG تا پیام‌های برنامه که در سطح INFO یا DEBUG ثبت شده‌اند در stderr چاپ شوند.
.RE
.sp
\fB\-w, \-\-warnings\fP
.RS 4
فعال کردن هشدارهای اسکریپت (روی کد اجراشده اعمال می‌شود).
.RE
.sp
\fB\-t, \-\-timings\fP
.RS 4
چاپ گزارش زمان‌بندی در stderr (زمان خواندن، تجزیه و تبدیل).
.RE
.SS "اطلاعات برنامه (Program Information)"
.sp
\fB\-h, \-\-help\fP [\fITOPIC\fP]
.RS 4
چاپ پیام راهنما.
اگر \fITOPIC\fP مشخص نشده یا ناشناخته باشد، نحوه استفاده از دستور را نمایش می‌دهد.
اگر \fITOPIC\fP برابر \fImanpage\fP باشد، صفحه راهنمای Asciidoctor را (در قالب troff/groff) چاپ می‌کند.
اگر \fITOPIC\fP برابر \fIsyntax\fP باشد، یک برگه راهنمای سریع نحو اسکی‌داک (به زبان AsciiDoc) چاپ می‌کند.
.RE
.sp
\fB\-V, \-\-version\fP
.RS 4
چاپ شماره نسخه برنامه.
.sp
اگر هیچ فایل منبعی مشخص نشده باشد، می‌توان از \fB\-v\fP نیز استفاده کرد.
.RE
.SH "محیط (ENVIRONMENT)"
.sp
\fBAsciidoctor\fP از متغیر محیطی \fBSOURCE_DATE_EPOCH\fP پیروی می‌کند.
اگر به این متغیر یک مقدار عدد صحیح اختصاص داده شود، از آن مقدار به عنوان مبدأ زمانی (epoch) تمام اسناد ورودی و به عنوان تاریخ و زمان محلی استفاده می‌شود.
برای اطلاعات بیشتر درباره این متغیر محیطی، به \c
.URL "https://reproducible\-builds.org/specs/source\-date\-epoch" "" ""
مراجعه کنید.
.SH "کد خروجی (EXIT STATUS)"
.sp
\fB0\fP
.RS 4
موفقیت‌آمیز.
.RE
.sp
\fB1\fP
.RS 4
شکست (خطای نحوی یا خطای نحوه استفاده؛ خطای پیکربندی؛ شکست در پردازش سند؛ خطای غیرمنتظره).
.RE
.SH "اشکالات (BUGS)"
.sp
به سامانه پیگیری اشکالات \fBAsciidoctor\fP در نشانی \c
.URL "https://github.com/asciidoctor/asciidoctor/issues?q=is%3Aopen" "" ""
مراجعه کنید.
.SH "نویسندگان (AUTHORS)"
.sp
\fBAsciidoctor\fP توسط Dan Allen و Sarah White هدایت و نگهداری می‌شود و مشارکت‌هایی از سوی افراد متعددی در جامعه Asciidoctor دریافت کرده است.
این پروژه در سال 2012 توسط Ryan Waldron بر پایه پیش‌نمونه‌ای که Nick Hengeveld برای وب‌سایت Git نوشته بود، آغاز شد.
Jason Porter نخستین پیاده‌سازی رابط خط فرمان (CLI) ارائه‌شده توسط این دستور را نوشت.
.sp
\fBAsciiDoc.py\fP توسط Stuart Rackham ایجاد شده و مشارکت‌هایی از افراد زیادی در جامعه AsciiDoc.py دریافت کرده است.
.SH "منابع (RESOURCES)"
.sp
\fBوب‌گاه پروژه:\fP \c
.URL "https://asciidoctor.org" "" ""
.sp
\fBمستندات پروژه:\fP \c
.URL "https://docs.asciidoctor.org" "" ""
.sp
\fBگفتگوی انجمن:\fP \c
.URL "https://chat.asciidoctor.org" "" ""
.sp
\fBمخزن سورس‌کد:\fP \c
.URL "https://github.com/asciidoctor/asciidoctor" "" ""
.sp
\fBبایگانی فهرست پستی:\fP \c
.URL "https://discuss.asciidoctor.org" "" ""
.SH "حق نشر (COPYING)"
.sp
حق نشر (C) 2012\-اکنون Dan Allen، Sarah White، Ryan Waldron و مشارکت‌کنندگان منفرد Asciidoctor.
استفاده از این نرم‌افزار تحت شرایط مجوز MIT مجاز است.