RONN(1) Ronn Manual RONN(1)

ronn - تبدیل فایل‌های markdown به صفحات راهنما

ronn [format...] file...
ronn -m|--man file...
ronn -S|--server file...
ronn --pipe file
ronn < file
ronn -E|--encoding encoding ...

دستور Ronn فایل‌های متنی را به صفحات راهنمای استاندارد یونیکس با قالب roff یا HTML تبدیل می‌کند. قالب ronn-format(7) بر پایهٔ markdown(7) است اما شامل قواعد و نحو اضافه‌ای با هدف نگارش صفحات راهنما می‌باشد.

در حالت پیش‌فرض، ronn یک یا چند file ورودی را به فایل‌های خروجی HTML یا roff تبدیل می‌کند. گزینه‌های --roff، --html، و --fragment مشخص می‌کنند که کدام فایل‌های خروجی تولید شوند. می‌توان چند آرگومان قالب برای تولید چندین فایل خروجی مشخص کرد. فایل‌های خروجی هم‌نام با fileهای ورودی نام‌گذاری شده و در همان دایرکتوری نوشته می‌شوند.

گزینه‌های --server و --man رفتار خروجی را از تولید فایل به میزبانی صفحات راهنمای HTML تولیدشده به‌صورت پویا یا مشاهدهٔ file همانند man(1) تغییر می‌دهند.

در صورت مشخص نشدن آرگومان‌های file، دستور ronn به‌عنوان یک پالایه (فیلتر) ساده عمل می‌کند. متن منبع Ronn از ورودی استاندارد خوانده شده و خروجی roff در خروجی استاندارد نوشته می‌شود. برای انتخاب قالب خروجی از گزینه‌های --html، --roff، و/یا --fragment استفاده کنید.

دستور ronn انتظار دارد که ورودی، متنی با قالب معتبر ronn-format(7) باشد. فایل‌های منبع معمولاً به‌صورت name.section.ronn نام‌گذاری می‌شوند (برای مثال example.1.ronn). بخش‌های name و section باید با نام و بخش تعریف‌شده در سربرگ file مطابقت داشته باشند.

صرف‌نظر از locale مشخص‌شده در سیستم که ronn تحت آن اجرا می‌شود، فایل‌های منبع باید دارای کدگذاری UTF-8 یا کدگذاری تعیین‌شده توسط گزینهٔ -E/--encoding باشند.

هنگام ساخت فایل‌های خروجی roff یا HTML، نام فایل‌های مقصد با گرفتن نام پایهٔ (basename) file ورودی و افزودن پسوند مناسب (یا حذف پسوند در مورد خروجی roff) تعیین می‌شود. برای مثال، اجرای ronn example.1.ronn فایل example.1 را با خروجی roff و فایل example.1.html را با خروجی HTML تولید می‌کند.

این گزینه‌ها تعیین می‌کنند که خروجی در فایل(ها)، خروجی استاندارد، یا مستقیماً در یک صفحه‌بندی‌کنندهٔ (pager) راهنما نوشته شود.

فایلی تولید نکن؛ fileها را به‌گونه‌ای نمایش بده که گویی man(1) روی فایل خروجی roff فراخوانی شده است. این حالت رفتار پیش‌فرض man را با هدایت خروجی roff از طریق لوله به groff(1) و برنامهٔ صفحه‌بندی مشخص‌شده در متغیر محیطی MANPAGER شبیه‌سازی می‌کند.
فایلی تولید نکن؛ یک کارساز HTTP روی http://localhost:1207 راه‌اندازی کن و صفحات HTML را به‌صورت پویا برای مجموعهٔ fileهای ورودی ارائه بده. فایلی با نام example.2.ronn به‌صورت /example.2.html ارائه می‌شود. همچنین یک صفحهٔ فهرست در ریشه قرار دارد که به هر file پیوند دارد.
کارساز به گزینهٔ --style و گزینه‌های ویژگی سند (--manual، --date و غیره) احترام می‌گذارد. همین گزینه‌ها را می‌توان در زمان درخواست با ارسال آن‌ها به‌عنوان پارامترهای پرسمان (query parameters) تغییر داد: ?manual=FOO&style=dark,toc
نکته: کارساز توکار برای کمک به روند نگارش و شیوه‌دهی به صفحات راهنما طراحی شده است. استفاده از آن به‌عنوان یک کارساز وب با کاربرد عمومی به‌هیچ‌وجه توصیه نمی‌شود.
هنگام استفاده با -S/--server، کارساز را روی درگاه مشخص‌شده به جای درگاه پیش‌فرض 1207 اجرا می‌کند.
فایلی تولید نکن؛ خروجی تولیدشده را در خروجی استاندارد بنویس. این رفتار پیش‌فرض هنگامی است که متن منبع ronn از ورودی استاندارد لوله‌کشی می‌شود و هیچ آرگومان file مشخص نشده است.
نوشتن فایل‌های تولیدشده در دایرکتوری مشخص‌شده به جای مکان پیش‌فرض.
کدگذاری فایل‌های ورودی را مشخص می‌کند. پیش‌فرض UTF-8 است، صرف‌نظر از تنظیمات locale کاربر. ورودی ارسال‌شده به STDIN همواره به‌صورت UTF-8 پردازش می‌شود، چه -E داده شده باشد چه نباشد.

