.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PERLTEX 1"
.TH PERLTEX 1 2024-12-03 v2.3 " "
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
perltex \- امکان تعریف ماکروهای LaTeX با استفاده از کدهای Perl
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
perltex
[\fB\-\-help\fR]
[\fB\-\-latex\fR=\fIprogram\fR]
[\fB\-\-\fR[\fBno\fR]\fBsafe\fR]
[\fB\-\-permit\fR=\fIfeature\fR]
[\fB\-\-makesty\fR]
[\fIlatex options\fR]
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
سامانه LaTeX \-\- از طریق سامانه حروف‌چینی زیربنایی TeX \-\- اسنادی با حروف‌چینی بسیار زیبا تولید می‌کند، اما دارای زبان ماکرویی است که برنامه‌نویسی با آن دشوار است. به‌ویژه، پشتیبانی از دستکاری‌های پیچیده رشته‌ها تا حد زیادی در آن وجود ندارد. از سوی دیگر، Perl یک زبان برنامه‌نویسی همه‌منظوره و محبوب است که نقطه قوت اصلی آن دستکاری رشته‌هاست. با این حال، به هیچ وجه از قابلیت‌های حروف‌چینی برخوردار نیست.
.PP
بدیهی است که قابلیت برنامه‌نویسی Perl می‌تواند مکمل نقاط قوت حروف‌چینی LaTeX باشد. \fBperltex\fR ابزاری است که همزیستی میان این دو سامانه را ممکن می‌سازد. تمام کاری که کاربر باید انجام دهد، کامپایل کردن سند LaTeX با استفاده از \fBperltex\fR به جای \fBlatex\fR است. (\fBperltex\fR در واقع یک پوشش (wrapper) برای \fBlatex\fR است، بنابراین هیچ‌کدام از قابلیت‌های \fBlatex\fR از دست نمی‌رود.) اگر سند در دیباچه (preamble) خود شامل دستور \f(CW\*(C`\eusepackage{perltex}\*(C'\fR باشد، آنگاه ماکروهای \&\f(CW\*(C`\eperlnewcommand\*(C'\fR و \f(CW\*(C`\eperlrenewcommand\*(C'\fR در دسترس قرار خواهند گرفت. رفتار این ماکروها دقیقاً مانند \f(CW\*(C`\enewcommand\*(C'\fR و \&\f(CW\*(C`\erenewcommand\*(C'\fR در LaTeX است، با این تفاوت که بدنه ماکرو به جای کد LaTeX، شامل کد Perl است.
.SH "گزینه‌ها (OPTIONS)"
.IX Header "OPTIONS"
\&\fBperltex\fR گزینه‌های خط فرمان زیر را می‌پذیرد:
.IP \fB\-\-help\fR 4
.IX Item "--help"
نمایش اطلاعات پایه درباره نحوه استفاده.
.IP \fB\-\-latex\fR=\fIprogram\fR 4
.IX Item "--latex=program"
مشخص کردن یک برنامه برای استفاده به جای \fBlatex\fR. برای مثال،
\&\f(CW\*(C`\-\-latex=pdflatex\*(C'\fR سند داده‌شده را با استفاده از
\&\fBpdflatex\fR به جای \fBlatex\fR معمولی حروف‌چینی می‌کند.
.IP \fB\-\-\fR[\fBno\fR]\fBsafe\fR 4
.IX Item "--[no]safe"
فعال یا غیرفعال کردن محیط ایزوله (sandboxing). در حالت پیش‌فرض \fB\-\-safe\fR،
\&\fBperltex\fR کد ناشی از یک ماکروی \f(CW\*(C`\eperlnewcommand\*(C'\fR یا
\&\f(CW\*(C`\eperlrenewcommand\*(C'\fR را درون یک محیط محافظت‌شده اجرا می‌کند که از
عملیات «ناامن» مانند دسترسی به فایل‌ها یا اجرای برنامه‌های خارجی جلوگیری
می‌نماید. مشخص کردن \fB\-\-nosafe\fR به سند LaTeX \&\fIاختیار تام (carte blanche)\fR می‌دهد تا
هر کد دلخواه Perl را اجرا کند، از جمله کدهایی که می‌توانند به فایل‌های
کاربر آسیب برسانند. برای اطلاعات بیشتر Safe را ببینید.
.IP \fB\-\-permit\fR=\fIfeature\fR 4
.IX Item "--permit=feature"
اجازه دادن به انجام عملیات‌های خاص در Perl. گزینه \fB\-\-permit\fR
که می‌تواند بیش از یک بار در خط فرمان مشخص شود، امکان کنترل دقیق‌تر
روی محیط ایزوله \fBperltex\fR را فراهم می‌سازد. برای اطلاعات بیشتر
Opcode را ببینید.
.IP \fB\-\-makesty\fR 4
.IX Item "--makesty"
تولید یک فایل استایل LaTeX به نام \fInoperltex.sty\fR. جایگزین کردن
خط \f(CW\*(C`\eusepackage{perltex}\*(C'\fR در سند با \f(CW\*(C`\eusepackage{noperltex}\*(C'\fR
همان خروجی را تولید می‌کند، اما به PerlTeX نیازی ندارد؛ این امر
سند را برای توزیع میان افرادی که PerlTeX را نصب ندارند مناسب می‌سازد.
عیب این روش این است که فایل \fInoperltex.sty\fR مختص همان سندی است که آن را تولید کرده
است. هرگونه تغییر در تعاریف ماکروهای PerlTeX یا فراخوانی‌های ماکرو در سند،
مستلزم اجرای مجدد \&\fBperltex\fR با گزینه \fB\-\-makesty\fR خواهد بود.
.PP
سپس به دنبال این گزینه‌ها، هر گزینه‌ای که به طور معمول به \fBlatex\fR (یا هر
برنامه‌ای که با \&\f(CW\*(C`\-\-latex\*(C'\fR مشخص شده است) ارسال می‌شود، قرار می‌گیرد؛ از جمله،
برای نمونه، نام فایل \fI.tex\fR برای کامپایل.
.SH "مثال‌ها (EXAMPLES)"
.IX Header "EXAMPLES"
در ساده‌ترین حالت، \fBperltex\fR درست مانند \fBlatex\fR اجرا می‌شود:
.PP
.Vb 1
\&    perltex myfile.tex
.Ve
.PP
برای استفاده از \fBpdflatex\fR به جای \fBlatex\fR معمولی، از گزینه \fB\-\-latex\fR
استفاده کنید:
.PP
.Vb 1
\&    perltex \-\-latex=pdflatex myfile.tex
.Ve
.PP
اگر LaTeX خطای «\f(CW\*(C`trapped by operation mask\*(C'\fR» را نشان داد و شما به
فایل \fI.tex\fR که قصد کامپایل آن را دارید اطمینان دارید که کد مخرب
Perl را اجرا نمی‌کند (مثلاً به این دلیل که خودتان آن را نوشته‌اید)، می‌توانید
سازوکارهای امنیتی \&\fBperltex\fR را با گزینه \fB\-\-nosafe\fR غیرفعال کنید:
.PP
.Vb 1
\&    perltex \-\-nosafe myfile.tex
.Ve
.PP
دستور زیر به اسناد تنها مجوزهای پیش‌فرض \fBperltex\fR (\f(CW\*(C`:browse\*(C'\fR) را
به همراه قابلیت باز کردن فایل‌ها و فراخوانی دستور \&\f(CW\*(C`time\*(C'\fR اعطا می‌کند:
.PP
.Vb 2
\&    perltex \-\-permit=:browse \-\-permit=:filesys_open
\&      \-\-permit=time myfile.tex
.Ve
.SH "محیط (ENVIRONMENT)"
.IX Header "ENVIRONMENT"
\&\fBperltex\fR از متغیرهای محیطی زیر پیروی می‌کند:
.IP PERLTEX 4
.IX Item "PERLTEX"
نام فایل کامپایلر LaTeX را مشخص می‌کند. کامپایلر LaTeX
به طور پیش‌فرض «\f(CW\*(C`latex\*(C'\fR» است. متغیر محیطی \f(CW\*(C`PERLTEX\*(C'\fR
این پیش‌فرض را بازنویسی می‌کند، و گزینه خط فرمان \fB\-\-latex\fR (بخش
«گزینه‌ها (OPTIONS)» را ببینید) آن را نیز لغو و بازنویسی می‌نماید.
.SH "فایل‌ها (FILES)"
.IX Header "FILES"
هنگام کامپایل \fIjobname.tex\fR، \fBperltex\fR از فایل‌های زیر استفاده می‌کند:
.IP \fIjobname.lgpl\fR 4
.IX Item "jobname.lgpl"
فایل گزارش (log) نوشته‌شده توسط Perl؛ مفید برای اشکال‌زدایی ماکروهای Perl
.IP \fIjobname.topl\fR 4
.IX Item "jobname.topl"
اطلاعات ارسال‌شده از LaTeX به Perl
.IP \fIjobname.frpl\fR 4
.IX Item "jobname.frpl"
اطلاعات ارسال‌شده از Perl به LaTeX
.IP \fIjobname.tfpl\fR 4
.IX Item "jobname.tfpl"
فایل «نشانگر» (flag) که وجود آن نشان می‌دهد \fIjobname.topl\fR حاوی داده‌های معتبر است
.IP \fIjobname.ffpl\fR 4
.IX Item "jobname.ffpl"
فایل «نشانگر» (flag) که وجود آن نشان می‌دهد \fIjobname.frpl\fR حاوی داده‌های معتبر است
.IP \fIjobname.dfpl\fR 4
.IX Item "jobname.dfpl"
فایل «نشانگر» (flag) که وجود آن نشان می‌دهد \fIjobname.ffpl\fR حذف شده است
.IP \fInoperltex\-#.tex\fR 4
.IX Item "noperltex-#.tex"
فایل تولیدشده توسط \fInoperltex.sty\fR برای هر فراخوانی ماکروی PerlTeX
.SH "نکات (NOTES)"
.IX Header "NOTES"
محیط ایزوله (sandbox) \&\fBperltex\fR به طور پیش‌فرض روی چیزی تنظیم شده است که Opcode آن را «\f(CW\*(C`:browse\*(C'\fR» می‌نامد.
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
\&\fBlatex\fR\|(1), \fBpdflatex\fR\|(1), \fBperl\fR\|(1), \fBSafe\fR\|(3pm), \fBOpcode\fR\|(3pm)
.SH "نویسنده (AUTHOR)"
.IX Header "AUTHOR"
Scott Pakin, \fIscott+pt@pakin.org\fR