نام (NAME)

a2x - زنجیره ابزار تولید اسناد از فایل‌های منبع AsciiDoc

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

a2x [گزینه‌ها] SOURCE_FILE

توضیحات (DESCRIPTION)

یک مدیر زنجیره ابزار DocBook که فایل متنی AsciiDoc با نام SOURCE_FILE را با استفاده از asciidoc(1) و برنامه‌های دیگر (بخش پیش‌نیازها را ببینید) به قالب‌های PDF، EPUB، DVI، PS، LaTeX، XHTML (تک‌صفحه‌ای یا چندبخشی)، صفحه راهنما (man page)، HTML Help یا متن ساده تبدیل می‌کند. SOURCE_FILE همچنین می‌تواند یک فایل DocBook با پسوند .xml باشد.

گزینه‌ها (OPTIONS)

-a, --attribute=ATTRIBUTE

تنظیم مقدار صفت (attribute) برای asciidoc(1) (میان‌بری برای گزینهٔ --asciidoc-opts="-a ATTRIBUTE";). این گزینه می‌تواند بیش از یک بار مشخص شود.

--asciidoc-opts=ASCIIDOC_OPTS

گزینه‌های اضافی برای asciidoc(1). این گزینه می‌تواند بیش از یک بار مشخص شود.

--conf-file=CONF_FILE

بارگذاری فایل پیکربندی. بخش فایل‌های پیکربندی (CONF FILES) را ببینید.

-D, --destination-dir=DESTINATION_DIR

پوشه خروجی. پیش‌فرض، پوشهٔ SOURCE_FILE است. این گزینه فقط برای قالب‌های خروجی مبتنی بر HTML و صفحه راهنما (chunked، epub، htmlhelp، xhtml، manpage) قابل اعمال است.

-d, --doctype=DOCTYPE

نوع سند DocBook: article، manpage یا book. نوع سند پیش‌فرض article است مگر اینکه قالب manpage باشد (که در این صورت پیش‌فرض آن manpage خواهد بود).

-b, --backend=BACKEND

BACKEND نام یک افزونهٔ پشتیبان (backend plugin) نصب‌شده است. هنگامی که این گزینه مشخص شود، a2x تلاش می‌کند فایلی به نام a2x-backend.py را از پوشهٔ افزونهٔ BACKEND بارگذاری کند. سپس SOURCE_FILE را با استفاده از تابعی سراسری به نام to_BACKEND که در a2x-backend.py تعریف شده است، به یک فایل خروجی با قالب BACKEND تبدیل می‌کند.

-f, --format=FORMAT

قالب‌های خروجی: chunked، docbook، dvi، epub، htmlhelp، manpage، pdf (پیش‌فرض)، ps، tex، text، xhtml. مقدار صفت AsciiDoc با نام a2x-format بر روی FORMAT تنظیم می‌شود.

-h, --help

چاپ نحو خط فرمان و گزینه‌های برنامه در stdout.

--icons

استفاده از تصاویر آیکون هشدار (admonition) یا ناوبری در اسناد خروجی. رفتار پیش‌فرض، استفاده از متن به جای آیکون‌ها است.

--icons-dir=PATH

مسیری (نسبت به فایل‌های خروجی) حاوی آیکون‌های هشدار و ناوبری. پیش‌فرض images/icons است. در صورت استفاده از این گزینه، گزینهٔ --icons به‌طور ضمنی فعال می‌شود.

-k, --keep-artifacts

فایل‌های موقت ساخت (build) حذف نشوند.

--lynx

استفاده از lynx(1) (در واقع: مرورگر متنی تعریف‌شده توسط متغیر پیکربندی LYNX) هنگام تولید خروجی با قالب متنی. رفتار پیش‌فرض، استفاده از w3m(1) (در واقع: مرورگر متنی تعریف‌شده توسط متغیر پیکربندی W3M) است.

-L, --no-xmllint

عدم بررسی خروجی asciidoc با xmllint(1).

---epubcheck

بررسی خروجی EPUB با epubcheck(1).

-n, --dry-run

هیچ کاری انجام نشود؛ فقط آنچه قرار بود انجام شود چاپ شود.

-r, --resource=RESOURCE_SPEC

مشخص کردن یک منبع. این گزینه می‌تواند بیش از یک بار مشخص شود. برای جزئیات بیشتر بخش منابع (RESOURCES) را ببینید.

-m, --resource-manifest=FILE