گزینه‌های قالب‌بندی تعیین می‌کنند که ronn چه فایل‌هایی را تولید کند، یا در صورت مشخص شدن آرگومان --pipe قالب خروجی چه باشد. هنگامی که هیچ گزینهٔ قالبی داده نشود، هر دو حالت --roff و --html در نظر گرفته می‌شوند.

تولید خروجی roff. این رفتار پیش‌فرض هنگامی است که هیچ file ورودی داده نشده باشد و متن منبع ronn از ورودی استاندارد خوانده شود.
-5, --html
تولید خروجی در قالب HTML.
تولید خروجی در قالب HTML اما تنها بخش بدنهٔ سند (fragment)، بدون سربرگ، عنوان، یا پانویس.

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

نام کتابچهٔ راهنمایی که این صفحه به آن تعلق دارد؛ manual به‌صورت برجسته در بالا و مرکز ناحیهٔ سربرگ نمایش می‌یابد.
نام گروه، سازمان یا فرد مسئول انتشار سند؛ name در پایین و سمت چپ ناحیهٔ پانویس نمایش داده می‌شود.
تاریخ انتشار سند؛ date باید در قالب YYYY-MM-DD باشد و در پایین و مرکز ناحیهٔ پانویس نمایش می‌یابد. در صورت مشخص نشدن date، از زمان اصلاح فایل (mtime) مربوط به file، و در صورت در دسترس نبودن file از زمان فعلی استفاده می‌شود.

خروجی HTML را می‌توان با استفاده از شیوه‌نامه‌های CSS سفارشی‌سازی کرد:

فهرست شیوه‌نامه‌های CSS برای اعمال به سند. می‌توان چندین آرگومان module را با ویرگول یا فاصله از هم جدا کرد.
هنگامی که module یک واژهٔ ساده باشد، فایل‌هایی به نام module.css ابتدا در تمام دایرکتوری‌های فهرست‌شده در متغیر محیطی RONN_STYLE و سپس در شیوه‌های داخلی جستجو می‌شوند.
هنگامی که module شامل نویسهٔ / باشد، به‌عنوان مسیر کامل به یک فایل شیوه‌نامه استفاده می‌شود.
شیوه‌های داخلی عبارتند از man (که به‌طور پیش‌فرض گنجانده شده است)، toc، و 80c. برای توضیحات مربوط به ویژگی‌های ارائه‌شده توسط هر پودمان، بخش STYLES را ببینید.

گزینه‌های متفرقه:

نمایش هشدارهای troff در خطای استاندارد هنگام تبدیل به roff. هشدارها اغلب ناشی از یک اشکال در منطق تبدیل HTML به roff در ronn هستند.
غیرفعال کردن هشدارهای troff. هشدارها به‌طور پیش‌فرض غیرفعال هستند. این گزینه می‌تواند برای بازگرداندن اثر آرگومان قبلی -w استفاده شود.
نمایش نگارش ronn و خروج.

هنگام تولید خروجی HTML، دستور ronn ارجاعات راهنما (مانند grep(1)، ls(1)، markdown(7)) در متن منبع را بر اساس نگاشت نام ارجاع به URL که در فایل index.txt تعریف شده، ابرپیوند می‌کند. هر خط از فایل نمایه، یک پیوند ارجاع منفرد را توصیف می‌کند که در آن نویسهٔ فاصله، id ارجاع را از location آن جدا می‌سازد. خطوط خالی مجاز هستند؛ خطوطی که با نویسهٔ # آغاز می‌شوند نادیده گرفته می‌شوند:

# 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

مقدار location یک URL مطلق یا نسبی است که معمولاً به نگارش HTML یک صفحهٔ راهنما اشاره دارد. همچنین امکان تعریف ارجاعات برای مواردی غیر از صفحات راهنما وجود دارد.

تمام کتابچه‌های راهنما در یک دایرکتوری واحد، در ارجاعات تعریف‌شده در فایل index.txt آن دایرکتوری مشترک هستند. ارجاعات نمایه را می‌توان با استفاده از نحو زیر به‌طور صریح در پیوندهای مرجع Markdown استفاده کرد: [text][id]، که در آن text متن پیوند و id نام ارجاع تعریف‌شده در نمایه است.

گزینهٔ --style فهرستی از شیوه‌نامه‌های CSS را برای گنجاندن در HTML تولیدشده انتخاب می‌کند. شیوه‌ها به ترتیبی که تعریف شده‌اند اعمال می‌شوند، بنابراین هر یک می‌توانند با رفتار آبشاری شیوه‌های پیشین را بازنویسی کنند.

این شیوه‌ها همراه با بسته ارائه شده‌اند:

