'\" t
.\"     Title: asciidoc
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 07/17/2024
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: Persian
.\"
.TH "ASCIIDOC" "1" "07/17/2024" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * 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)"
asciidoc \- تبدیل فایل متنی AsciiDoc به HTML یا DocBook
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBasciidoc\fR [\fIOPTIONS\fR] \fIFILE\fR
.SH "توضیحات (DESCRIPTION)"
.sp
دستور asciidoc(1) فایل متنی AsciiDoc با نام \fIFILE\fR را به DocBook یا HTML تبدیل می‌کند\&. اگر \fIFILE\fR برابر با \fI\-\fR باشد، از ورودی استاندارد استفاده می‌شود\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-a, \-\-attribute\fR=\fIATTRIBUTE\fR
.RS 4
تعریف یا حذف صفت (attribute) سند\&.
\fIATTRIBUTE\fR
به صورت
\fINAME=VALUE\fR
قالب‌بندی می‌شود\&. صفت‌های خط فرمان بر صفت‌های سند و فایل‌های پیکربندی اولویت دارند\&. سایر فرم‌های قابل قبول عبارتند از:
\fINAME\fR
(مقدار
\fIVALUE\fR
به‌طور پیش‌فرض یک رشته خالی خواهد بود)؛
\fINAME!\fR
(حذف صفت
\fINAME\fR)؛
\fINAME=VALUE@\fR
(صفت‌های سند یا فایل پیکربندی بازنویسی نشوند)\&. مقادیر حاوی فاصله باید درون علامت‌های نقل‌قول دوتایی (گیومه) قرار گیرند\&. این گزینه می‌تواند بیش از یک بار مشخص شود\&. یک صفت ویژه به نام
\fItrace\fR
خروجی اطلاعات عیب‌یابی را کنترل می‌کند\&.
.RE
.PP
\fB\-b, \-\-backend\fR=\fIBACKEND\fR
.RS 4
قالب فایل خروجی بک‌اند:
\fIdocbook45\fR،
\fIdocbook5\fR،
\fIxhtml11\fR،
\fIhtml4\fR،
\fIhtml5\fR،
\fIslidy\fR،
\fIwordpress\fR
یا
\fIlatex\fR
(بک‌اند
\fIlatex\fR
آزمایشی است)\&. همچنین می‌توانید از نام‌های مستعار بک‌اند مانند
\fIhtml\fR
(نام مستعار برای
\fIxhtml11\fR) یا
\fIdocbook\fR
(نام مستعار برای
\fIdocbook45\fR)
استفاده کنید\&. مقدار پیش‌فرض
\fIhtml\fR
است\&. گزینه
\fB\-\-backend\fR
همچنین برای مدیریت افزونه‌های بک‌اند استفاده می‌شود (بخش
\fBدستورات افزونه (PLUGIN COMMANDS)\fR
را ببینید)\&.
.RE
.PP
\fB\-f, \-\-conf\-file\fR=\fICONF_FILE\fR
.RS 4
استفاده از فایل پیکربندی
\fICONF_FILE\fR\&. فایل‌های پیکربندی به ترتیب مشخص‌شده در خط فرمان (پس از فایل‌های پیکربندی ضمنی) پردازش می‌شوند\&. این گزینه می‌تواند بیش از یک بار مشخص شود\&.
.RE
.PP
\fB\-\-doctest\fR
.RS 4
اجرای doctestهای پایتون در ماژول
\fIasciidoc\fR\&.
.RE
.PP
\fB\-d, \-\-doctype\fR=\fIDOCTYPE\fR
.RS 4
نوع سند:
\fIarticle\fR،
\fImanpage\fR
یا
\fIbook\fR\&. نوع سند
\fIbook\fR
فقط توسط بک‌اندهای
\fIdocbook\fR
پشتیبانی می‌شود\&. نوع سند پیش‌فرض
\fIarticle\fR
است\&.
.RE
.PP
\fB\-c, \-\-dump\-conf\fR
.RS 4
تخلیه و چاپ پیکربندی در خروجی استاندارد (stdout)\&.
.RE
.PP
\fB\-\-filter\fR=\fIFILTER\fR
.RS 4
مشخص کردن نام فیلتری که باید بارگذاری شود (برای بارگذاری فیلترهایی که به‌طور خودکار بارگذاری نمی‌شوند استفاده می‌شود)\&. این گزینه می‌تواند بیش از یک بار مشخص شود\&. گزینه
\fB\-\-filter\fR
همچنین برای مدیریت افزونه‌های فیلتر استفاده می‌شود (بخش
\fBدستورات افزونه (PLUGIN COMMANDS)\fR
را ببینید)\&.
.RE
.PP
\fB\-h, \-\-help\fR [\fITOPIC\fR]
.RS 4
چاپ راهنمای TOPIC (موضوع)\&. دستور
\fB\-\-help\fR
\fItopics\fR
فهرستی از موضوعات راهنما را چاپ می‌کند،
\fB\-\-help\fR
\fIsyntax\fR
خلاصه‌ای از نحو ساختار AsciiDoc را ارائه می‌دهد، و
\fB\-\-help\fR
\fImanpage\fR
صفحه راهنمای AsciiDoc را چاپ می‌کند\&.
.RE
.PP
\fB\-e, \-\-no\-conf\fR
.RS 4
مستثنی کردن فایل‌های پیکربندی که به صورت ضمنی بارگذاری می‌شوند، به جز آن‌هایی که هم‌نام فایل ورودی هستند (\fIinfile\&.conf\fR
و
\fIinfile\-backend\&.conf\fR)\&.
.RE
.PP
\fB\-s, \-\-no\-header\-footer\fR
.RS 4
جلوگیری از چاپ سربرگ و پاورقی سند در خروجی\&.
.RE
.PP
\fB\-o, \-\-out\-file\fR=\fIOUT_FILE\fR
.RS 4
نوشتن خروجی در فایل
\fIOUT_FILE\fR\&. مقدار پیش‌فرض، نام پایه فایل ورودی همراه با پسوند
\fIbackend\fR
است\&. اگر ورودی از stdin باشد، فایل خروجی به‌طور پیش‌فرض stdout خواهد بود\&. اگر
\fIOUT_FILE\fR
برابر با
\fI\-\fR
باشد، از خروجی استاندارد استفاده می‌شود\&.
.RE
.PP
\fB\-n, \-\-section\-numbers\fR
.RS 4
شماره‌گذاری خودکار عناوین بخش‌های مقاله HTML\&. مترادف با
\fB\-\-attribute numbered\fR\&.
.RE
.PP
\fB\-\-safe\fR
.RS 4
فعال‌سازی حالت امن (safe mode)\&. حالت امن به‌طور پیش‌فرض غیرفعال است\&.
\fIsafe mode\fR
در AsciiDoc از پردازش بخش‌های اسکریپتی بالقوه خطرناک در فایل‌های منبع AsciiDoc صرف‌نظر می‌کند\&.
.RE
.PP
\fB\-\-theme\fR=\fITHEME\fR
.RS 4
مشخص کردن نام پوسته (theme)\&. مترادف با
\fB\-\-attribute theme\fR=\fITHEME\fR\&. گزینه
\fB\-\-theme\fR
همچنین برای مدیریت افزونه‌های پوسته استفاده می‌شود (بخش
\fBدستورات افزونه (PLUGIN COMMANDS)\fR
را ببینید)\&.
.RE
.PP
\fB\-v, \-\-verbose\fR
.RS 4
چاپ اطلاعات پردازش و بررسی فایل‌های پیکربندی با جزئیات کامل در stderr\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
چاپ شماره نسخه برنامه\&.
.RE
.SH "دستورات افزونه (PLUGIN COMMANDS)"
.sp
گزینه‌های \fB\-\-filter\fR، \fB\-\-backend\fR و \fB\-\-theme\fR در asciidoc(1) برای نصب، حذف و فهرست کردن افزونه‌های فیلتر، بک‌اند و پوسته AsciiDoc استفاده می‌شوند\&. نحو دستورات:
.sp
.if n \{\
.RS 4
.\}
.nf
asciidoc OPTION install ZIP_FILE [PLUGINS_DIR]
asciidoc OPTION remove PLUGIN_NAME [PLUGINS_DIR]
asciidoc OPTION list
asciidoc OPTION build ZIP_FILE PLUGIN_SOURCE
.fi
.if n \{\
.RE
.\}
.sp
که در آن:
.PP
\fBOPTION\fR
.RS 4
گزینه
\fB\-\-filter\fR،
\fB\-\-backend\fR
یا
\fB\-\-theme\fR
در asciidoc(1) که نوع افزونه را مشخص می‌کند\&.
.RE
.PP
\fBPLUGIN_NAME\fR
.RS 4
یک نام افزونه یکتا که فقط شامل کاراکترهای الفبایی\-عددی یا خط زیر (underscore) است\&.
.RE
.PP
\fBZIP_FILE\fR
.RS 4
یک فایل فشرده Zip حاوی منابع افزونه؛ نام آن باید با نام افزونه شروع شود، به عنوان مثال
my_filter\-1\&.0\&.zip
فیلتر
my_filter
را بسته‌بندی می‌کند\&.
.RE
.PP
\fBPLUGINS_DIR\fR
.RS 4
پوشه‌ای که شامل افزونه‌های نصب‌شده است\&. هر افزونه در زیرپوشه اختصاصی خود که نامی هم‌نام با افزونه دارد قرار می‌گیرد\&. مقدار پیش‌فرض
\fBPLUGINS_DIR\fR
برابر است با
$HOME/\&.asciidoc/filters
(برای افزونه‌های فیلتر) یا
$HOME/\&.asciidoc/backends
(برای افزونه‌های بک‌اند) یا
$HOME/\&.asciidoc/themes
(برای افزونه‌های پوسته)\&.
.RE
.PP
\fBPLUGIN_SOURCE\fR
.RS 4
نام پوشه حاوی فایل‌های منبع افزونه یا نام یک فایل منبع تکی\&.
.RE
.sp
دستورات افزونه به شرح زیر عمل می‌کنند:
.PP
\fBinstall\fR
.RS 4
ایجاد یک زیرپوشه در
\fBPLUGINS_DIR\fR
با نامی مشابه با افزونه و سپس استخراج محتویات
\fBZIP_FILE\fR
درون آن\&.
.RE
.PP
\fBremove\fR
.RS 4
حذف زیرپوشه افزونه
\fBPLUGIN_NAME\fR
و تمامی محتویات آن از
\fBPLUGINS_DIR\fR\&.
.RE
.PP
\fBlist\fR
.RS 4
فهرست کردن نام‌ها و مکان‌های تمام افزونه‌های فیلتر یا پوسته نصب‌شده (شامل افزونه‌های استانداردی که در پوشه پیکربندی سراسری نصب شده‌اند)\&.
.RE
.PP
\fBbuild\fR
.RS 4
ایجاد یک فایل افزونه به نام
\fBZIP_FILE\fR
حاوی فایل‌ها و زیرپوشه‌های مشخص‌شده توسط
\fBPLUGIN_SOURCE\fR\&. نام فایل‌ها و پوشه‌هایی که با نقطه شروع می‌شوند نادیده گرفته می‌شوند\&.
.RE
.SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)"
.PP
\fBSOURCE_DATE_EPOCH\fR
.RS 4
اگر متغیر محیطی
SOURCE_DATE_EPOCH
روی یک برچسب زمانی یونیکس (UNIX timestamp) تنظیم شده باشد، صفت‌های
{docdate}،
{doctime}،
{localdate}
و
{localtime}
در منطقه زمانی UTC محاسبه می‌شوند و هر برچسب زمانی که جدیدتر از
SOURCE_DATE_EPOCH
باشد با
SOURCE_DATE_EPOCH
جایگزین می‌گردد\&. (این کار به نرم‌افزارهایی که از AsciiDoc استفاده می‌کنند کمک می‌کند تا ساخت بازتولیدپذیر داشته باشند\&.)
.RE
.SH "مثال‌ها (EXAMPLES)"
.PP
asciidoc asciidoc_file_name\&.txt
.RS 4
تولید ساده یک فایل html از asciidoc_file_name\&.txt موجود در دایرکتوری فعلی با استفاده از asciidoc\&.
.RE
.PP
asciidoc \-b html5 asciidoc_file_name\&.txt
.RS 4
استفاده از سوییچ
\-b
برای به‌کارگیری یکی از بک‌اندهای پیشنهادی یا بک‌اند دیگری که روی رایانه خود نصب کرده‌اید\&.
.RE
.PP
asciidoc \-a data\-uri \-a icons \-a toc \-a max\-width=55em article\&.txt
.RS 4
استفاده از سوییچ
\-a
برای تنظیم صفت‌ها از خط فرمان\&. با این دستور، AsciiDoc راهنمای کاربری مستقل HTML خود را شامل CSS، جاوااسکریپت و تصاویر جاسازی‌شده، از قالب مقاله AsciiDoc تولید کرد\&.
.RE
.PP
asciidoc \-b html5 \-d manpage asciidoc\&.1\&.txt
.RS 4
تولید صفحه راهنمای (manpage) دستور asciidoc با استفاده از بک‌اند html5\&.
.RE
.SH "وضعیت خروج (EXIT STATUS)"
.PP
\fB0\fR
.RS 4
موفقیت‌آمیز\&.
.RE
.PP
\fB1\fR
.RS 4
شکست (خطای نحو یا نحوه استفاده؛ خطای پیکربندی؛ شکست در پردازش سند؛ خطای غیرمنتظره)\&.
.RE
.SH "اشکالات (BUGS)"
.sp
فایل BUGS موجود در توزیع AsciiDoc را ببینید\&.
.SH "نویسندگان (AUTHORS)"
.sp
دستور AsciiDoc در ابتدا توسط Stuart Rackham نوشته شد\&. افراد زیادی در توسعه آن مشارکت داشته‌اند\&.
.SH "منابع (RESOURCES)"
.sp
گیت‌هاب: https://github\&.com/asciidoc/asciidoc\-py3
.sp
وب‌سایت اصلی: https://asciidoc\&.org
.SH "همچنین ببینید (SEE ALSO)"
.sp
a2x(1)
.SH "حق نشر (COPYING)"
.sp
حق نشر \(co 2002\-2013 Stuart Rackham\&.
.sp
حق نشر \(co 2013\-2022 مشارکت‌کنندگان AsciiDoc\&.
.sp
استفاده آزاد از این نرم‌افزار تحت شرایط مجوز عمومی همگانی گنو (GNU General Public License) منتشر شده توسط بنیاد نرم‌افزارهای آزاد مجاز است؛ یا نسخه ۲ مجوز، یا (به انتخاب شما) هر نسخه بالاتر\&.
.sp
این برنامه به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص\&. برای جزئیات بیشتر مجوز عمومی همگانی گنو را ببینید\&.