FILE حاوی فهرستی از منابع است (یک منبع در هر خط). ورودی‌های فایل مانیفست FILE دقیقاً مانند آرگومان‌های گزینهٔ --resource قالب‌بندی می‌شوند. متغیرهای محیطی و علامت مدک برای پوشه خانگی مجاز هستند.

--stylesheet=STYLESHEET

فهرستی جداشده با فاصله از یک یا چند نام فایل شیوه‌نامهٔ CSS که برای اعمال سبک به خروجی HTML تولیدشده توسط DocBook XSL Stylesheets استفاده می‌شوند. پیش‌فرض docbook-xsl.css است. شیوه‌نامه‌ها به ترتیب فهرست پردازش می‌شوند. شیوه‌نامه‌ها باید در یک مکان معتبر فایل منبع (resource file) قرار داشته باشند. برای قالب‌های HTML زیر اعمال می‌شود: xhtml، epub، chunked، htmlhelp.

-v, --verbose

چاپ جزئیات عملیات در stderr. دومین گزینهٔ -v گزینه پرحرف را برای دستورات زنجیره ابزار نیز اعمال می‌کند.

--version

چاپ نسخهٔ برنامه در stdout.

--xsltproc-opts=XSLTPROC_OPTS

گزینه‌های اضافی برای xsltproc(1). این گزینه می‌تواند بیش از یک بار مشخص شود.

--xsl-file=XSL_FILE

جایگزین کردن شیوه‌نامهٔ داخلی XSL با شیوه‌نامهٔ سفارشی XSL با نام XSL_FILE.

--fop

استفاده از FOP برای تولید PDF. رفتار پیش‌فرض، استفاده از dblatex(1) است. در صورت استفاده از گزینهٔ --fop-opts گزینهٔ --fop به‌طور ضمنی فعال می‌شود.

--fop-opts=FOP_OPTS

گزینه‌های اضافی برای fop(1). اگر این گزینه مشخص شود، از FOP برای تولید PDF استفاده می‌شود. این گزینه می‌تواند بیش از یک بار مشخص شود.

--dblatex-opts=DBLATEX_OPTS

گزینه‌های اضافی برای dblatex(1). این گزینه می‌تواند بیش از یک بار مشخص شود.

--backend-opts=BACKEND_OPTS

گزینه‌های مربوط به افزونهٔ پشتیبان که توسط گزینهٔ --backend مشخص شده است. این گزینه می‌تواند بیش از یک بار مشخص شود.

گزینه‌ها همچنین می‌توانند درون فایل منبع AsciiDoc تنظیم شوند. اگر SOURCE_FILE دارای یک خط توضیح (comment) باشد که با // a2x: شروع می‌شود، باقی‌ماندهٔ آن خط به‌عنوان گزینه‌های خط فرمان a2x در نظر گرفته خواهد شد. برای مثال:

// a2x default options.
//    a2x: -dbook --epubcheck
// Suppress revision history in dblatex outputs.
//    a2x: --dblatex-opts "-P latex.output.revhistory=0"

•گزینه‌هایی که در چندین خط توضیح از این دست قرار دارند، به یکدیگر متصل خواهند شد.

•صفر یا چند نویسه فاصله (white space) می‌توانند بین // آغازین و a2x: قرار گیرند.

•گزینه‌های خط فرمان بر گزینه‌های تنظیم‌شده در فایل منبع اولویت دارند.

فایل‌های خروجی (OUTPUT FILES)

فایل‌های خروجی در پوشه‌ای که توسط گزینهٔ --destination-dir مشخص شده است نوشته می‌شوند. اگر هیچ گزینهٔ --destination-dir مشخص نشده باشد، فایل‌های خروجی در پوشهٔ SOURCE_FILE نوشته می‌شوند.

فایل‌های خروجی دارای همان نام SOURCE_FILE هستند اما با پسوند فایل مناسب: .html برای xhtml؛ .epub برای epub؛ .hhp برای htmlhelp؛ .pdf برای pdf؛ .text برای text؛ .xml برای docbook. طبق قرارداد، صفحات راهنما (manpages) هیچ پسوند .man ندارند (فقط شماره بخش صفحه راهنما). نام پوشه‌های HTML چندبخشی (chunked) دارای پسوند .chunked است؛ نام پوشه‌های HTML Help چندبخشی دارای پسوند .htmlhelp است.

فایل‌های موجود با همان نام بازنویسی می‌شوند.

علاوه بر تولید فایل‌های HTML، قالب‌های xhtml، epub، chunked و htmlhelp اطمینان حاصل می‌کنند که فایل‌های منبع در مکان‌های صحیح پوشه مقصد کپی شوند.

