.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "RONN" "1" "January 2024" "Ronn-NG 0.10.1" "Ronn Manual"
.SH "نام (NAME)"
\fBronn\fR \- تبدیل فایل‌های markdown به صفحات راهنما
.SH "خلاصه دستور (SYNOPSIS)"
\fBronn\fR [\fIformat\fR\|\.\|\.\|\.] \fIfile\fR\|\.\|\.\|\.
.br
\fBronn\fR \fB\-m\fR|\fB\-\-man\fR \fIfile\fR\|\.\|\.\|\.
.br
\fBronn\fR \fB\-S\fR|\fB\-\-server\fR \fIfile\fR\|\.\|\.\|\.
.br
\fBronn\fR \fB\-\-pipe\fR \fIfile\fR
.br
\fBronn\fR < \fIfile\fR
.br
\fBronn\fR \fB\-E\fR|\fB\-\-encoding\fR \fIencoding\fR \|\.\|\.\|\.
.SH "توضیحات (DESCRIPTION)"
دستور \fBRonn\fR فایل‌های متنی را به صفحات راهنمای استاندارد یونیکس با قالب roff یا HTML تبدیل می‌کند\. قالب ronn\-format(7) بر پایهٔ markdown(7) است اما شامل قواعد و نحو اضافه‌ای با هدف نگارش صفحات راهنما می‌باشد\.
.P
در حالت پیش‌فرض، \fBronn\fR یک یا چند \fIfile\fR ورودی را به فایل‌های خروجی HTML یا roff تبدیل می‌کند\. گزینه‌های \fB\-\-roff\fR، \fB\-\-html\fR، و \fB\-\-fragment\fR مشخص می‌کنند که کدام فایل‌های خروجی تولید شوند\. می‌توان چند آرگومان قالب برای تولید چندین فایل خروجی مشخص کرد\. فایل‌های خروجی هم‌نام با \fIfile\fRهای ورودی نام‌گذاری شده و در همان دایرکتوری نوشته می‌شوند\.
.P
گزینه‌های \fB\-\-server\fR و \fB\-\-man\fR رفتار خروجی را از تولید فایل به میزبانی صفحات راهنمای HTML تولیدشده به‌صورت پویا یا مشاهدهٔ \fIfile\fR همانند man(1) تغییر می‌دهند\.
.P
در صورت مشخص نشدن آرگومان‌های \fIfile\fR، دستور \fBronn\fR به‌عنوان یک پالایه (فیلتر) ساده عمل می‌کند\. متن منبع Ronn از ورودی استاندارد خوانده شده و خروجی roff در خروجی استاندارد نوشته می‌شود\. برای انتخاب قالب خروجی از گزینه‌های \fB\-\-html\fR، \fB\-\-roff\fR، و/یا \fB\-\-fragment\fR استفاده کنید\.
.SH "فایل‌ها (FILES)"
دستور \fBronn\fR انتظار دارد که ورودی، متنی با قالب معتبر ronn\-format(7) باشد\. فایل‌های منبع معمولاً به‌صورت \fIname\fR\.\fIsection\fR\.ronn نام‌گذاری می‌شوند (برای مثال \fBexample\.1\.ronn\fR)\. بخش‌های \fIname\fR و \fIsection\fR باید با نام و بخش تعریف‌شده در سربرگ \fIfile\fR مطابقت داشته باشند\.
.P
صرف‌نظر از locale مشخص‌شده در سیستم که \fBronn\fR تحت آن اجرا می‌شود، فایل‌های منبع باید دارای کدگذاری UTF\-8 یا کدگذاری تعیین‌شده توسط گزینهٔ \fB\-E\fR/\fB\-\-encoding\fR باشند\.
.P
هنگام ساخت فایل‌های خروجی roff یا HTML، نام فایل‌های مقصد با گرفتن نام پایهٔ (basename) \fIfile\fR ورودی و افزودن پسوند مناسب (یا حذف پسوند در مورد خروجی roff) تعیین می‌شود\. برای مثال، اجرای \fBronn example\.1\.ronn\fR فایل \fBexample\.1\fR را با خروجی roff و فایل \fBexample\.1\.html\fR را با خروجی HTML تولید می‌کند\.
.SH "گزینه‌ها (OPTIONS)"
این گزینه‌ها تعیین می‌کنند که خروجی در فایل(ها)، خروجی استاندارد، یا مستقیماً در یک صفحه‌بندی‌کنندهٔ (pager) راهنما نوشته شود\.
.TP
\fB\-m\fR, \fB\-\-man\fR
فایلی تولید نکن؛ \fIfile\fRها را به‌گونه‌ای نمایش بده که گویی man(1) روی فایل خروجی roff فراخوانی شده است\. این حالت رفتار پیش‌فرض man را با هدایت خروجی roff از طریق لوله به groff(1) و برنامهٔ صفحه‌بندی مشخص‌شده در متغیر محیطی \fBMANPAGER\fR شبیه‌سازی می‌کند\.
.TP
\fB\-S\fR, \fB\-\-server\fR
فایلی تولید نکن؛ یک کارساز HTTP روی \fIhttp://localhost:1207\fR راه‌اندازی کن و صفحات HTML را به‌صورت پویا برای مجموعهٔ \fIfile\fRهای ورودی ارائه بده\. فایلی با نام \fIexample\.2\.ronn\fR به‌صورت \fI/example\.2\.html\fR ارائه می‌شود\. همچنین یک صفحهٔ فهرست در ریشه قرار دارد که به هر \fIfile\fR پیوند دارد\.
.IP
کارساز به گزینهٔ \fB\-\-style\fR و گزینه‌های ویژگی سند (\fB\-\-manual\fR، \fB\-\-date\fR و غیره) احترام می‌گذارد\. همین گزینه‌ها را می‌توان در زمان درخواست با ارسال آن‌ها به‌عنوان پارامترهای پرسمان (query parameters) تغییر داد: \fB?manual=FOO&style=dark,toc\fR
.IP
\fIنکته: کارساز توکار برای کمک به روند نگارش و شیوه‌دهی به صفحات راهنما طراحی شده است\. استفاده از آن به‌عنوان یک کارساز وب با کاربرد عمومی به‌هیچ‌وجه توصیه نمی‌شود\.\fR
.TP
\fB\-\-port\fR=\fIport\fR
هنگام استفاده با \fB\-S\fR/\fB\-\-server\fR، کارساز را روی درگاه مشخص‌شده به جای درگاه پیش‌فرض 1207 اجرا می‌کند\.
.TP
\fB\-\-pipe\fR
فایلی تولید نکن؛ خروجی تولیدشده را در خروجی استاندارد بنویس\. این رفتار پیش‌فرض هنگامی است که متن منبع ronn از ورودی استاندارد لوله‌کشی می‌شود و هیچ آرگومان \fIfile\fR مشخص نشده است\.
.TP
\fB\-o\fR=\fIdirectory\fR, \fB\-\-output\-dir\fR=\fIdirectory\fR
نوشتن فایل‌های تولیدشده در دایرکتوری مشخص‌شده به جای مکان پیش‌فرض\.
.TP
\fB\-E\fR=\fIencoding\fR, \fB\-\-encoding\fR=\fIencoding\fR
کدگذاری فایل‌های ورودی را مشخص می‌کند\. پیش‌فرض UTF\-8 است، صرف‌نظر از تنظیمات locale کاربر\. ورودی ارسال‌شده به STDIN همواره به‌صورت UTF\-8 پردازش می‌شود، چه \fB\-E\fR داده شده باشد چه نباشد\.
.P
گزینه‌های قالب‌بندی تعیین می‌کنند که \fBronn\fR چه فایل‌هایی را تولید کند، یا در صورت مشخص شدن آرگومان \fB\-\-pipe\fR قالب خروجی چه باشد\. هنگامی که هیچ گزینهٔ قالبی داده نشود، هر دو حالت \fB\-\-roff\fR و \fB\-\-html\fR در نظر گرفته می‌شوند\.
.TP
\fB\-r\fR, \fB\-\-roff\fR
تولید خروجی roff\. این رفتار پیش‌فرض هنگامی است که هیچ \fIfile\fR ورودی داده نشده باشد و متن منبع ronn از ورودی استاندارد خوانده شود\.
.TP
\fB\-5\fR, \fB\-\-html\fR
تولید خروجی در قالب HTML\.
.TP
\fB\-f\fR, \fB\-\-fragment\fR
تولید خروجی در قالب HTML اما تنها بخش بدنهٔ سند (fragment)، بدون سربرگ، عنوان، یا پانویس\.
.P
ویژگی‌های سند که در نواحی سربرگ و پانویس محتوای تولیدشده نمایش داده می‌شوند با این گزینه‌ها مشخص می‌گردند\. (این مقادیر را می‌توان از طریق متغیرهای محیطی نیز تنظیم کرد\.)
.TP
\fB\-\-manual\fR=\fImanual\fR
نام کتابچهٔ راهنمایی که این صفحه به آن تعلق دارد؛ \fImanual\fR به‌صورت برجسته در بالا و مرکز ناحیهٔ سربرگ نمایش می‌یابد\.
.TP
\fB\-\-organization\fR=\fIname\fR
نام گروه، سازمان یا فرد مسئول انتشار سند؛ \fIname\fR در پایین و سمت چپ ناحیهٔ پانویس نمایش داده می‌شود\.
.TP
\fB\-\-date\fR=\fIdate\fR
تاریخ انتشار سند؛ \fIdate\fR باید در قالب \fBYYYY\-MM\-DD\fR باشد و در پایین و مرکز ناحیهٔ پانویس نمایش می‌یابد\. در صورت مشخص نشدن \fIdate\fR، از زمان اصلاح فایل (mtime) مربوط به \fIfile\fR، و در صورت در دسترس نبودن \fIfile\fR از زمان فعلی استفاده می‌شود\.
.P
خروجی HTML را می‌توان با استفاده از شیوه‌نامه‌های CSS سفارشی‌سازی کرد:
.TP
\fB\-\-style\fR=\fImodule\fR[,\fImodule\fR]\|\.\|\.\|\.
فهرست شیوه‌نامه‌های CSS برای اعمال به سند\. می‌توان چندین آرگومان \fImodule\fR را با ویرگول یا فاصله از هم جدا کرد\.
.IP
هنگامی که \fImodule\fR یک واژهٔ ساده باشد، فایل‌هایی به نام \fImodule\fR\fB\.css\fR ابتدا در تمام دایرکتوری‌های فهرست‌شده در متغیر محیطی \fI\fBRONN_STYLE\fR\fR و سپس در شیوه‌های داخلی جستجو می‌شوند\.
.IP
هنگامی که \fImodule\fR شامل نویسهٔ \fI/\fR باشد، به‌عنوان مسیر کامل به یک فایل شیوه‌نامه استفاده می‌شود\.
.IP
شیوه‌های داخلی عبارتند از \fIman\fR (که به‌طور پیش‌فرض گنجانده شده است)، \fItoc\fR، و \fI80c\fR\. برای توضیحات مربوط به ویژگی‌های ارائه‌شده توسط هر پودمان، بخش \fISTYLES\fR را ببینید\.
.P
گزینه‌های متفرقه:
.TP
\fB\-w\fR, \fB\-\-warnings\fR
نمایش هشدارهای troff در خطای استاندارد هنگام تبدیل به roff\. هشدارها اغلب ناشی از یک اشکال در منطق تبدیل HTML به roff در ronn هستند\.
.TP
\fB\-W\fR
غیرفعال کردن هشدارهای troff\. هشدارها به‌طور پیش‌فرض غیرفعال هستند\. این گزینه می‌تواند برای بازگرداندن اثر آرگومان قبلی \fB\-w\fR استفاده شود\.
.TP
\fB\-v\fR, \fB\-\-version\fR
نمایش نگارش ronn و خروج\.
.SH "نمایه‌های پیوند (LINK INDEXES)"
هنگام تولید خروجی HTML، دستور \fBronn\fR ارجاعات راهنما (مانند \fBgrep(1)\fR، \fBls(1)\fR، \fBmarkdown(7)\fR) در متن منبع را بر اساس نگاشت نام ارجاع به URL که در فایل \fBindex\.txt\fR تعریف شده، ابرپیوند می‌کند\. هر خط از فایل نمایه، یک پیوند ارجاع منفرد را توصیف می‌کند که در آن نویسهٔ فاصله، \fIid\fR ارجاع را از \fIlocation\fR آن جدا می‌سازد\. خطوط خالی مجاز هستند؛ خطوطی که با نویسهٔ \fB#\fR آغاز می‌شوند نادیده گرفته می‌شوند:
.IP "" 4
.nf
# manuals included in this project:
whisky(1)    whisky\.1\.ronn
tango(5)     tango\.5\.ronn

