.TH highlight 1 "2023-05-11" "Andre Simon" "user documentation"

.SH "نام (NAME)"
highlight \- مبدل همه‌منظوره کد منبع به متن قالب‌بندی‌شده

.SH "خلاصه دستور (SYNOPSIS)"
.B highlight
[\fIOPTIONS\fR]... [\fIFILES\fR]...

.SH "توضیحات (DESCRIPTION)"
.B Highlight
کد منبع را به HTML،‏ XHTML،‏ RTF،‏ ODT،‏ LaTeX،‏ TeX،‏ BBCode، نشانه‌گذاری Pango،‏ SVG یا توالی‌های گریز XTERM یا ANSI تبدیل می‌کند.
پوسته‌های رنگی متعددی در دسترس هستند.
.B Highlight
کلمات کلیدی، اعداد، رشته‌ها، توضیحات، نمادها و دستورهای پیش‌پردازنده را شناسایی می‌کند.
این برنامه از حدود ۱۸۰ زبان برنامه‌نویسی که در اسکریپت‌های Lua تعریف شده‌اند، پشتیبانی می‌کند.

.PP
گسترش و ارتقای پایگاه‌دادهٔ زبان‌های برنامه‌نویسی و پوسته‌های رنگی highlight به‌سادگی امکان‌پذیر است.
برای جزئیات بیشتر فایل README را ببینید.
.SH "گزینه‌های عمومی (GENERAL OPTIONS)"
.IP "\fB-B\fR, \fB--batch-recursive\fR=<\fIwildcard\fR>"
تبدیل تمام فایل‌های منطبق با نویسه عام (wildcard) (از جستجوی بازگشتی استفاده می‌کند)
.IP "\fB-D\fR, \fB--data-dir\fR=<\fIpath\fR>"
تنظیم مسیر به دایرکتوری داده‌های highlight
.IP "\fB--config-file\fR=<\fIfile\fR>"
تنظیم مسیر به یک فایل زبان یا پوسته
.IP "\fB-h\fR, \fB--help\fR[=\fItopic\fR]"
چاپ این راهنما یا توضیح یک مبحث
<topic> = [syntax, theme, plugin, config]
.IP "\fB-i\fR, \fB--input\fR=<\fIfile\fR>"
نام فایل ورودی
.IP "\fB-o\fR, \fB--output\fR=<\fIfile\fR>"
نام فایل خروجی
.IP "\fB-d\fR, \fB--outdir\fR=<\fIoutput directory\fR>"
نام دایرکتوری خروجی
.IP "\fB-P\fR, \fB--progress\fR"
چاپ نوار پیشرفت در حالت دسته‌ای
.IP "\fB-S\fR, \fB--syntax\fR=<\fItype\fR|\fIpath\fR>"
تعیین نوع کد منبع، در صورت نبود پسوند فایل ورودی ضروری است. نحو می‌تواند به عنوان مسیر فایل زبان نیز تعریف شود.
.IP "\fB--syntax-by-name\fR=<\fIname\fR>"
مشخص کردن نوع کد منبع با نام ارائه‌شده. فایلی با این نام خوانده نخواهد شد؛ برای stdin و جهت تعیین نحو فایل پیش از هدایت (pipe) محتوای آن به highlight کاربرد دارد. این گزینه بر \-\-syntax اولویت دارد.
.IP "\fB--syntax-supported\fR"
بررسی اینکه آیا نحو داده‌شده قابل بارگیری است یا خیر و چاپ نتیجه (مستلزم \-S یا \-\-syntax-by-name)
.IP "\fB-v\fR, \fB--verbose\fR"
چاپ اطلاعات اشکال‌زدایی در stderr؛ برای نمایش اطلاعات بیشتر تکرار کنید
.IP "\fB-q\fR, \fB--quiet\fR"
عدم نمایش اطلاعات پیشرفت در حالت دسته‌ای
.IP "\fB--force\fR[=\fIsyntax\fR]"
تولید خروجی در صورت ناشناخته بودن نحو ورودی. نحو جایگزین می‌تواند در اینجا تعیین شود، پیش‌فرض Plain Text است.
.IP "\fB--list-scripts\fR=<\fItype\fR>"
فهرست کردن اسکریپت‌های نصب‌شده
<type> = [langs, themes, plugins]
.IP "\fB--list-cat\fR=<\fIcategories\fR>"
پالایش اسکریپت‌ها بر اساس دسته‌های داده‌شده (مثال: \-\-list\-cat=\(aqsource;script\(aq)
.IP "\fB--max-size\fR=<\fIsize\fR>"
تنظیم حداکثر اندازه فایل ورودی (مثال‌ها: 512M، 1G؛ پیش‌فرض: 256M)
.IP "\fB--skip-leading-cols\fR=<\fInum\fR>"
خروجی دادن num ستون نخست هر خط بدون برجسته‌سازی؛ این ستون‌ها خارج از تجزیه‌کننده نگه داشته می‌شوند، بنابراین نقل‌قول‌ها یا جداکننده‌های توضیح درون آن‌ها نمی‌توانند برجسته‌سازی بقیه کد را تغییر دهند (مثال: خروجی hg یا svn annotate)
.IP "\fB--plug-in\fR=<\fIscript\fR>"
اجرای اسکریپت افزونهٔ Lua؛ برای اعمال چندین افزونه این گزینه را تکرار کنید
.IP "\fB--plug-in-param\fR"
تنظیم پارامتر ورودی افزونه. این می‌تواند نام یک فایل ورودی باشد (مانند \(aqtags\(aq).
.IP "\fB--print-config\fR"
چاپ پیکربندی مسیرها
.IP "\fB--print-style\fR"
فقط چاپ شیوه‌نامه (ببینید: \-\-style-outfile)
.IP "\fB--skip\fR=<\fIlist\fR>"
نادیده گرفتن انواع ناشناختهٔ فایل‌های فهرست‌شده (مثال: \-\-skip=\(aqbak;c~;h~\(aq)
.IP "\fB--stdout\fR"
ارسال خروجی به stdout (حالت دسته‌ای، \-\-print-style)
.IP "\fB--validate-input\fR"
بررسی اینکه آیا ورودی یک فایل متنی معتبر است یا خیر
.IP "\fB--service-mode\fR"
اجرا در حالت سرویس، تا زمان دریافت سیگنال متوقف نمی‌شود
.IP "\fB--version\fR"
چاپ اطلاعات نسخه و حق تکثیر (کپی‌رایت)

.SH "گزینه‌های قالب‌بندی خروجی (OUTPUT FORMATTING OPTIONS)"
.IP "\fB-O\fR, \fB--out-format\fR=<\fIformat\fR>"
خروجی دادن فایل در قالب مشخص‌شده
<format>=[html, xhtml, latex, tex, rtf, odt, ansi, xterm256, truecolor, bbcode, pango, svg]
.IP "\fB-c\fR, \fB--style-outfile\fR=<\fIfile\fR>"
نام فایل تعریف شیوه (style)
.IP "\fB-T\fR, \fB--doc-title\fR"
عنوان سند
.IP "\fB-e\fR, \fB--style-infile\fR=<\fIfile\fR>"
نام فایلی که در style-outfile گنجانده می‌شود
.IP "\fB-f\fR, \fB--fragment\fR"
حذف سربرگ و پانویس سند خروجی (ببینید: \-\-keep-injections)
.IP "\fB-F\fR, \fB--reformat\fR=<\fIstyle\fR>"
قالب‌بندی مجدد خروجی به شیوه مشخص‌شده.
<style>=[allman, gnu, google, horstmann, java, kr, linux, lisp, mozilla, otbs, pico, vtk, ratliff, stroustrup, webkit, whitesmith]
.IP "\fB-I\fR, \fB--include-style\fR"
گنجاندن تعاریف شیوه در خروجی
.IP "\fB-J\fR, \fB--line-length\fR=<\fInum\fR>"
طول خط پیش از شکستن (ببینید: \-V، \-W)
.IP "\fB-j\fR, \fB--line-number-length\fR=<\fInum\fR>"
طول شماره خط شامل فاصله‌گذاری از چپ. طول پیش‌فرض: 5
.IP "\fB-k\fR, \fB--font\fR=<\fIfont\fR>"
تنظیم قلم (مخصوص قالب خروجی)
.IP "\fB-K\fR, \fB--font-size\fR=<\fInum?\fR>"
تنظیم اندازه قلم (مخصوص قالب خروجی)
.IP "\fB-l\fR, \fB--line-numbers\fR"
چاپ شماره خطوط در فایل خروجی
.IP "\fB-m\fR, \fB--line-number-start\fR=<\fIcnt\fR>"
شروع شماره‌گذاری خطوط از cnt (مستلزم \-l)
.IP "\fB--line-range\fR=<\fIstart\fR-\fIend\fR>"
خروجی دادن تنها خطوط از شماره <start> تا <end>
.IP "\fB--indent-guides\fR"
رسم خط راهنما در فضای خالی ابتدای هر سطح تورفتگی. خطوط خالی درون یک بلوک، تورفتگی خط بعدی را که حاوی کد است به خود می‌گیرند.
راهنماها از عنصر پوسته IndentGuide یا یک مقدار پیش‌فرض کم‌رنگ استفاده می‌کنند اگر پوسته عنصری تعریف نکرده باشد (خروجی ساده ansi همواره از پیش‌فرض کم‌رنگ استفاده می‌کند)؛ در صورتی که پهنای تب تعیین نشده باشد مستلزم \fB-t 4\fR است
.IP "\fB-s\fR, \fB--style\fR=<\fIstyle name\fR|\fIpath\fR>"
تنظیم شیوه (پوسته) برجسته‌سازی. برای استفاده از یک پوسته Base16، پیشوند \(aqbase16/\(aq را اضافه کنید. پوسته می‌تواند به عنوان مسیر فایل پوسته نیز تعریف شود.
.IP "\fB-t\fR  \fB--replace-tabs\fR=<\fInum\fR>"
جایگزینی تب‌ها با num فاصله
.IP "\fB-u\fR, \fB--encoding\fR=<\fIenc\fR>"
تنظیم کدگذاری خروجی مطابق با کدگذاری فایل ورودی؛ اگر روی "NONE" تنظیم شود، اطلاعات کدگذاری حذف می‌گردد
.IP "\fB-V\fR, \fB--wrap-simple\fR"
شکستن خطوط پس از ۸۰ نویسه (پیش‌فرض) بدون ایجاد تورفتگی برای پارامترهای توابع و عبارت‌ها.
.IP "\fB-W\fR, \fB--wrap\fR"
شکستن خطوط پس از ۸۰ نویسه (پیش‌فرض) (با احتیاط استفاده شود).
.IP "\fB-z\fR, \fB--zeroes\fR"
پر کردن فضای خالی ابتدای شماره خطوط با صفر
.IP "\fB--isolate\fR"
خروجی دادن هر نشانهٔ نحوی در برچسب‌های جداگانه (خروجی پرگو)
.IP "\fB--keep-injections\fR"
خروجی دادن تزریق‌های سربرگ و پانویس افزونه علی‌رغم استفاده از \-f
.IP "\fB--kw-case\fR=<\fIupper\fR|\fIlower\fR|\fIcapitalize\fR>"
خروجی دادن تمام کلمات کلیدی با بزرگی و کوچکی حروف داده‌شده در صورتی که زبان به بزرگی و کوچکی حروف حساس نباشد
.IP "\fB--no-trailing-nl\fR[=\fImode\fR]"
حذف خط جدید پایانی. اگر mode برابر با "empty-file" باشد، تنها برای ورودی خالی حذف می‌شود
.IP "\fB--no-version-info\fR"
حذف توضیح مربوط به اطلاعات نسخه
.IP "\fB--wrap-no-numbers\fR"
حذف شماره خطوط برای خطوط شکسته شده (مستلزم \-l)

.SH "گزینه‌های (X)HTML ((X)HTML OPTIONS)"
.IP "\fB-a\fR, \fB--anchors\fR"
افزودن لنگرگاه‌ها (anchors) به شماره خطوط (تنها در HTML)
.IP "\fB-y\fR, \fB--anchor-prefix\fR=<\fIstr\fR>"
تنظیم پیشوند نام لنگرگاه
.IP "\fB-N\fR, \fB--anchor-filename\fR"
استفاده از نام فایل ورودی به عنوان نام لنگرگاه
.IP "\fB-C\fR, \fB--print-index\fR"
چاپ فایل شاخص حاوی پیوند به تمامی فایل‌های خروجی
.IP "\fB-n\fR, \fB--ordered-list\fR"
چاپ خطوط به عنوان موارد فهرست مرتب‌شده (ordered list)
.IP "\fB--class-name\fR=<\fIstr\fR>"
تنظیم پیشوند نام کلاس CSS؛ اگر روی "NONE" تنظیم شود، نام کلاس حذف می‌شود
.IP "\fB--inline-css\fR"
خروجی دادن CSS درون هر برچسب (خروجی پرگو)
.IP "\fB--enclose-pre\fR"
محصور کردن خروجی قطعه‌بندی‌شده درون برچسب pre (مستلزم \-f)

.SH "گزینه‌های LATEX (LATEX OPTIONS)"
.IP "\fB-b\fR, \fB--babel\fR"
غیرفعال کردن میان‌برهای بسته Babel
.IP "\fB-r\fR, \fB--replace-quotes\fR"
جایگزینی نقل‌قول جفتی با \edq
.IP "\fB--beamer\fR"
تطبیق خروجی برای بسته Beamer
.IP "\fB--pretty-symbols\fR"
بهبود ظاهر براکت‌ها و سایر نمادها

.SH "گزینه‌های RTF (RTF OPTIONS)"
.IP "\fB--page-color\fR"
گنجاندن ویژگی‌های رنگ صفحه
.IP "\fB-x\fR, \fB--page-size\fR=<\fIsize\fR>"
تنظیم اندازه صفحه، <size>=[a3, a4, a5, b4, b5, b6, letter]
.IP "\fB--char-styles\fR"
گنجاندن شیوه‌نامه‌های نویسه

.SH "گزینه‌های SVG (SVG OPTIONS)"
.IP "\fB--height\fR=<\fIh\fR>"
تنظیم ارتفاع تصویر (استفاده از واحدها مجاز است)
.IP "\fB--width\fR=<\fIw\fR>"
تنظیم اندازه تصویر (ببینید: \-\-height)

.SH "گزینه‌های خروجی توالی گریز ترمینال (TERMINAL ESCAPE OUTPUT OPTIONS (XTERM256 OR TRUECOLOR))"
.IP "\fB--canvas\fR[=\fIwidth\fR]"
تنظیم فاصله‌گذاری رنگ پس‌زمینه (پیش‌فرض: 80)

.SH "گزینه‌های کارساز زبان (LANGUAGE SERVER OPTIONS)"
.IP "\fB--ls-profile\fR=<\fIserver\fR>"
بارگیری پیکربندی LSP از lsp.conf
.IP "\fB--ls-delay\fR=<\fIms\fR>"
تنظیم تأخیر راه‌اندازی اولیه کارساز بر حسب میلی‌ثانیه
.IP "\fB--ls-exec\fR=<\fIbin\fR>"
تنظیم نام فایل اجرایی کارساز
.IP "\fB--ls-option\fR=<\fIoption\fR>"
تنظیم گزینه خط فرمان برای کارساز (قابل تکرار)
.IP "\fB--ls-hover\fR"
اجرای درخواست‌های شناوری (hover) (تنها خروجی HTML)
.IP "\fB--ls-semantic\fR"
پرس‌وجو از کارساز برای انواع نشانه‌های معنایی (نیازمند LSP 3.16)
.IP "\fB--ls-syntax\fR=<\fIlang\fR>"
تنظیم نحوی که برای کارساز قابل درک باشد
.IP "\fB--ls-syntax-error\fR"
دریافت اطلاعات خطای نحو (مستلزم \-\-ls-hover یا \-\-ls-semantic)
.IP "\fB--ls-workspace\fR=<\fIdir\fR>"
تنظیم دایرکتوری فضای کاری برای راه‌اندازی اولیه کارساز
.IP "\fB--ls-legacy\fR"
عدم نیاز به پاسخ قابلیت‌های کارساز

.SH "محیط (ENVIRONMENT)"
برنامه Highlight این متغیرها را شناسایی می‌کند:
.IP "\fIHIGHLIGHT_DATADIR\fR"
مسیر اسکریپت‌های پیکربندی highlight را تنظیم می‌کند
.IP "\fIHIGHLIGHT_OPTIONS\fR"
می‌تواند شامل گزینه‌های خط فرمان باشد، اما نباید شامل مسیر فایل‌های ورودی باشد.

.SH "نکات (HINTS)"
اگر هیچ فایل ورودی یا خروجی مشخص نشود، stdin و stdout برای ورودی یا خروجی استفاده خواهند شد.
همچنین خواندن از stdin می‌تواند با گزینه \(aq\-\(aq فعال شود.

قالب خروجی پیش‌فرض: xterm256 یا در صورت مناسب بودن truecolor، در غیر این صورت HTML.

در صورتی که هیچ‌یک از گزینه‌های \-c یا \-I داده نشود، تعاریف شیوه در highlight.css (برای HTML، XHTML، SVG) یا highlight.sty (برای LaTeX، TeX) ذخیره می‌شوند. برای CSS، با گزینه \-I تعاریف در سربرگ سند خروجی ذخیره می‌شوند؛ چنانچه \-f نیز مشخص شده باشد، هیچ تعریف شیوه‌ای وجود نخواهد داشت.

قالب‌بندی مجدد کد (\-F) تنها با فایل‌های ورودی C،‏ C++،‏ C# و Java کار خواهد کرد.

ویژگی‌های LSP به مسیرهای ورودی مطلق نیاز دارند و قالب‌بندی مجدد (\-F) را غیرفعال می‌کنند.

.SH "گزارش باگ‌ها (BUGS)"
شکستن خطوط با \-V یا \-W باعث برجسته‌سازی نادرست توضیحات طولانی تک‌خطی و دستورهای پیش‌پردازنده خواهد شد.
استفاده از line-range ممکن است با عناصر نحوی چندخطی تداخل ایجاد کند. با احتیاط استفاده شود.
.SH "فایل‌ها (FILES)"
فایل‌های پیکربندی در \fI/usr/share/highlight/\fR ذخیره شده‌اند.
تعاریف زبان، پوسته‌ها و افزونه‌ها در زیردایرکتوری‌ها قرار دارند.
.PP
فایل‌های مستندات در \fI/usr/share/doc/highlight/\fR و فایل‌های پیکربندی در \fI/etc/highlight/\fR ذخیره شده‌اند.
.PP
برای چگونگی نصب اسکریپت‌های اختصاصی در دایرکتوری خانگی (home)، فایل README را ببینید.
.SH "مثال‌ها (EXAMPLES)"
تبدیل یک فایل تکی:
.PP
highlight -o hello.html -i hello.c
.PP
highlight -o hello.html hello.c
.PP
highlight -o hello.html -S c < hello.c
.PP
highlight -S c < hello.c > hello.html
.PP
توجه داشته باشید که فایلی با نام highlight.css در دایرکتوری جاری ایجاد می‌شود.
.PP
پردازش دسته‌ای فایل‌ها:

highlight --out-format=xhtml  -B '*.cpp' -d /home/you/html_code/
.PP
تمام فایل‌های ‎*.cpp در دایرکتوری جاری و دایرکتوری‌های فرعی آن را به فایل‌های xhtml تبدیل کرده و خروجی را در ‎/home/you/html_code ذخیره می‌کند.
.PP
highlight --out-format=latex  * -d /home/you/latex_code/
.PP
تمام فایل‌ها را به LaTeX تبدیل کرده و در ‎/home/you/latex_code/ ذخیره می‌کند.
.PP
برای بهبود کارایی پردازش دسته‌ای فایل‌ها از \-\-quiet استفاده کنید (برای استفاده در اسکریپت‌های شل توصیه می‌شود).
.PP
از دستور highlight \-\-out\-format=xterm256 <yourfile> | less \-R برای نمایش یک فایل منبع در ترمینال استفاده کنید.
.PP
برای مشاهده تمامی انواع نحوهای پشتیبانی‌شده، دستور highlight \-\-list\-scripts=langs را اجرا کنید.

.SH "نویسندگان (AUTHORS)"
Andre Simon <as@andre-simon.de>
.SH "همچنین ببینید (SEE ALSO)"
فایل‌های README و <http://www.andre-simon.de>.