شیوه‌های پایهٔ صفحهٔ راهنما: نویسه‌نگاری، فهرست‌های تعاریف، دندانه‌گذاری. این مورد صرف‌نظر از آرگومان --style همواره گنجانده می‌شود. با این وجود، می‌توان با قرار دادن فایل man.css در مسیر RONN_STYLE، پودمان پیش‌فرض man را با یک نمونهٔ سفارشی جایگزین کرد.
شیوه‌نامهٔ پایه برای چاپ. برچسب <style> تولیدشده شامل ویژگی media=print خواهد بود.
بخش ناوبری فهرست مطالب را فعال می‌کند. ساختار TOC به‌طور پیش‌فرض در HTML تولیدشده گنجانده می‌شود اما با یک قاعدهٔ شیوهٔ درون‌خطی به‌صورت display:none پنهان است؛ پودمان toc آن را فعال کرده و شیوه‌های پایهٔ TOC را اعمال می‌کند.
متن روشن بر روی پس‌زمینهٔ تیره.
80c
عرض نمایش را برای شبیه‌سازی یک پایانهٔ کلاسیک ۸۰ نویسه‌ای تغییر می‌دهد. عرض پیش‌فرض باعث می‌شود خطوط در ۱۰۰ نویسه شکسته شوند.

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

.mp
عنصر دربرگیرندهٔ صفحهٔ راهنما. در اسناد کامل و بخش‌های سند موجود است.
مشخص می‌کند که صفحه به‌طور کامل توسط Ronn تولید شده و شامل یک صفحهٔ راهنمای منفرد (عنصر .mp) است.
.man-decor
عناصر سه‌بخشی سربرگ و پانویس هر دو این رده را دارند.
.man-head, .man-foot
به‌ترتیب سربرگ و پانویس.
.man-title
عنصر اصلی <h1>. به‌طور پیش‌فرض پنهان است مگر این‌که کتابچهٔ راهنما ویژگی‌های name یا section را نداشته باشد.

برای مشاهدهٔ نمونه‌ها، کدهای منبع شیوه‌های توکار را در https://github.com/apjanke/ronn-ng/tree/main/lib/ronn/template ببینید.

ساخت فایل‌های خروجی roff و HTML و مشاهدهٔ صفحهٔ راهنمای roff با استفاده از man(1):

$ ronn some-great-program.1.ronn
roff: some-great-program.1
html: some-great-program.1.html
$ man ./some-great-program.1

تنها ساخت صفحهٔ راهنمای roff برای تمام فایل‌های .ronn در دایرکتوری جاری:

$ ronn --roff *.ronn
roff: mv.1
roff: ls.1
roff: cd.1
roff: sh.1

تنها ساخت صفحهٔ راهنمای HTML برای چند فایل و اعمال شیوه‌نامه‌های dark و toc:

$ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn
html: mv.1.html
html: ls.1.html

تولید خروجی roff در خروجی استاندارد و نوشتن آن در فایل:

$ ronn <hello.1.ronn >hello.1

مشاهدهٔ یک فایل ronn بدون ساخت فایل roff، دقیقاً مشابه man(1):

$ ronn --man hello.1.ronn

میزبانی صفحات راهنمای HTML روی http://localhost:1207 برای تمام فایل‌های *.ronn موجود در دایرکتوری man/:

$ ronn --server man/*.ronn
$ open http://localhost:1207

نام پیش‌فرض کتابچهٔ راهنما برای نمایش در بالا و مرکز ناحیهٔ سربرگ. گزینهٔ --manual نسبت به این مقدار اولویت دارد.
گروه، سازمان یا شخص ناشر پیش‌فرض کتابچهٔ راهنما برای نمایش در پایین و سمت چپ ناحیهٔ پانویس. گزینهٔ --organization نسبت به این مقدار اولویت دارد.
تاریخ پیش‌فرض کتابچهٔ راهنما در قالب YYYY-MM-DD. در پایین و مرکز ناحیهٔ پانویس نمایش داده می‌شود. گزینهٔ --date نسبت به این مقدار اولویت دارد.
فهرستی به سبک متغیر PATH از دایرکتوری‌ها جهت جستجوی شیوه‌نامه‌های داده‌شده به گزینهٔ --style. دایرکتوری‌ها با : از هم جدا می‌شوند؛ ورودی‌های خالی نادیده گرفته می‌شوند. برای گنجاندن دایرکتوری کاری جاری از . استفاده کنید.
برنامهٔ صفحه‌بندی مورد استفاده برای صفحات راهنما. این متغیر معمولاً روی مقداری مانند 'less -is' تنظیم می‌شود.
در صورتی که MANPAGER تعریف نشده باشد، به جای آن استفاده می‌شود.

حق نشر نرم‌افزار Ronn-NG متعلق است به: (C) 2009 Ryan Tomayko https://tomayko.com/about و (C) 2018-2023 Andrew Janke https://apjanke.net و سایر مشارکت‌کنندگان. برای جزئیات کامل، فایل AUTHORS موجود در توزیع Ronn-NG را ببینید.

groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn-format(7)

January 2024 Ronn-NG 0.10.1