# external manuals
grep(1)      https://man7\.org/linux/man\-pages/man1/grep\.1\.html
ls(1)        https://man7\.org/linux/man\-pages/man1/ls\.1\.html

# other URLs for use with markdown reference links
src          https://github\.com
.fi
.IP "" 0
.P
مقدار \fIlocation\fR یک URL مطلق یا نسبی است که معمولاً به نگارش HTML یک صفحهٔ راهنما اشاره دارد\. همچنین امکان تعریف ارجاعات برای مواردی غیر از صفحات راهنما وجود دارد\.
.P
تمام کتابچه‌های راهنما در یک دایرکتوری واحد، در ارجاعات تعریف‌شده در فایل \fBindex\.txt\fR آن دایرکتوری مشترک هستند\. ارجاعات نمایه را می‌توان با استفاده از نحو زیر به‌طور صریح در پیوندهای مرجع Markdown استفاده کرد: \fB[\fR\fItext\fR\fB][\fR\fIid\fR\fB]\fR، که در آن \fItext\fR متن پیوند و \fIid\fR نام ارجاع تعریف‌شده در نمایه است\.
.SH "شیوه‌ها (STYLES)"
گزینهٔ \fB\-\-style\fR فهرستی از شیوه‌نامه‌های CSS را برای گنجاندن در HTML تولیدشده انتخاب می‌کند\. شیوه‌ها به ترتیبی که تعریف شده‌اند اعمال می‌شوند، بنابراین هر یک می‌توانند با رفتار آبشاری شیوه‌های پیشین را بازنویسی کنند\.
.SS "شیوه‌نامه‌های توکار (Builtin Stylesheets)"
این شیوه‌ها همراه با بسته ارائه شده‌اند:
.TP
\fBman\fR
شیوه‌های پایهٔ صفحهٔ راهنما: نویسه‌نگاری، فهرست‌های تعاریف، دندانه‌گذاری\. این مورد صرف‌نظر از آرگومان \fB\-\-style\fR همواره گنجانده می‌شود\. با این وجود، می‌توان با قرار دادن فایل \fBman\.css\fR در مسیر \fBRONN_STYLE\fR، پودمان پیش‌فرض \fBman\fR را با یک نمونهٔ سفارشی جایگزین کرد\.
.TP
\fBprint\fR
شیوه‌نامهٔ پایه برای چاپ\. برچسب \fB<style>\fR تولیدشده شامل ویژگی \fBmedia=print\fR خواهد بود\.
.TP
\fBtoc\fR
بخش ناوبری فهرست مطالب را فعال می‌کند\. ساختار TOC به‌طور پیش‌فرض در HTML تولیدشده گنجانده می‌شود اما با یک قاعدهٔ شیوهٔ درون‌خطی به‌صورت \fBdisplay:none\fR پنهان است؛ پودمان \fBtoc\fR آن را فعال کرده و شیوه‌های پایهٔ TOC را اعمال می‌کند\.
.TP
\fBdark\fR
متن روشن بر روی پس‌زمینهٔ تیره\.
.TP
\fB80c\fR
عرض نمایش را برای شبیه‌سازی یک پایانهٔ کلاسیک ۸۰ نویسه‌ای تغییر می‌دهد\. عرض پیش‌فرض باعث می‌شود خطوط در ۱۰۰ نویسه شکسته شوند\.
.SS "شیوه‌نامه‌های سفارشی (Custom Stylesheets)"
نوشتن شیوه‌نامه‌های سفارشی ساده و سرراست است\. انتخاب‌گرهای اصلی زیر امکان هدف قرار دادن تمامی عناصر تولیدشده را فراهم می‌کنند:
.TP
\fB\.mp\fR
عنصر دربرگیرندهٔ صفحهٔ راهنما\. در اسناد کامل و بخش‌های سند موجود است\.
.TP
\fBbody#manpage\fR
مشخص می‌کند که صفحه به‌طور کامل توسط Ronn تولید شده و شامل یک صفحهٔ راهنمای منفرد (عنصر \fB\.mp\fR) است\.
.TP
\fB\.man\-decor\fR
عناصر سه‌بخشی سربرگ و پانویس هر دو این رده را دارند\.
.TP
\fB\.man\-head\fR, \fB\.man\-foot\fR
به‌ترتیب سربرگ و پانویس\.
.TP
\fB\.man\-title\fR
عنصر اصلی \fB<h1>\fR\. به‌طور پیش‌فرض پنهان است مگر این‌که کتابچهٔ راهنما ویژگی‌های \fIname\fR یا \fIsection\fR را نداشته باشد\.
.P
برای مشاهدهٔ نمونه‌ها، کدهای منبع شیوه‌های توکار را در \fIhttps://github\.com/apjanke/ronn\-ng/tree/main/lib/ronn/template\fR ببینید\.
.SH "مثال‌ها (EXAMPLES)"
ساخت فایل‌های خروجی roff و HTML و مشاهدهٔ صفحهٔ راهنمای roff با استفاده از man(1):
.IP "" 4
.nf
$ ronn some\-great\-program\.1\.ronn
roff: some\-great\-program\.1
html: some\-great\-program\.1\.html
$ man \./some\-great\-program\.1
.fi
.IP "" 0
.P
تنها ساخت صفحهٔ راهنمای roff برای تمام فایل‌های \fB\.ronn\fR در دایرکتوری جاری:
.IP "" 4
.nf
$ ronn \-\-roff *\.ronn
roff: mv\.1
roff: ls\.1
roff: cd\.1
roff: sh\.1
.fi
.IP "" 0
.P
تنها ساخت صفحهٔ راهنمای HTML برای چند فایل و اعمال شیوه‌نامه‌های \fBdark\fR و \fBtoc\fR:
.IP "" 4
.nf
$ ronn \-\-html \-\-style=dark,toc mv\.1\.ronn ls\.1\.ronn
html: mv\.1\.html
html: ls\.1\.html
.fi
.IP "" 0
.P
تولید خروجی roff در خروجی استاندارد و نوشتن آن در فایل:
.IP "" 4
.nf
$ ronn <hello\.1\.ronn >hello\.1
.fi
.IP "" 0
.P
مشاهدهٔ یک فایل ronn بدون ساخت فایل roff، دقیقاً مشابه man(1):
.IP "" 4
.nf
$ ronn \-\-man hello\.1\.ronn
.fi
.IP "" 0
.P
میزبانی صفحات راهنمای HTML روی \fIhttp://localhost:1207\fR برای تمام فایل‌های \fB*\.ronn\fR موجود در دایرکتوری \fBman/\fR:
.IP "" 4
.nf
$ ronn \-\-server man/*\.ronn
$ open http://localhost:1207
.fi
.IP "" 0
.SH "محیط (ENVIRONMENT)"
.TP
\fBRONN_MANUAL\fR
نام پیش‌فرض کتابچهٔ راهنما برای نمایش در بالا و مرکز ناحیهٔ سربرگ\. گزینهٔ \fB\-\-manual\fR نسبت به این مقدار اولویت دارد\.
.TP
\fBRONN_ORGANIZATION\fR
گروه، سازمان یا شخص ناشر پیش‌فرض کتابچهٔ راهنما برای نمایش در پایین و سمت چپ ناحیهٔ پانویس\. گزینهٔ \fB\-\-organization\fR نسبت به این مقدار اولویت دارد\.
.TP
\fBRONN_DATE\fR
تاریخ پیش‌فرض کتابچهٔ راهنما در قالب \fBYYYY\-MM\-DD\fR\. در پایین و مرکز ناحیهٔ پانویس نمایش داده می‌شود\. گزینهٔ \fB\-\-date\fR نسبت به این مقدار اولویت دارد\.
.TP
\fBRONN_STYLE\fR
فهرستی به سبک متغیر \fBPATH\fR از دایرکتوری‌ها جهت جستجوی شیوه‌نامه‌های داده‌شده به گزینهٔ \fB\-\-style\fR\. دایرکتوری‌ها با \fI:\fR از هم جدا می‌شوند؛ ورودی‌های خالی نادیده گرفته می‌شوند\. برای گنجاندن دایرکتوری کاری جاری از \fI\.\fR استفاده کنید\.
.TP
\fBMANPAGER\fR
برنامهٔ صفحه‌بندی مورد استفاده برای صفحات راهنما\. این متغیر معمولاً روی مقداری مانند \(aqless \-is\(aq تنظیم می‌شود\.
.TP
\fBPAGER\fR
در صورتی که \fBMANPAGER\fR تعریف نشده باشد، به جای آن استفاده می‌شود\.
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
حق نشر نرم‌افزار Ronn\-NG متعلق است به: (C) 2009 Ryan Tomayko \fIhttps://tomayko\.com/about\fR و (C) 2018\-2023 Andrew Janke \fIhttps://apjanke\.net\fR و سایر مشارکت‌کنندگان\. برای جزئیات کامل، فایل AUTHORS موجود در توزیع Ronn\-NG را ببینید\.
.SH "همچنین ببینید (SEE ALSO)"
groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn\-format(7)