منابع (RESOURCES)

منابع فایل‌هایی هستند (معمولاً CSS و تصاویر) که برای خروجی‌های مبتنی بر HTML (قالب‌های xhtml، epub، chunked، htmlhelp) مورد نیاز هستند. a2x فایل‌های HTML تولیدشده را بررسی کرده و فهرستی از فایل‌های CSS و تصاویر مورد نیاز تهیه می‌کند. فایل‌های منبع اضافی را می‌توان به‌طور صریح با استفاده از گزینهٔ --resource مشخص کرد.

a2x فایل‌های منبع را در مکان‌های زیر و به ترتیب زیر جستجو می‌کند:

1.پوشهٔ SOURCE_FILE.

2.پوشه‌های منابع مشخص‌شده توسط گزینهٔ --resource (به‌صورت بازگشتی جستجو می‌شوند).

3.پوشه‌های منابع مشخص‌شده توسط گزینهٔ --resource-manifest (به‌صورت بازگشتی و به ترتیبی که در فایل مانیفست آمده‌اند جستجو می‌شوند).

4.پوشه‌های پیش‌فرض images و stylesheets در پوشه‌های فایل‌های پیکربندی asciidoc(1) (به‌صورت بازگشتی جستجو می‌شوند).

5.پوشهٔ مقصد.

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

دو سازوکار مجزا برای مشخص کردن منابع اضافی وجود دارد:

1.یک پوشهٔ منبع که برای فایل‌های منبع ناموجود به‌صورت بازگشتی جستجو می‌شود.

2.یک فایل منبع که در پوشهٔ مقصد خروجی کپی می‌شود.

منابع با مقادیر گزینهٔ --resource مشخص می‌شوند که می‌توانند یکی از قالب‌های زیر را داشته باشند:

<resource_dir>
<resource_file>[=<destination_file>]
.<ext>=<mimetype>

که در آن:

<resource_dir>

یک پوشه (مطلق یا نسبت به SOURCE_FILE) را مشخص می‌کند که برای فایل‌های منبع ناموجود به‌صورت بازگشتی جستجو می‌شود. برای جلوگیری از ابهام، نام <resource_dir> باید با یک نویسهٔ جداکننده پوشه خاتمه یابد.

<resource_file>

یک فایل منبع (مطلق یا نسبت به SOURCE_FILE) را مشخص می‌کند که در <destination_file> کپی خواهد شد. اگر <destination_file> مشخص نشود، همانند <resource_file> خواهد بود.

<destination_file>

مقصد فایل منبع کپی‌شده را مشخص می‌کند. مسیر <destination_file> نسبت به پوشه مقصد است (مسیرهای مطلق مجاز نیستند). مکان پوشه مقصد به FORMAT خروجی بستگی دارد (برای جزئیات به بخش فایل‌های خروجی (OUTPUT FILES) مراجعه کنید):

chunked, htmlhelp

پوشه خروجی قطعه‌قطعه‌شده (chunked).

epub

پوشه بایگانی‌شدهٔ OEBPS.

xhtml

پوشه خروجی DESTINATION_DIR.

.<ext>=<mimetype>

هنگام افزودن منابع به فایل‌های EPUB، نوع MIME از روی پسوند <destination_file> استنباط می‌شود؛ اگر نوع MIME قابل تشخیص نباشد، خطایی رخ می‌دهد. ساختار منبع .<ext>=<mimetype> می‌تواند برای تعیین صریح نوع‌های MIME استفاده شود. <ext> پسوند نام فایل و <mimetype> نوع MIME متناظر است.

مثال‌هایی از گزینهٔ منبع:

--resource ../images/
--resource doc/README.txt=README.txt
--resource ~/images/tiger.png=images/tiger.png
--resource .ttf=application/x-font-ttf

مثال‌ها (EXAMPLES)

a2x -f pdf doc/source-highlight-filter.txt

تولید فایل doc/source-highlight-filter.pdf.

a2x -f xhtml -D ../doc --icons -r ../images/ team.txt

ایجاد فایل HTML به نام ../doc/team.html، استفاده از آیکون‌های هشدار و جستجوی بازگشتی در پوشهٔ ../images/ برای یافتن منابع ناموجود.

a2x -f manpage doc/asciidoc.1.txt

تولید صفحه راهنمای doc/asciidoc.1.

پیش‌نیازها (REQUISITES)

