TEXFOT(1) Karl Berry TEXFOT(1)

texfot - اجرای TeX و فیلتر کردن گزارش برخط برای پیام‌های مهم

texfot [option]... texcmd [texarg...]

دستور "texfot" دستور texcmd را با آرگومان‌های داده‌شدهٔ texarg اجرا می‌کند و خروجی برخط را برای یافتن پیام‌های «مهم» فیلتر می‌نماید. مقدار خروج آن همان مقدار خروج texcmd است. مثال‌ها:

# نمونه فراخوانی ساده:
texfot pdflatex file.tex

# به‌طور معمول خروجی کامل پیش از فیلتر شدن درون /tmp/fot.$UID کپی می‌شود،
# اما می‌توان آن را نادیده گرفت یا نام فایل را تغییر داد:
texfot --tee=/dev/null lualatex file.tex

# نمونه‌ای از فراخوانی پیچیده‌تر موتور:
texfot xelatex --recorder '\nonstopmode\input file'

در اینجا نمونه‌ای از ظاهر خروجی (به‌طور کامل) در یک اجرای بدون خطا آورده شده است:

/path/to/texfot: invoking: pdflatex hello.ltx
This is pdfTeX, Version 3.141592653-2.6-1.40.24 (TeX Live 2022) (preloaded format=pdflatex)
Output written on hello.pdf (1 page, 94415 bytes).

به‌جز گزینه‌های اختصاصی خود که در ادامه شرح داده شده‌اند، "texfot" صرفاً دستور داده‌شده را با آرگومان‌های مشخص‌شده اجرا می‌کند (رویکردی مشابه نحو خط فرمان دستورهای "env"، "nice"، "timeout" و غیره). بدین ترتیب، "texfot" با هر موتوری و با هر گزینه‌ای در خط فرمان کار می‌کند.

دستور "texfot" فایل گزارش (log) یا هر فایل خروجی احتمالی دیگری را بررسی نمی‌کند؛ بلکه تنها خروجی استاندارد (stdout) و خطای استاندارد (stderr) دستور را تحلیل می‌کند. ابتدا stdout پردازش می‌شود و سپس stderr. دستور "texfot" تمام خطوط پذیرفته‌شده را در خروجی استاندارد خود می‌نویسد.

پیام‌های نشان داده‌شده مواردی هستند که به احتمال زیاد نیازمند اقدام از سوی نویسنده‌اند: پیام‌های خطا، جعبه‌های overfull و underfull، ارجاعات تعریف‌نشده، نویسه‌های ناموجود در فونت‌ها و غیره..SH "روند عملیات (FLOW OF OPERATION)" ترتیب بررسی خطوط خروجی به شرح زیر است:

1.
اگر لازم است ``خط بعدی'' چاپ شود (پایین را ببینید)، آن را چاپ کن.
2.
در غیر این صورت، اگر خط با هر یک از عبارت‌های باقاعدهٔ ارائه‌شده توسط کاربر برای پذیرش (که با "--accept" مشخص می‌شوند، پایین را ببینید) مطابقت داشته باشد، به همان ترتیب، آن را چاپ کن.
3.
در غیر این صورت، اگر خط با فهرست توکار عبارت‌های باقاعده برای نادیده‌گرفتن، یا هر فهرستی از عبارت‌های باقاعده ارائه‌شده توسط کاربر برای نادیده‌گرفتن (که با "--ignore" مشخص می‌شوند، پایین را ببینید) مطابقت داشته باشد، به همان ترتیب، آن را نادیده بگیر.
4.
در غیر این صورت، اگر خط با فهرست عبارت‌های باقاعده‌ای که باید خط بعدی آن‌ها نیز نشان داده شود (در کل دو خط) مطابقت داشته باشد، این خط را نشان بده و پرچم ``خط بعدی'' را برای تکرار بعدی حلقه تنظیم کن. نمونه‌هایی از این موارد، پیام‌های خطای رایج "!" و "filename:lineno:" هستند که عموماً یک خط حاوی جزئیات مشخص دربارهٔ خطا در ادامهٔ آن‌ها می‌آید.
5.
در غیر این صورت، اگر خط با فهرست عبارت‌های باقاعده برای نمایش مطابقت داشته باشد، آن را نشان بده.
6.
در غیر این صورت، حالت پیش‌فرض: اگر خط از stdout آمده باشد، آن را نادیده بگیر؛ اگر خط از stderr آمده باشد، آن را (در stdout) با پیشوند "[stderr] " چاپ کن. این تفکیک به این دلیل انجام می‌شود که موتورهای TeX پیام‌های نسبتاً اندکی در stderr می‌نویسند، و احتمالاً هر پیامی از این دست باید بررسی شود.

به محض این که یک بررسی مطابقت پیدا کند، برنامه برای پردازش خط بعدی ادامه می‌دهد.

