% !TeX program = lualatex
\documentclass{article}

\usepackage{booktabs,tabularx}
\usepackage{graphicx}
\usepackage{needspace}
\usepackage{docref}
\directlua{dofile(kpse.find_file("build-doc.lua"))}
\usepackage{listings}
\usepackage[section]{minted}
\usepackage[svgnames]{xcolor}

\setminted{
    escapeinside=||,
    breaklines=true,
    % breakanywhere=true,
    fontsize=\small
}

\setminted[latex]{bgcolor=Gold, bgcolorpadding=0.5em}
\setminted[bash]{bgcolor=Gainsboro}
\setminted[text]{bgcolor=Ivory}


\usepackage{hyperref}
\hypersetup{
colorlinks=true,
linkcolor=blue,
urlcolor=blue
}
\pdfstringdefDisableCommands{%
\def\XeTeX{XeTeX}%
\def\PdfTeX{pdfTeX}%
\def\LuaTeX{LuaTeX}%
\def\code#1{#1}%
\def\lr#1{#1}%
}
\usepackage%[fontcache=false]
{unipersian}
\settextfont{HM XNiloofar}
\setlatintextfont{Times New Roman}
\setlatinmonofont{JetBrains Mono}
\setpersianmonofont[BoldFont={Vazir Code},ItalicFont={Vazir Code}]{Vazir Code}

