.TH TEXPROF 1 "2 September 2024" "Version 1.0"
.\"=====================================================================
.if n .ds MF Metafont
.if t .ds MF Metafont
.if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
.if n .ds TX TeX
.ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP
.el .ds OX TeX
.\" BX definition must follow TX so BX can use TX
.if t .ds BX \fRB\s-2IB\s0\fP\*(TX
.if n .ds BX BibTeX
.\" LX definition must follow TX so LX can use TX
.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
.if n .ds LX LaTeX
.if t .ds AX \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(TX
.if n .ds AX AmSTeX
.if t .ds AY \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(LX
.if n .ds AY AmSLaTeX
.if n .ds WB Web
.if t .ds WB W\s-2EB\s0
.\"=====================================================================
.SH "نام (NAME)"
texprof \- پروفایلری برای فایل‌های منبع TeX
.SH "خلاصه دستور (SYNOPSIS)"
.B texprof
.RI [ options ]
.RI [ \fB&\fPformat ]
.RI [ file | \fB\e\fPcommands ]
.\"=====================================================================
.SH "توضیحات (DESCRIPTION)"
پروفایلر \*(TX را بر روی
.IR file
اجرا می‌کند، که معمولاً موجب ایجاد
.IR file.dvi
و
.IR file.tprof
می‌گردد. اگر آرگومان
.IR file
فاقد پسوند باشد، «.tex» به انتهای آن افزوده خواهد شد.
به جای نام فایل، می‌توان فهرستی از دستورات \*(TX را ارائه داد که نخستین آن‌ها باید با یک بک‌اسلش آغاز شود.
با یک آرگومان
.BI & format
، پروفایلر \*(TX از مجموعهٔ متفاوتی از دستورات از پیش کامپایل‌شدهٔ موجود در
.IR format\fB.fmt\fP
استفاده می‌کند؛ هرچند معمولاً بهتر است به جای آن از گزینهٔ
.B -fmt
.I format
استفاده شود.
.PP
پروفایلر \*(TX نسخه‌ای از \*(TX است که زمان مورد نیاز \*(TX را برای اجرای هر یک از خطوط ورودی یا ماکروها اندازه می‌گیرد.
این برنامه داده‌های جمع‌آوری‌شده را در فایلی با پسوند
.IR .tprof
می‌نویسد.
برنامهٔ جداگانه‌ای به نام
.B texprofile
(ببینید:
.BR texprofile (1))
برای نمایش محتوای یک فایل
.IR .tprof
به شکلی خوانا استفاده می‌شود.

.PP
کاربرد معمول پروفایلر \*(TX همراه با قالب‌های از پیش تولیدشده است.
دستور
.B texprof
از قالبی معادل با plain \*(TX استفاده می‌کند و دستور
.B latexprof
از قالبی معادل با \*(LX بهره می‌برد. برای بررسی زمان‌بندی ماکروهای مختص
.B pdftex
یا
.BR pdflatex ،
می‌توانید از
.B pdftexprof
یا
.B pdflatexprof
استفاده کنید.

.PP
نحوهٔ مدیریت آرگومان‌های خط فرمان توسط پروفایلر \*(TX مشابه سایر برنامه‌های \*(TX در پیاده‌سازی
.I web2c
است.

.\"=====================================================================.SH "گزینه‌ها (OPTIONS)"
این نسخه از پروفایلر \*(TX گزینه‌های خط فرمان زیر را پشتیبانی می‌کند.
.TP
.BI -cnf-line \ string
تجزیه
.I string
به عنوان یک خط پیکربندی
.IR texmf.cnf .
دفترچه راهنمای Kpathsea را ببینید.
.TP
.B -etex
فعال‌سازی افزونه‌های e-\*(TX. این گزینه فقط در ترکیب با
.B -ini
مؤثر است.
.BR etex (1)
را ببینید.
.TP
.B -file-line-error
چاپ پیام‌های خطا در قالب
.I file:line:error
که مشابه شیوه قالب‌بندی بسیاری از کامپایلرها است.
.TP
.B -no-file-line-error
غیرفعال‌سازی چاپ پیام‌های خطا در قالب
.IR file:line:error .
.TP
.BI -fmt \ format
استفاده از
.I format
به عنوان نام فرمت مورد استفاده، به جای نامی که پروفایلر \*(TX با آن فراخوانی شده یا یک خط
.IR %& .
.TP
.B -help
نمایش پیام راهنما و خروج.
.TP
.B -ini
شروع در حالت
.IR INI ،
که برای ذخیره رونوشت (dump) فرمت‌ها استفاده می‌شود. حالت
.I INI
می‌تواند برای حروف‌چینی استفاده شود، اما هیچ فرمتی از پیش بارگذاری نمی‌شود و ممکن است مقداردهی‌های اولیه اساسی مانند تنظیم catcodeها لازم باشد.
.TP
.BI -interaction \ mode
تنظیم حالت تعاملی. این حالت می‌تواند یکی از مقادیر
.IR batchmode ،
.IR nonstopmode ،
.IR scrollmode
یا
.IR errorstopmode
باشد. معنای این حالت‌ها مشابه دستورات (\ecommands) متناظر آن‌ها است.
.TP
.BI -jobname \ name
استفاده از
.I name
برای نام کار (job name)، به جای استخراج آن از نام فایل ورودی.
.TP
.BI -kpathsea-debug \ bitmask
تنظیم پرچم‌های اشکال‌زدایی جستجوی مسیر با توجه به bitmask. برای جزئیات به دفترچه راهنمای
.I Kpathsea
مراجعه کنید.
.TP
.B -ltx
فعال‌سازی افزونه‌های \*(LX. این گزینه تنها در ترکیب با
.B -ini
مؤثر است.
.BR latex (1)
را ببینید.
.TP
.BI -mktex \ fmt
فعال‌سازی
.RI mktex fmt ،
که در آن
.I fmt
باید یکی از مقادیر
.IR tex ،
.IR tfm ،
.IR fmt
یا
.IR pk
باشد.
.TP
.BI -no-mktex \ fmt
غیرفعال‌سازی
.RI mktex fmt ،
که در آن
.I fmt
باید یکی از مقادیر
.IR tex ،
.IR tfm ،
.IR fmt
یا
.IR pk
باشد.
.TP
.BI -output-directory \ directory
نوشتن فایل‌های خروجی در
.I directory
به جای دایرکتوری جاری. جستجوی فایل‌های ورودی ابتدا در
.I directory
و سپس در امتداد مسیر جستجوی عادی انجام می‌شود.
.TP
.B -parse-first-line
اگر اولین خط از فایل ورودی اصلی با
.I %&
شروع شود، برای یافتن نام dump تجزیه می‌شود.
.TP
.B -no-parse-first-line
غیرفعال‌سازی تجزیه اولین خط از فایل ورودی اصلی.
.TP
.B -pdf
فعال‌سازی شبیه‌سازی دستورات اولیه رایج
.BR pdftex .
این گزینه به گزینه
.B -ini
نیاز دارد و متضمن گزینه
.B -ltx
است.
.BR pdftex (1)
را ببینید.
.TP
.B -prof
فعال‌سازی تحلیل کارایی (profiling) به محض ورود \*(TX به حلقه اصلی. اگر از این گزینه استفاده نشود، تحلیل کارایی باید با استفاده از دستور اولیه \eprofileon فعال گردد. همچنین می‌توان تحلیل کارایی را با دستور اولیه \eprofileoff خاموش کرد.
.TP
.BI -progname \ name
عمل کردن در قالب برنامه
.IR name .
این امر بر فرمت مورد استفاده و مسیرهای جستجو تأثیر می‌گذارد.
.TP
.B -version
نمایش اطلاعات نسخه و خروج.
.\"=====================================================================.SH "محیط (ENVIRONMENT)"
برای جزئیات دقیق چگونگی استفاده از متغیرهای محیطی، به مستندات کتابخانهٔ Kpathsea (برای نمونه، گره «Path specifications») مراجعه کنید.
از ابزار
.B kpsewhich
می‌توان برای پرس‌وجوی مقادیر متغیرها استفاده کرد.
.PP
.TP
.B TEXMFOUTPUT
به‌طور معمول، \*(TX فایل‌های خروجی خود را در دایرکتوری جاری قرار می‌دهد. اگر هر یک از فایل‌های خروجی در آنجا باز نشوند، تلاش می‌کند آن را در دایرکتوری مشخص‌شده در متغیر محیطی TEXMFOUTPUT باز کند.
هیچ مقدار پیش‌فرضی برای این متغیر وجود ندارد. برای مثال، اگر دستور
.I texprof  paper
را اجرا کنید و دایرکتوری جاری قابل نوشتن نباشد و متغیر TEXMFOUTPUT دارای مقدار
.IR /tmp
باشد، \*(TX تلاش می‌کند فایل‌های
.I /tmp/paper.log ،
.I /tmp/paper.dvi ،
و
.I /tmp/paper.tprof
را ایجاد کند. متغیر TEXMFOUTPUT برای فایل‌های ورودی نیز بررسی می‌شود، زیرا \*(TX اغلب فایل‌هایی تولید می‌کند که پس از آن باید خوانده شوند؛ برای ورودی، هیچ پسوندی (مانند «.tex») به‌طور پیش‌فرض افزوده نمی‌شود و نام ورودی صرفاً به همان صورتی که داده شده بررسی می‌شود.
.TP
.B TEXINPUTS
مسیر جستجو برای فایل‌های
.I \einput
و
.IR \eopenin .
این مسیر معمولاً با «.» آغاز می‌شود تا فایل‌های کاربر پیش از فایل‌های سیستمی پیدا شوند. یک مؤلفهٔ خالی در مسیر با مسیرهای تعریف‌شده در فایل
.I texmf.cnf
جایگزین خواهد شد. برای مثال، TEXINPUTS را روی ".:/home/user/tex:" تنظیم کنید تا دایرکتوری جاری و «/home/user/tex» به ابتدای مسیر جستجوی استاندارد افزوده شوند.
.TP
.B TEXFORMATS
مسیر جستجو برای فایل‌های format.
.TP
.B TFMFONTS
مسیر جستجو برای فایل‌های سنجهٔ قلم
.RI ( .tfm ).
.TP
.B SOURCE_DATE_EPOCH
اگر تنظیم شود، مقدار آن بر حسب ثانیه‌های مبدأ (epoch-seconds) در نظر گرفته شده و برای تاریخ ایجاد و به عنوان لحظهٔ مرجع برای دستورهای اولیه مرتبط با زمان در \*(LX استفاده خواهد شد. این متغیر برای ساخت‌های بازتولیدپذیر (reproducible builds) مفید است.
.TP
.B FORCE_SOURCE_DATE
اگر روی مقدار "1" تنظیم شود، دستورهای اولیه مرتبط با زمان در \*(TX
.RI ( \eyear ،
.IR \emonth ،
.IR \eday ،
.IR \etime )
نیز از مقدار SOURCE_DATE_EPOCH مقداردهی اولیه می‌شوند. در صورت وجود هرگونه جایگزین امکان‌پذیر، استفاده از این روش توصیه نمی‌شود.
.PP
متغیرهای محیطی بسیار بیشتری در رابطه با جستجوی مسیر ممکن است بررسی شوند. راهنمای Kpathsea را ببینید.
.\"=====================================================================
.SH "فایل‌ها (FILES)"
محل فایل‌های ذکرشده در زیر از سیستمی به سیستم دیگر متفاوت است. از ابزار
.B kpsewhich
برای یافتن محل آن‌ها استفاده کنید.
.TP
.I *.tfm
فایل‌های سنجه (metric) برای قلم‌های \*(TX.
.TP
.I *.fmt
فایل‌های format پیش‌پردازش‌شدهٔ \*(TX.
.TP
.I *.pk *.pfb
فایل‌های قلم مورد استفادهٔ \*(TX.
.\"=====================================================================.SH "نکات (NOTES)"
این صفحهٔ راهنما جامع نیست. مستندات کامل برای پروفایلر \*(TX را می‌توان در
.IR texprof.pdf
یافت. اطلاعات بیشتر را می‌توان در راهنمای
.IR "Kpathsea library"
پیدا کرد.
.\"=====================================================================
.SH "گزارش باگ‌ها (BUGS)"
این نسخه از پروفایلر \*(TX تمامی دستورهای اولیه‌ای (primitives) را که pdftex ارائه می‌دهد پیاده‌سازی نمی‌کند، و علاوه بر این، اثرهای جانبی یکسانی تولید نخواهد کرد.
.\"=====================================================================
.SH "در دسترس بودن (AVAILABILITY)"
پروفایلر \*(TX باید روی طیف گسترده‌ای از معماری‌های ماشین و سیستم‌عامل‌ها کامپایل شود. تابع مورد استفاده برای دریافت اطلاعات زمان‌بندی، مختص POSIX است.
.PP
سورس‌کدهای پروفایلر \*(TX در آدرس زیر میزبانی می‌شوند:
.BR https://github.com/ruckertm/HINT
.\"=====================================================================
.SH "همچنین ببینید (SEE ALSO)"
.BR texprofiler (1)،
.BR tex (1)،
.BR latex (1)،
.BR pdftex (1)،
.BR pdflatex (1)
و
.BR kpsewhich (1).
.\"=====================================================================
.SH "نویسندگان (AUTHORS)"
نویسندهٔ اصلی پروفایلر \*(TX، Martin Ruckert است،
همراه با افزونه‌های e\*(TX توسط Peter Breitenlohner،
افزونه‌های \*(LX توسط Thierry Laronde،
و
کتابخانهٔ kpathsearch توسط Karl Berry.
.PP
\*(TX توسط Donald E. Knuth طراحی شده است،
کسی که آن را با استفاده از سیستم \*(WB خود برای برنامه‌های Pascal پیاده‌سازی کرد.
.PP
افراد بسیار بیشتری در این سامانه حروف‌چینی که امروزه به نام \*(TX شناخته می‌شود مشارکت کرده‌اند؛
بسیار بیشتر از آن که بتوان نام همهٔ آن‌ها را در اینجا آورد.
.\" vim: syntax=nroff