"texfot" منحصراً خط‌به‌خط مطابقت را بررسی می‌کند؛ با این حال، خود TeX خطوط خروجی را معمولاً در ستون 79 می‌شکند. این بدان معناست که ممکن است تطابق‌ها ناموفق باشند چرا که متنِ در حال بررسی روی دو خط شکسته شده است. برای رفع این مشکل، می‌توانید با تنظیم پارامتر "max_print_line" روی یک عدد بزرگ، چه در متغیرهای محیط و چه در خط فرمان، شکستن خطوط توسط TeX را عملاً غیرفعال کنید:

# هنگامی که خطاها به دلیل شکستن خطوط توسط TeX دیده نمی‌شوند:
texfot pdftex --cnf-line max_print_line=999 file.tex

# معادل آن:
env max_print_line=999 texfot pdftex file.tex

در بررسی کد منبع این اسکریپت درنگ نکنید؛ این اسکریپت اساساً یک حلقهٔ سرراست است که خروجی را با فهرست‌های گوناگون یادشده مطابقت می‌دهد. می‌توانید عبارت‌های باقاعدهٔ دقیقی را که در دسته‌های مختلف بررسی می‌شوند، در کد منبع مشاهده کنید.

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

موارد زیر گزینه‌های خود "texfot" هستند (نه موتور TeX که فراخوانی می‌شود؛ برای آن به مستندات همان موتور یا خروجی "--help" آن مراجعه کنید).

نخستین آرگومان غیرگزینه، تجزیهٔ گزینه‌های "texfot" را متوقف می‌کند، و باقی خط فرمان بدون تجزیهٔ بیشتر، به عنوان دستور TeX اجرا می‌شود. برای نمونه، "texfot --debug tex --debug" اطلاعات اشکال‌زدایی را هم از "texfot" و هم از "tex" خروجی می‌دهد. موتورهای TeX، بر خلاف بسیاری از برنامه‌های استاندارد، نیاز دارند که گزینه‌ها پیش از نام فایل ورودی یا متن مشخص شوند.

گزینه‌ها می‌توانند با - یا -- آغاز شوند، و تا جایی که ابهامی وجود نداشته باشد می‌توان آن‌ها را کوتاه کرد. با این حال، در اسکریپت‌ها بهتر است از نام کامل گزینه‌ها استفاده شود تا از تداخل‌های احتمالی با گزینه‌های جدید در آینده جلوگیری گردد.

"--accept" regexp
خطوطی را در خروجی TeX که با عبارت باقاعدهٔ (Perl) regexp مطابقت دارند، می‌پذیرد. می‌توان این گزینه را تکرار کرد. این فهرست ابتدا بررسی می‌شود، بنابراین صرف‌نظر از سایر گزینه‌ها، هر تطابقی نشان داده خواهد شد. این عبارت‌های باقاعده به‌طور خودکار لنگرگذاری نمی‌شوند (یا دچار تغییرات دیگر نمی‌گردند)، بلکه دقیقاً همان‌گونه که هستند به کار می‌روند.
"--debug"
"--no-debug"
آنچه برنامه انجام می‌دهد را در خطای استاندارد خروجی می‌دهد (یا نمی‌دهد)؛ به‌طور پیش‌فرض غیرفعال است.
"--ignore" regexp
خطوطی را در خروجی TeX که با عبارت باقاعدهٔ (Perl) regexp مطابقت دارند، نادیده می‌گیرد. می‌توان این گزینه را تکرار کرد. این موارد به جای جایگزینی، به مجموعهٔ پیش‌فرض عبارت‌های باقاعدهٔ نادیده‌گرفتن اضافه می‌شوند. همانند عبارت‌های باقاعدهٔ پذیرش، این‌ها نیز به‌طور خودکار لنگرگذاری نمی‌شوند (یا تغییر دیگری نمی‌کنند).
"--interactive"
"--no-interactive"
به‌طور پیش‌فرض، ورودی استاندارد به فرایند TeX بسته می‌شود تا هرگز حالت تعاملی TeX (انتظار برای ورودی هنگام بروز خطا، خط فرمان "*"، و غیره) فعال نشود. دادن "--interactive" اجازه می‌دهد تعامل صورت گیرد.
"--quiet"
"--no-quiet"
به‌طور پیش‌فرض، دستور TeX در حال فراخوانی روی خروجی استاندارد گزارش می‌شود؛ "--quiet" این گزارش را حذف می‌کند. برای داشتن یک اجرای کاملاً بی‌صدا، خروجی استاندارد را تغییر مسیر دهید: "texfot ... >/dev/null". (تنها پیام‌های خطای استاندارد باید خطاهای خود "texfot" باشند، بنابراین نیازی به تغییر مسیر آن نیست، هرچند مسلماً آن کار نیز قابل انجام است.)
"--stderr"
"--no-stderr"
حالت پیش‌فرض این است که "texfot" هر آنچه را که توسط دستور TeX در stderr نوشته می‌شود (روی stdout) گزارش دهد. "--no-stderr" این گزارش را حذف می‌کند. (برخی برنامه‌ها، که "dvisvgm" یکی از آن‌هاست، می‌توانند در stderr نسبتاً پرپیام و پرگو باشند.)
"--tee" file
به‌طور پیش‌فرض، خروجیِ در حال فیلتر شدن، پیش از فیلتر، با دستور "tee" در فایلی نوشته می‌شود تا در صورت بروز مشکل، بررسی خروجی کامل آسان باشد.