\newcommand{\code}[1]{\lr{\texttt{\small #1}}}


% Keep page numbers Persian and in numeric order, even during code output.
\makeatletter
\renewcommand{\ps@plain}{%
\let\@mkboth\@gobbletwo
\let\@oddhead\@empty
\let\@evenhead\@empty
\def\@oddfoot{\hfil
    \foreignlanguage{persian}{\LR{\number\value{page}}}\hfil}%
\let\@evenfoot\@oddfoot
}
\makeatother
\pagestyle{plain}

\title{بسته \code{UniPersian}}
\author{عامر آمیخته}

\usepackage{pkgmeta}
\NewDocumentCommand{\manualref}{m m}{%
    \docref{#1}{#2}\footnote{%
        \code{#1}، نسخهٔ \lr{\pkgmeta[version]{#1}}؛
        صفحهٔ \docpageref*{#1}{#2}؛
        «\lr{\docnameref*{#1}{#2}}».}%
}
\date{%
\localedate[calendar=persian,convert]
{\pkgmeta[year]{unipersian}}
{\pkgmeta[month]{unipersian}}
{\pkgmeta[day]{unipersian}}\\[2pt]
نسخهٔ \lr{\pkgmeta[version]{unipersian}}
}

\def\XeTeX{%
\leavevmode
\hbox{%
    X%
    \lower.5ex\hbox{%
        \kern-.125em
        \scalebox{-1}[1]{E}%
    }%
    \kern-.0900em
    \TeX
}%
}

\def\PdfTeX{%
\leavevmode
\hbox{%
    P%
    \kern-.18em
    \raise-.42ex\hbox{\scriptsize Df}%
    \kern-.08em
    \TeX
}%
}

\def\LuaTeX{%
\leavevmode
\hbox{%
    L%
    \kern-.16em
    \raise.28ex\hbox{\scriptsize Ua}%
    \kern-.16em
    \TeX
}%
}

\begin{document}
\emergencystretch=3em
\maketitle

\begin{abstract}
\code{UniPersian}
 بسته‌ای برای حروف‌چینی زبان فارسی در \LaTeX{} است که از
 \code{BabelBidi} (مبتنی بر \code{Babel}) بهره می‌گیرد.
    فارسی
    می‌تواند زبان اصلی یا دوم سند باشد. بسته تنظیم قلم‌های فارسی و
    لاتین، عنوان‌های فارسی و شیوه‌های شماره‌گذاری را فراهم می‌کند.
    \LuaTeX{} موتور توصیه‌شده است؛ \XeTeX{} نیز پشتیبانی می‌شود و
    پشتیبانی از \PdfTeX{} به امکانات پایه محدود است. 
این راهنما بسته را معرفی می‌کند و کار با آن را توضیح می‌دهد؛
برای کاربردهای معمول، آشنایی قبلی با
\code{BabelBidi}
و
\code{Babel}
 لازم نیست.

\end{abstract}


\tableofcontents

\section{مقدمه}

هدف \code{UniPersian}، فراهم‌کردن حروف‌چینی فارسی با تمرکز بر
\LuaTeX{} و زیرساخت چندزبانهٔ \code{Babel} است. رابط‌های پرکاربرد
تا حد امکان برای کاربران \code{xepersian} آشنا هستند؛ بااین‌حال،
سازگاری کامل همهٔ دستورها و یکسانی شکست سطر و صفحه تضمین نمی‌شود.

\code{Babel} مدیریت زبان و قلم را بر عهده دارد و \code{BabelBidi}
فرمان‌های جهت و اصلاح چیدمان دوجهته را فراهم می‌کند. هر دو با
\code{UniPersian} خودکار بارگذاری می‌شوند. برای سند معمول فارسی،
تنظیم جداگانهٔ آن‌ها لازم نیست؛ امکانات پیشرفته در راهنماهای اصلی
این بسته‌ها توضیح داده شده‌اند.

\section{دریافت و نصب}

نسخهٔ رسمی بسته از آرشیو \code{CTAN} در دسترس است:
\begin{center}
    \url{https://ctan.org/pkg/unipersian}
\end{center}

در ویندوز، لینوکس و مک، روش نصب به توزیع \TeX{} بستگی دارد.
در نصب مستقیم \TeX{} Live، از جمله \code{MacTeX} در مک، بنویسید:
\begin{minted}{bash}
    tlmgr install unipersian BabelBidi
\end{minted}
در \code{MiKTeX}، دو بسته را از بخش \code{Packages} در
\code{MiKTeX Console} نصب کنید. برای \TeX{} Live نصب‌شده از
مخازن لینوکس، از مدیر بستهٔ همان توزیع استفاده کنید. در نصب دستی،
فایل‌های دو بسته باید در مسیر جست‌وجوی \TeX{} باشند؛ نسخه‌های
توسعهٔ آن‌ها را نیز متناسب با یکدیگر نصب کنید.

\section{موتورهای پشتیبانی‌شده}

\begin{center}
    \begin{tabular}{@{}crr@{}}
        \toprule
        موتور & فرمان اجرا & وضعیت \\
        \midrule
        \LuaTeX & \code{lualatex} & موتور اصلی و توصیه‌شده \\
        \XeTeX & \code{xelatex} &پشتیبانی می‌شود \\
        \PdfTeX & \code{pdflatex} &  پشتیبانی پایه‌ای \\
        \bottomrule
    \end{tabular}
\end{center}

موتور خودکار تشخیص داده می‌شود. خود این راهنما تنها با
\LuaTeX
قابل اجرا است. امکانات اختصاصی هر موتور در بخش
مربوط مشخص شده‌اند. تشخیص خودکار زبان و قلم پشتیبان مخصوص
\LuaTeX{} است. دستورهای قلم در \XeTeX{} هم کار می‌کنند، اما در
\PdfTeX{} قابل استفاده نیستند.


\section{بارگذاری بسته}
\label{sec:start}

در
 \LuaTeX،
 لازم نیست unipersian آخرین بستهٔ بارگذاری‌شده باشد. در
 \XeTeX
بهتر است آن را پس از سایر بسته‌ها، به‌ویژه hyperref، بارگذاری کنید؛
\begingroup
\VerbatimFootnotes
\footnote{سند
زیر به دلیل استفاده از بستهٔ 
\code{bidi}
در
\XeTeX
خطا می‌دهد:
\vspace{-0.5\baselineskip}
\begin{minted}{latex}
    \documentclass{article}
    \usepackage{unipersian}
    \usepackage{hyperref}
    
    \begin{document}
        A\footnote{text}
    \end{document}
\end{minted}
\vspace{-\baselineskip}
اگر به جای
\verb|unipersian|
از
\verb|bidi|
هم استفاده کنید، خطا همان خواهد بود.
}
\endgroup
ترتیب‌های اختصاصی توصیه‌شده برای بسته‌های دیگر نیز باید رعایت شوند.

\subsection{فارسی به‌عنوان زبان اول}

در حالت پیش‌فرض، فارسی زبان اصلی و انگلیسی زبان دوم سند است. نمونهٔ زیر
یک سند کامل است:

\begin{minted}[chardir={.r}]{latex}
    \documentclass{article}
    \usepackage{unipersian}
    
    \begin{document}
        سلام دنیا! این یک سند لاتک است.
    \end{document}
\end{minted}

تنظیم قلم‌ها در قسمت~\ref{sec:fonts} توضیح داده شده است.

\subsection{فارسی به‌عنوان زبان دوم}
\label{sec:second-language}

برای سندی که زبان اصلی آن انگلیسی یا هر زبان دلخواه از زبان‌های بسته‌ی 
\code{Babel}
 باشد، زبان اصلی را با یکی از دو روش
زیر تعیین کنید.

روش کلاسیک، با گزینهٔ \code{main} هنگام بارگذاری بسته:

\begin{minted}{latex}
    \usepackage[main=english]{unipersian}
\end{minted}

روش مدرن، با دستور \code{Babel} پس از بارگذاری بسته:

\begin{minted}{latex}
    \usepackage{unipersian}
    \babelprovide[main]{english}
\end{minted}

تنظیم قلم و نوشتن عبارت‌ها و پاراگراف‌های فارسی در قسمت‌های
\ref{sec:fonts} و~\ref{sec:language} آمده است.


\subsection{گزینه‌ها}
\label{sec:options}

گزینه‌های اختصاصی این بسته \code{persianprovide}،
\code{englishprovide} و \code{encodings} هستند. سایر گزینه‌ها به
بسته‌های \code{BabelBidi} و \code{Babel} منتقل می‌شوند. برای آگاهی از
کاربرد آن‌ها، قسمت~\manualref{babelbidi}{loading} راهنمای \code{BabelBidi}
و قسمت~\manualref{babel}{options} راهنمای \code{Babel} را ببینید.

گزینه‌های \code{persianprovide} و \code{englishprovide} به‌ترتیب
تنظیمات زبان فارسی و انگلیسی را هنگام معرفی آن‌ها به \code{Babel}
تعیین می‌کنند. این تنظیمات از گزینه‌های مجاز دستور
\verb|\babelprovide|
انتخاب می‌شوند؛ شرح آن‌ها در قسمت~\manualref{babel}{provide}
راهنمای \code{Babel} آمده است.

پیش‌فرض این گزینه‌ها در \LuaTeX{} به‌ترتیب
\code{mapdigits,onchar=ids fonts letters}
و
\code{onchar=ids fonts letters}
است و در \XeTeX{} خالی است. مقدار صریح هر گزینه جایگزین تمام
پیش‌فرض‌های همان زبان می‌شود. برای نمونه،
\code{persianprovide={mapdigits}}
فقط نگاشت رقم‌ها را فعال می‌کند و تنظیمات خودکار زبان و قلم را حفظ
نمی‌کند.

برای حذف تنظیمات پیش‌فرض انگلیسی می‌توان نوشت:

\begin{minted}{latex}
    \usepackage[englishprovide={}]{unipersian}
\end{minted}

گزینهٔ \code{encodings} برای افزودن کدگذاری‌های قلم در \PdfTeX{} به
کار می‌رود. این گزینه کدگذاری‌های مشخص‌شده را به فهرست کدگذاری‌های
بارگذاری‌شده به‌وسیلهٔ \code{fontenc} می‌افزاید. کدگذاری‌های
\code{LAE}، \code{LFE} و \code{T1} در هر صورت بارگذاری می‌شوند.

برای نمونه، برای افزودن کدگذاری \code{LGR}، که برای حروف یونانی به کار
می‌رود، می‌توان نوشت:

\begin{minted}{latex}
    \usepackage[encodings={LGR}]{unipersian}
\end{minted}

این گزینه در \LuaTeX{} و \XeTeX{} اثری ندارد.



\section{تنظیم قلم‌ها}
\label{sec:fonts}

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

دستورهای زیر در \LuaTeX{} و \XeTeX{} یک آرگومان اختیاری برای
ویژگی‌های قلم و یک آرگومان اجباری برای نام قلم می‌پذیرند:
\begin{center}
    \begin{tabularx}{\linewidth}{@{}lX@{}}
        \toprule
        دستور & کاربرد \\
        \midrule
        \latinverb|\settextfont[...]{...}| & قلم زبان اصلی \\
        \latinverb|\setpersiantextfont[...]{...}| & قلم فارسی، مستقل از زبان اصلی \\
        \latinverb|\setlatintextfont[...]{...}| & قلم زبان لاتین؛ معمولاً انگلیسی \\
        \bottomrule
    \end{tabularx}
\end{center}

هر دستور هر سه خانوادهٔ معمولی، بدون‌سریف و تک‌عرض زبان مربوط را
تنظیم می‌کند. برای قلم‌های جداگانهٔ خانواده‌ها، پس از آن بنویسید:
\begin{minted}{latex}
    \setpersiansansfont{Vazirmatn}
    \setlatinsansfont{Latin Modern Sans}
    \setpersianmonofont{Vazir Code}
    \setlatinmonofont{Latin Modern Mono}
\end{minted}

خانواده‌های بدون‌سریف و تک‌عرض با \verb|\sffamily| و
\verb|\ttfamily| یا \verb|\textsf| و \verb|\texttt| انتخاب
می‌شوند. ویژگی‌های قلم به \verb|\babelfont| در \code{Babel}
منتقل می‌شوند (قسمت~\manualref{babel}{fonts} راهنمای \code{Babel})؛
مثلاً اگر قلم ایتالیک جداگانه ندارد:
\begin{minted}{latex}
    \settextfont[ItalicFont={Vazirmatn}]{Vazirmatn}
\end{minted}

در نبود تعیین صریح، بسته قلم فارسی را از میان \code{HM XNiloofar}،
\code{Vazirmatn}، \code{Amiri}، \code{FreeSerif} و
\code{Tahoma} به همین ترتیب جست‌وجو می‌کند. اگر هیچ‌کدام موجود
نباشد، باید قلم را خودتان تعیین کنید.

برای استفادهٔ موضعی از قلم، دستور دلخواه تعریف کنید و کاربرد آن را
در یک گروه محدود کنید:
\begin{minted}{latex}
    \defpersianfont\headingfont{Vazirmatn}
    \deflatinfont\quotefont[Scale=0.95]{Latin Modern Roman}
\end{minted}

\begin{minted}{latex}
    {\headingfont عنوان فارسی}
    {\quotefont An English quotation}
\end{minted}

\section{تشخیص خودکار و قلم پشتیبان}
\label{sec:auto-font}

در \LuaTeX، فارسی و انگلیسی به‌طور پیش‌فرض با تنظیم \code{onchar}
تشخیص داده می‌شوند و زبان و قلم مناسب انتخاب می‌شود
(قسمت~\manualref{babel}{provide} راهنمای \code{Babel}). متن معمول
آمیخته را مستقیماً بنویسید؛ تعیین زبان برای هر واژه لازم نیست.
کنترل نشانه‌های مشترک و جهت پاراگراف در قسمت~\ref{sec:language} آمده است.

اگر قلم فعلی نویسه‌ای نداشته باشد، قلم پشتیبان در زبان دیگر جست‌وجو
می‌شود. رابطهٔ دوطرفهٔ انگلیسی و فارسی از پیش فعال است؛ خانواده،
اندازه، ضخامت و شکل قلم حفظ می‌شوند و زبان و جهت متن عوض نمی‌شوند.
برای تغییر رابطه یا غیرفعال‌کردن آن از فهرست خالی استفاده کنید:
\begin{minted}{latex}
    \fontfallback{english}{persian}
    \fontfallback{english}{}
\end{minted}

دستور دوم جایگزین اول می‌شود. این قابلیت شامل قلم ریاضی نیست و در
\XeTeX{} و \PdfTeX{} کاربرد ندارد؛ جزئیات در راهنمای
\code{BabelBidi}، قسمت~\manualref{babelbidi}{fallback} آمده است.

\section{مدیریت زبان و جهت نوشتار}
\label{sec:language}

در \LuaTeX{} زبان و جهت عبارت‌های ساده از روی نویسه‌ها تشخیص
داده می‌شود:
\begin{minted}[textlang=persian]{latex}
    این متن با LaTeX نوشته شده است.
\end{minted}

اگر نشانه‌های مشترک، مانند پرانتز، درست جای نگرفتند، محدودهٔ
عبارت را صریح تعیین کنید. \verb|\lr| زبان چپ‌به‌راست،
معمولاً انگلیسی، و
 \verb|\rl| زبان راست‌به‌چپ، معمولاً فارسی،
را انتخاب می‌کند:
\begin{minted}[textdir=rtl,chardir={{\\}{l},{\}}{l}}]{latex}
    این روش در \lr{Chapter 2 (Examples)} توضیح داده شده است.
\end{minted}

نشانه‌های متعلق به عبارت را در همان آرگومان قرار دهید.
در \XeTeX{} و \PdfTeX، که این تشخیص خودکار را ندارند،
برای عبارت‌های ساده نیز از همین دستورها استفاده کنید.

تشخیص خودکار نویسه‌ها جهت پاراگراف و عنوان‌های ثابت را تغییر
نمی‌دهد. برای پاراگراف‌های مستقل انگلیسی از محیط \code{latin}
و برای پاراگراف مستقل فارسی از محیط \code{persian} استفاده کنید.
با پایان محیط، زبان قبلی بازمی‌گردد:
\begin{minted}{latex}
    \begin{latin}
        This is an English paragraph.
    \end{latin}
\end{minted}

نام زبان فارسی در \code{Babel} برای \LuaTeX{} و \XeTeX{}،
\code{persian}، و برای \PdfTeX{}، \code{farsi} است. محیط
\code{persian} این تفاوت را مدیریت می‌کند.

برای افزودن زبان‌های دیگر، پس از بارگذاری بسته از دستور
\verb|\babelprovide| استفاده کنید؛ مثلاً
\verb|\babelprovide[import]{greek}| زبان یونانی را معرفی می‌کند.

رابط‌های عمومی \code{Babel} نیز در دسترس‌اند؛ برای انتخاب زبان،
قسمت‌های~\manualref{babel}{selectors} و~\manualref{babel}{aux-selectors}
راهنمای آن را ببینید.


رابط‌های تغییر جهت بدون تغییر زبان، مانند \verb|\LR| و محیط
\code{RTL}، در قسمت‌های~\manualref{babelbidi}{commands}
و~\manualref{babelbidi}{environments} راهنمای \code{BabelBidi} آمده‌اند.
شیوهٔ انتخاب زبان برای \verb|\lr|، \verb|\rl| و محیط \code{latin}
در قسمت~\manualref{babelbidi}{languages} همان راهنما توضیح داده شده است.
\section{اعداد، شماره‌گذاری و تاریخ}
\label{sec:numerals}

در \LuaTeX، گزینهٔ پیش‌فرض \code{mapdigits} رقم‌های لاتین متن را
در محدودهٔ فارسی به شکل فارسی نمایش می‌دهد. در \XeTeX، دستورهای
قلم فارسی نگاشت \code{farsidigits} را به کار می‌گیرند. برای حفظ
رقم لاتین در شناسه، زبان آن را صریح انتخاب کنید:
\begin{minted}[chardir={{.}{r},{\}}{l}},textdir=rtl]{latex}
    تعداد نمونه‌ها 123 است؛ شناسهٔ آن‌ها \lr{A-123} است.
\end{minted}


\begin{sloppypar}
این نگاشت فقط نمایش رقم‌ها را تغییر می‌دهد؛ در آرگومان‌های عددی دستورها،
مانند \code{\textbackslash setcounter\{section\}\{3\}}، از رقم لاتین استفاده کنید.
\end{sloppypar}

دستورهای عدد به حروف دو گونه‌اند: یکی نام شمارنده و دیگری مقدار
مستقیم را می‌گیرد:

\begin{center}
    \begin{tabularx}{\linewidth}{@{}llX@{}}
        \toprule
        نام شمارنده & مقدار مستقیم & نمایش \\
        \midrule
        \latinverb|\harfi{section}| & \latinverb|\harfinumeral{3}| & الفبای فارسی: \harfinumeral{3} \\
        \latinverb|\adadi{section}| & \latinverb|\adadinumeral{11}| & عدد به حروف: \adadinumeral{11} \\
        \latinverb|\tartibi{section}| & \latinverb|\tartibinumeral{4}| & ترتیبی: \tartibinumeral{4} \\
        \latinverb|\Abjad{section}| & \latinverb|\Abjadnumeral{7}| & ترتیب ابجد: \Abjadnumeral{7} \\
        \latinverb|\abjad{section}|
        & 
        \latinverb|\abjadnumeral{12}| & 
        مقدار ابجد: \abjadnumeral{12} \\
        \bottomrule
    \end{tabularx}
\end{center}


\verb|\harfi| مقادیر ۱ تا ۳۲، \verb|\Abjad| مقادیر ۱ تا ۲۸
و \verb|\abjad| مقدارها را تا ۱۹۹۹ می‌پذیرند. \verb|\adadi|
و \verb|\tartibi| برای اعداد صحیح نامنفی تا ۹۹۹٬۹۹۹٬۹۹۹ هستند؛
خروجی صفر، «صفر» و «صفرم» است.

برای شمارهٔ قسمت و صفحه، مثلاً بنویسید:
\begin{minted}{latex}
    \renewcommand{\thesection}{\harfi{section}}
    \pagenumbering{harfi}
\end{minted}
\begin{sloppypar}
\verb|\pagenumbering| شمارهٔ صفحه را از نو آغاز می‌کند؛ برای شماره‌گذاری
عددی، آرگومان آن را \code{arabic} قرار دهید. \verb|\alph| و
\verb|\Alph| در فارسی حروف ابجد و در انگلیسی حروف لاتین می‌دهند.
\end{sloppypar}

فهرست‌ها با \code{itemize} و \code{enumerate} ساخته می‌شوند.
با بارگذاری \code{enumitem} پیش از \code{unipersian} می‌توان
شمارهٔ فهرست را نیز ترتیبی کرد:
\begin{minted}{latex}
    \begin{enumerate}[label=\tartibi*.]
        \item نخستین مورد
        \item دومین مورد
    \end{enumerate}
\end{minted}

\verb|\today| تاریخ روز را با تنظیمات زبان فعال و
\verb|\latintoday| آن را در زبان لاتینِ انتخاب‌شده نمایش می‌دهد.
برای تاریخ ثابت، تبدیل تقویم و قالب‌بندی بیشتر، امکانات تاریخ
\code{Babel}
 در قسمت
 \manualref{babel}{dates} 
راهنمای آن، یا بستهٔ
\code{datemultical} را ببینید.

    \section{فارسی‌سازی عناوین و اصطلاحات}
بستهٔ \code{UniPersian}، همانند بستهٔ \code{xepersian}،
ترجمهٔ فارسی عناوین استاندارد \LaTeX و اصطلاحات برخی بسته‌ها و کلاس‌های
پرکاربرد را فراهم می‌کند. این ترجمه‌ها شامل عنوان‌هایی مانند «فهرست
مطالب»، «شکل»، «جدول»، «منابع»، «نمایه» و «واژه‌نامه» است.

ترجمه‌های مرتبط با هر بسته یا کلاس، در صورت بارگذاری آن به صورت شرطی
فعال می‌شوند. برای نمونه، بسته‌های \code{algorithm},
\code{hyperref}, \code{listings} و
\code{minitoc}، و همچنین کلاس \code{beamer}، از این
قابلیت پشتیبانی می‌کنند.


    \section{کدنویسی}

بستهٔ \code{UniPersian} نمایش قطعه‌کدها و متن‌های با چیدمان ثابت را
در اسناد فارسی، مستقل از جهت نوشتار متن پیرامون، فراهم می‌کند.

روش پیشنهادی برای نمایش قطعه‌کدها، استفاده از بستهٔ \code{minted}
همراه با \LuaTeX است. در این حالت، متن فارسی و لاتین درون کد و
توضیحات آن به‌صورت طبیعی قابل استفاده است:

\begin{minted}{latex}
    \begin{minte||d}{python}
        # توضیح فارسی
        print("سلام")
    \end{minte||d}
\end{minted}

برای تنظیم زبان و جهت کد با گزینه‌های \code{textlang}،
\code{textdir} و \code{chardir}، قسمت~\manualref{babelbidi}{minted}
راهنمای \code{BabelBidi} را ببینید.

بستهٔ \code{minted} به پیش‌نیازهای خود نیاز دارد. در صورت نبود این
پیش‌نیازها، می‌توان از \code{listings} استفاده کرد. در این صورت بستهٔ
\code{unipersian-listings}
به‌صورت خودکار بارگذاری می‌شود.
با \LuaTeX، جهت و فونت کدها مدیریت می‌شود؛ با این‌حال، \code{listings} در پردازش برخی نویسه‌های
فارسی، از جمله فاصله‌ها، محدودیت‌هایی دارد
و به
\code{escapeinside}
نیاز پیدا می‌کند.

در صورت استفاده از \XeTeX، برای وارد کردن متن فارسی در
\code{lstlisting} نیز باید از \code{escapeinside} و دستور
\verb|\fa| استفاده کرد. در این حالت، \verb|\fa| تنظیمات و
رنگ‌آمیزی \code{listings} را حفظ می‌کند.
\begin{minted}{latex}
    \begin{lstlisting}[language=Python,escapeinside={@}{@}]
        # @\fa{توضیح فارسی}@
        print("@\fa{سلام}@")
    \end{lstlisting}
\end{minted}



اگر به امکانات بسته‌های کدنویسی نیاز ندارید، دستور \verb|\verb| و
محیط \code{verbatim} نیز برای نمایش متن با چیدمان ثابت در اسناد
فارسی سازگار شده‌اند و می‌توان از آن‌ها برای کدهای ساده استفاده کرد.




 \section{ارائه‌های فارسی با \code{beamer}}
 
 بستهٔ \code{UniPersian} با کلاس استاندارد \code{beamer} سازگار
 است. برای ارائه‌های فارسی، استفاده از کلاس \code{beamer-rl}
 همراه با این بسته توصیه می‌شود؛ این کلاس به‌طور ویژه برای
 ارائه‌های راست‌به‌چپ طراحی شده و به \LuaTeX{} نیاز دارد.
 
 \begin{minted}[chardir={!r}]{latex}
     \documentclass{beamer-rl}
     \usepackage{unipersian}
     
     \begin{document}
         \begin{frame}
             سلام دنیا!
         \end{frame}
     \end{document}
 \end{minted}
 
 استفاده از کلاس استاندارد \code{beamer} نیز امکان‌پذیر است.
 اصلاحات چیدمان این کلاس در قسمت~\manualref{babelbidi}{patches}
 راهنمای \code{BabelBidi} آمده است.



    \section{محدودیت‌های فعلی}

نسخه‌ی فعلی هنوز کامل نیست و چند محدودیت شناخته‌شده دارد.

مهم‌ترین موارد عبارت‌اند از:

\begin{enumerate}
    \item همه‌ی قابلیت‌های \code{xepersian} هنوز پیاده‌سازی نشده‌اند.
    \item سازگاری با همهٔ بسته‌های جانبی \LaTeX{} تضمین نشده است.
\end{enumerate}


    \section{گزارش مشکلات}

هنگام گزارش یک مشکل، لطفاً اطلاعات زیر را ارائه کنید:

\begin{enumerate}
    \item موتور \TeX{} و نسخه‌ی آن.
    \item نسخه‌ی \LaTeX{}.
    \item نسخه‌ی بسته‌ی \code{UniPersian}.
    \item یک مثال حداقلی قابل اجرا (MWE).
    \item در صورت امکان، متن کامل خطا.
\end{enumerate}

\Needspace{5\baselineskip}
برای مثال:


\begin{minted}{text}
    Engine: LuaTeX
    LaTeX: TeX Live 2026
    UniPersian: |\pkgmeta[version]{unipersian}|
\end{minted}


برای بررسی یک مشکل، یک مثال کوچک و قابل بازتولید
بسیار مفیدتر از یک سند بزرگ است.



    \section{مجوز}

بسته‌ی \code{UniPersian} تحت مجوز
\lr{LaTeX Project Public License (LPPL)}
نسخه‌ی \lr{1.3c} یا جدیدتر منتشر می‌شود.
متن کامل مجوز در فایل \code{LICENSE} موجود است.


\section{نویسنده و نگهدارنده}

بسته‌ی \code{UniPersian} در حال حاضر توسط
\textbf{عامر آمیخته}
نگهداری و توسعه داده می‌شود.

کد منبع، نسخه‌های توسعه و امکان گزارش مشکلات در مخزن پروژه در دسترس
است:

\hfill \url{https://github.com/gambi-shah/unipersian}

\end{document}