a2x از برنامه‌های زیر استفاده می‌کند:

•Asciidoc: https://asciidoc.org

•xsltproc: (تمام قالب‌ها به جز متن): http://xmlsoft.org/XSLT

•DocBook XSL Stylesheets (تمام قالب‌ها به جز متن): https://github.com/docbook/xslt10-stylesheets

•dblatex (قالب‌های pdf، dvi، ps، tex): http://dblatex.sourceforge.net

•FOP (قالب pdf — تولیدکنندهٔ جایگزین فایل PDF): https://xmlgraphics.apache.org/fop

•w3m (قالب متن): http://w3m.sourceforge.net/index.en.html

•Lynx (قالب متن — تولیدکنندهٔ جایگزین فایل متنی): https://invisible-island.net/lynx

•epubcheck (قالب epub — اعتبارسنج فایل EPUB): https://github.com/w3c/epubcheck

همچنین آخرین فایل README را ببینید.

فایل‌های پیکربندی (CONF FILES)

یک فایل پیکربندی شامل کدهای اجرایی پایتون است که پارامترهای پیکربندی سراسری را در a2x.py بازنویسی می‌کند. فایل‌های پیکربندی اختیاری به ترتیب زیر بارگذاری می‌شوند:

1.a2x.conf از پوشهٔ حاوی فایل اجرایی a2x.py.

2.a2x.conf از پوشهٔ پیکربندی سراسری AsciiDoc. در صورتی که نسخهٔ نصب‌شده به‌صورت محلی (غیر سراسری در سیستم) را اجرا می‌کنیم، از این مرحله صرف‌نظر می‌شود.

3.a2x.conf از پوشهٔ پیکربندی $HOME/.asciidoc در AsciiDoc.

4.فایل CONF_FILE مشخص‌شده در گزینهٔ --conf-file.

در اینجا مقادیر پیش‌فرض گزینه‌های فایل پیکربندی آمده است:

# Optional environment variable dictionary passed to
# executing programs. If set to None the existing
# environment is used.
ENV = None
# External executables.
ASCIIDOC = 'asciidoc'
XSLTPROC = 'xsltproc'
DBLATEX = 'dblatex'         # pdf generation.
FOP = 'fop'                 # pdf generation (--fop option).
W3M = 'w3m'                 # primary text file generator.
LYNX = 'lynx'               # alternate text file generator.
XMLLINT = 'xmllint'         # Set to '' to disable.
EPUBCHECK = 'epubcheck'     # Set to '' to disable.
# External executable default options.
ASCIIDOC_OPTS = ''
BACKEND_OPTS = ''
DBLATEX_OPTS = ''
FOP_OPTS = ''
LYNX_OPTS = '-dump'
W3M_OPTS = '-dump -cols 70 -T text/html -no-graph'
XSLTPROC_OPTS = ''

توجه داشته باشید که امکان بازتعریف W3M و LYNX برای استفاده از مرورگرهای متنی متفاوت وجود دارد؛ به عنوان مثال links: http://links.twibright.com یا elinks: http://elinks.or.cz. متغیرهای LYNX_OPTS و W3M_OPTS می‌توانند برای ارسال گزینه‌ها به مرورگر انتخاب‌شده استفاده شوند. در صورت تعریف شدن، این متغیرها مقادیر پیش‌فرض مربوطه را که در بالا ذکر شد بازنویسی می‌کنند (بنابراین فراموش نکنید که گزینهٔ -dump را در تعریف خود بگنجانید: این کار دست‌کم در مورد w3m، lynx، links و elinks برای ارسال متن قالب‌بندی‌شده به stdout الزامی است).

اشکالات (BUGS)

فایل BUGS در توزیع AsciiDoc را ببینید.

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

برنامهٔ a2x در ابتدا توسط Stuart Rackham نوشته شد. افراد زیادی در توسعه آن مشارکت داشته‌اند.

منابع (RESOURCES)

گیت‌هاب: https://github.com/asciidoc/asciidoc-py3

وب‌سایت اصلی: https://asciidoc.org

همچنین ببینید (SEE ALSO)

asciidoc(1)

حق نشر (COPYING)

استفاده رایگان از این نرم‌افزار تحت شرایط مجوز عمومی همگانی گنو (GNU General Public License) منتشرشده توسط بنیاد نرم‌افزارهای آزاد (Free Software Foundation) مجاز است؛ یا نسخه ۲ مجوز، یا (به انتخاب شما) هر نسخهٔ بعدی.

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