مقدار پیش‌فرض file برابر "$TMPDIR/fot."uid است؛ اگر "TMPDIR" تنظیم نشده باشد، در صورت تنظیم بودن "TMP" از آن استفاده می‌شود؛ و اگر هیچ‌کدام تنظیم نشده باشند، دایرکتوری پیش‌فرض "/tmp" خواهد بود. برای نمونه: "/tmp/fot.1001". پسوند uid همان userid مؤثر فرایند است که برای جلوگیری مقدماتی از تداخل میان کاربران گوناگون روی همان سیستم الحاق می‌شود.

این گزینه امکان تعیین فایلی متفاوت را فراهم می‌کند. برای دور ریختن خروجی اصلی از "--tee /dev/null" استفاده کنید.

"--version"
اطلاعات نسخه را خروجی داده و با موفقیت خارج می‌شود.
"--help"
این راهنما را نمایش داده و با موفقیت خارج می‌شود..SH "دلایل توسعه (RATIONALE)" من این برنامه را نوشتم زیرا در جریان کارم به‌عنوان ویراستار TUGboat (https://tug.org/TUGboat، ارسال مقالات همیشه مورد استقبال است!)، اسناد متعددی را بارها و بارها اجرا می‌کنم. در میان حجم عظیم خروجی‌های یکنواخت و کسل‌کننده از سوی TeX، مانند خوانده شدن فایل‌های استایل و فونت‌های مورد استفاده، هشدارهایی که نیاز به دیدنشان داشتم به‌سادگی گم می‌شدند. می‌خواستم تنها و همهٔ پیام‌هایی را ببینم که نیازمند اقدامی از سوی من بودند.

برنامه‌های دیگری با ماهیت مشابه، بستهٔ LaTeX با نام "silence" و شمار زیادی از پوشش‌دهنده‌های دیگر (La)TeX را پیدا کردم، اما به نظر می‌رسید هیچ‌یک از آن‌ها کاری را که می‌خواستم انجام نمی‌دادند. آن‌ها یا فایل لاگ را می‌خواندند (من می‌خواستم تنها خروجی برخط را بررسی کنم)، یا کمتر یا بیشتر از آنچه مد نظرم بود خروجی می‌دادند، یا اینکه مستلزم فراخوانی TeX به شیوه‌ای متفاوت بودند (می‌خواستم فرایند ساخت من دقیقاً یکسان باقی بماند، به‌ویژه فراخوانی TeX که می‌تواند پیچیده شود). از این رو این اسکریپت کوچک را نوشتم.

در ادامه چند کلیدواژه آورده شده است اگر می‌خواهید گزینه‌های دیگر را بررسی کنید: texloganalyser،‏ pydflatex،‏ logfilter،‏ latexmk،‏ rubber،‏ arara، و جست‌وجوی عبارت "log" در https://ctan.org/search.

"texfot" به زبان Perl نوشته شده و روی Unix اجرا می‌شود. در صورت نصب بودن Perl و سایر نرم‌افزارهای لازم، ممکن است روی Windows نیز کار کند، اما من از Windows استفاده نمی‌کنم و از "texfot" در آن پشتیبانی نمی‌کنم.

این نام از فایل‌های "trip.fot" و "trap.fot" برگرفته شده است که بخشی از آزمون‌های دشوار trip و trap دونالد کنوت (Knuth) هستند و خروجی برخط برنامه‌ها را ثبت می‌کنند. مطمئن نیستم که "fot" در trip و trap مخفف چیست، اما در این مورد می‌توانم وانمود کنم که مخفف "filter online transcript" است :).

این اسکریپت و مستندات آن توسط Karl Berry نوشته شده‌اند و هر دو در مالکیت عمومی (public domain) منتشر شده‌اند. گزارش‌های باگ را به "karl@freefriends.org" ارسال کنید. این برنامه به‌جز صفحهٔ بسته در CTAN، هیچ صفحهٔ خانگی دیگری ندارد: https://ctan.org/pkg/texfot.

$Id: texfot,v 1.54 2026/01/05 17:14:08 karl Exp $
2026-01-05 texfot