نام (NAME)

texlogsieve - فیلتر و خلاصه‌سازی فایل‌های گزارش (log) لیتک

خلاصه دستور (SYNOPSIS)

texlogsieve [OPTION]... [INPUT FILE]

توضیحات (DESCRIPTION)

دستور texlogsieve یک فایل گزارش لیتک (یا ورودی استاندارد در صورتی که فایلی مشخص نشده باشد) را می‌خواند، پیام‌های با اهمیت کمتر را فیلتر کرده و یک گزارش خلاصه‌شده را نمایش می‌دهد.

ابزار texlogsieve باید از همان دایرکتوری‌ای اجرا شود که [pdf|lua|xe]latex اجرا می‌شود، زیرا به دنبال فایل‌های استفاده‌شده در حین کامپایل می‌گردد (بسته‌های بارگذاری‌شده از دایرکتوری جاری، فایل‌های فراخوانی‌شده با \input و غیره). همچنین، از آن‌جا که نمی‌تواند تشخیص دهد لیتک (LaTeX) چه زمانی منتظر ورودی کاربر متوقف شده است، هنگامی که texlogsieve در حال خواندن از یک لوله (pipe) است، حتماً باید LaTeX را در حالت nonstopmode اجرا کنید.

این برنامه تلاش زیادی برای مدیریت صحیح شکست خطوط (line wrapping) در TeX انجام می‌دهد. متغیر پیکربندی max_print_line در TeX را درک می‌کند و مقدار آن را از همان مکان‌هایی می‌خواند که خود TeX می‌خواند. تنظیم max_print_line روی مقداری بزرگ‌تر از 9999 باعث می‌شود texlogsieve از شکستن خطوط صرف‌نظر کند.

تنظیمات پیش‌فرض معقول هستند؛ امید است تنها با اجرای دستور زیر:

[pdf|lua|xe]latex -interaction nonstopmode myfile.tex | texlogsieve

یا

texlogsieve myfile.log

از نتیجهٔ حاصل راضی باشید.

گزینه‌ها (OPTIONS)

--page-delay, --no-page-delay: فعال/غیرفعال‌سازی گروه‌بندی پیام‌ها بر اساس صفحه پیش از نمایش. هنگام فعال بودن، پیام‌ها تنها پس از پایان یافتن صفحهٔ جاری (shipout) چاپ می‌شوند. مزیت این کار این است که شمارهٔ صفحه در پیام گنجانده می‌شود (به‌طور پیش‌فرض فعال است).
--summary, --no-summary: فعال/غیرفعال‌سازی خلاصهٔ نهایی (به‌طور پیش‌فرض فعال است).
--only-summary: هیچ پیامی چاپ نشود و تنها خلاصهٔ نهایی نمایش داده شود (به‌طور پیش‌فرض غیرفعال است).
--shipouts, --no-shipouts: فعال/غیرفعال‌سازی گزارش shipoutها (به‌طور پیش‌فرض با page-delay غیرفعال و با no-page-delay فعال است).
--file-banner, --no-file-banner: نمایش دادن/ندادن پیام‌های بنر “From file...” (به‌طور پیش‌فرض فعال است، مگر در سطح DEBUG که در آن صورت زاید و گیج‌کننده خواهد بود).
--repetitions, --no-repetitions: مجاز دانستن/جلوگیری از پیام‌های تکراری (به‌طور پیش‌فرض غیرفعال است، یعنی پیام‌های تکراری سرکوب می‌شوند).
--be-redundant, --no-be-redundant: نمایش/سرکوب پیام‌های عادی که در خلاصه نیز نمایش داده می‌شوند. این گزینه بر پیام‌هایی تأثیر می‌گذارد که خلاصه‌های ویژه‌ای دارند (مانند under/overfull boxes یا ارجاعات نامشخص). با --no-be-redundant (پیش‌فرض)، این پیام‌ها فیلتر شده و تنها در خلاصهٔ نهایی ظاهر می‌شوند.
--box-detail, --no-box-detail: گنجاندن/حذف اطلاعات با جزئیات مربوط به under/overfull boxes در خلاصهٔ نهایی. با --no-box-detail، خلاصه تنها فهرستی از صفحات و فایل‌هایی را نمایش می‌دهد که دارای under/overfull box بوده‌اند (به‌طور پیش‌فرض فعال است).
--ref-detail, --no-ref-detail: گنجاندن/حذف اطلاعات با جزئیات مربوط به ارجاعات تعریف‌نشده در خلاصهٔ نهایی. با --no-ref-detail، خلاصه تنها فهرستی از ارجاعات تعریف‌نشده را بدون شماره صفحات و نام فایل‌ها ارائه می‌دهد (به‌طور پیش‌فرض فعال است).
--cite-detail, --no-cite-detail: گنجاندن/حذف اطلاعات با جزئیات مربوط به استنادهای (citations) تعریف‌نشده در خلاصهٔ نهایی. با --no-cite-detail، خلاصه تنها فهرستی از استنادهای تعریف‌نشده را بدون شماره صفحات و نام فایل‌ها ارائه می‌دهد (به‌طور پیش‌فرض فعال است).
--summary-detail, --no-summary-detail: تغییر وضعیت هم‌زمان گزینه‌های --box-detail، --ref-detail و --cite-detail.
--heartbeat, --no-heartbeat: فعال/غیرفعال‌سازی نشانگر پیشرفت در حالت page-delay (به‌طور پیش‌فرض فعال است).
--color, --no-color: فعال/غیرفعال‌سازی خروجی رنگی. در سیستم‌عامل ویندوز، این گزینه تنها بر روی ویندوز ۱۰ به‌روزشده یا نسخه‌های پس از آن کار خواهد کرد (به‌طور پیش‌فرض غیرفعال است).
--tips, --no-tips: فعال/غیرفعال‌سازی پیشنهاد راه‌حل برای برخی از هشدارهای شناخته‌شده (به‌طور پیش‌فرض فعال است).
-l LEVEL, --minlevel=LEVEL: پالایش پیام‌هایی که سطح اهمیت آن‌ها پایین‌تر از LEVEL است. سطوح معتبر عبارتند از DEBUG (بدون فیلتر)، INFO، WARNING، CRITICAL و UNKNOWN (پیش‌فرض: WARNING).
-u, --unwrap-only: پیام‌ها را فیلتر نمی‌کند و خلاصه‌ای تولید نمی‌کند، تنها خطوط طولانی شکسته را باز می‌کند (unwrap). خروجی باید بسیار شبیه (اما نه کاملاً یکسان) به فایل ورودی باشد، با این تفاوت که خطوط شکسته بازسازی شده‌اند. این گزینه پرچم‌های -l debug، --no-summary، --no-page-delay، --repetitions، --be-redundant، --shipouts و --no-file-banner را فعال می‌کند، و همچنین پیام‌های پرگو و تفصیلی “open/close file” و “shipout” را حذف کرده و در عوض قالب TeX را با پرانتزها و قلاب‌ها شبیه‌سازی می‌کند. این قابلیت زمانی مفید است که گزارش‌های تولیدشده توسط ابزاری دیگر را ترجیح می‌دهید اما می‌خواهید از الگوریتم باز کردن خطوط texlogsieve بهره‌مند شوید؛ خروجی تولیدشده با این گزینه باید توسط ابزارهای دیگر قابل تجزیه (parse) باشد (هرچند احتمالاً باید ابزار دیگر را مجبور کنید تلاشی برای باز کردن مجدد خطوط نکند).
--silence-package=PKGNAME: پالایش پیام‌هایی که می‌توان مبدأ آن‌ها را بستهٔ مشخص‌شده تشخیص داد. از این گزینه به دفعات برای سرکوب پیام‌های حاصل از چندین بستهٔ مختلف استفاده کنید.
--silence-string=EXCERPT OF UNWANTED MESSAGE: پالایش پیام‌هایی که شامل رشتهٔ داده‌شده هستند (برای حذف کل پیام، تنها کافی است بخشی از متن پیام را مشخص کنید). از این گزینه به دفعات برای سرکوب چندین پیام مختلف استفاده کنید. این رشته باید در یک خط باشد، اما این موضوع برای پیام‌های لاگ چندخطی مشکلی ایجاد نمی‌کند: نویسه‌های فاصله (space) در رشتهٔ ارائه‌شده با هر دنباله‌ای از فاصله‌ها در پیام، از جمله شکست خطوط (newlines)، مطابقت داده می‌شوند. در صورت نیاز می‌توانید در ابتدای رشته عبارت “////” را قرار دهید که در این صورت استفاده از الگوهای انطباق شیوهٔ Lua مجاز خواهد بود (https://www.lua.org/pil/20.2.html). توجه داشته باشید که رشته به‌صورت عینی (verbatim) پردازش می‌شود: ممکن است برای پوسته (shell) لازم باشد آن را درون علامت‌های نقل‌قول قرار داده یا نویسه‌های ویژه‌ای مانند “\” را گریز دهید (escape کنید)، اما چنین کاری در فایل پیکربندی غیرضروری (و حتی آسیب‌رسان) خواهد بود.
--silence-file=FILENAME OR FILE GLOB: پالایش پیام‌هایی که هنگام پردازش فایل داده‌شده ایجاد شده‌اند. از مسیرهای مطلق یا نسبی استفاده نکنید، تنها نام فایل مجاز است. الگوهای نام فایل ساده (file glob) مانند “*.cls” طبق انتظار عمل می‌کنند. اگر تنها از بسته‌هایی استفاده می‌کنید که آن‌ها را می‌شناسید، ساکت کردن الگوهایی نظیر “*.sty” می‌تواند فکر خوبی باشد (توجه داشته باشید که این کار تمام پیام‌های تمام بسته‌ها را حذف نمی‌کند، بلکه تنها پیام‌هایی را که در حین بارگذاری بسته‌ها صادر می‌شوند سرکوب می‌کند). برای سرکوب پیام‌های چند فایل مختلف، از این گزینه به دفعات استفاده کنید.
--semisilence-file=FILENAME OR FILE GLOB: دقیقاً مانند گزینهٔ پیشین، اما به‌صورت غیربازگشتی عمل می‌کند. این بدان معناست که پیام‌های تولیدشده در هنگام پردازش فایل داده‌شده حذف می‌شوند، اما پیام‌های حاصل از فایل‌های دیگری که توسط آن فراخوانی شده‌اند پابرجا می‌مانند. برای نمونه، اگر فایل “chapters.tex” فایل‌های “chapter1.tex” و “chapter2.tex” را (توسط \input) فراخوانی کند، استفاده از “--silence-file=chapters.tex” مانع از نمایش پیام‌های ایجادشده توسط هر سه فایل خواهد شد. اما اگر از “--semisilence-file=chapters.tex” استفاده نمایید، پیام‌های تولیدشده توسط chapters.tex سرکوب می‌شوند ولی پیام‌های chapter1.tex یا chapter2.tex نمایش داده خواهند شد..TP --add-[debug|info|warning|critical]-message=MESSAGE افزودن MESSAGE به فهرست پیام‌های شناخته‌شده برای برنامه با سطح اهمیت مشخص‌شده؛ برای اطلاعات بیشتر در این رابطه، بخش پیام‌های ناشناخته (UNRECOGNIZED MESSAGES) را در زیر ببینید. همانند --silence-string، این پیام‌ها نیز باید تک‌خطی باشند؛ برخلاف --silence-string، باید به طور صریح \n را برای مشخص کردن شکست خط قرار دهید (این دقیقاً یک نویسهٔ بک‌اسلش به همراه حرف “n” است، نه نویسهٔ خط جدید). برای استفاده از تطبیق الگو به سبک lua می‌توانید در ابتدای رشته عبارت “////” را قرار دهید، اما درج \n برای نشان دادن شکست خط اجتناب‌ناپذیر است. از این گزینه‌ها می‌توانید چندین بار برای افزودن پیام‌های مختلف استفاده کنید.
--set-to-level-[debug|info|warning|critical]=EXCERPT OF MESSAGE: بازتعریف سطح اهمیت پیام‌هایی که حاوی رشتهٔ ارائه‌شده هستند به سطح مشخص‌شده. توضیحات مربوط به --silence-string را بررسی کنید، چرا که این گزینه نیز به شیوه‌ای مشابه کار می‌کند. از این گزینه‌ها چندین بار برای تغییر دادن سطح اهمیت پیام‌های مختلف استفاده کنید.
-c CFGFILE, --config-file=CFGFILE: خواندن گزینه‌ها از فایل پیکربندی مشخص‌شده علاوه بر فایل‌های پیکربندی پیش‌فرض (بخش فایل پیکربندی (CONFIGURATION FILE) را ببینید).
-v, --verbose: چاپ فهرست فایل‌های پیکربندی خوانده‌شده و خلاصه‌ای کوتاه از مهم‌ترین گزینه‌های پیکربندی فعال.
-h, --help: نمایش توضیحات مختصر گزینه‌ها.
--version: چاپ نسخهٔ برنامه.

پیام‌های ناشناخته (UNRECOGNIZED MESSAGES)

texlogsieve به طور خودکار پیام‌هایی مانند “Package blah Info:...” یا “LaTeX Warning:...” را مدیریت می‌کند. با این حال، بسیاری از پیام‌ها از این الگو پیروی نمی‌کنند. برای اینکه texlogsieve وظیفهٔ خود را انجام دهد، باید از قبل این پیام‌های دیگر را بشناسد.

اگرچه texlogsieve به طور پیش‌فرض پیام‌های متعددی را شناسایی می‌کند، ممکن است با پیامی تولیدشده توسط یک بسته روبه‌رو شوید که آن را نمی‌شناسد (می‌توانید با استفاده از “-l unknown” این مورد را بررسی کنید). در این حالت، می‌توانید از گزینه‌های --add-[debug|info|warning|critical]-message برای افزودن آن به فهرست پیام‌های شناخته‌شده توسط برنامه استفاده کنید.

فایل پیکربندی (CONFIGURATION FILE)

texlogsieve همواره به طور خودکار به دنبال فایل پیکربندی (اختیاری) texlogsieverc در $TEXINPUTS می‌گردد (یعنی با استفاده از Kpathsea جستجو می‌کند). در پیکربندی پیش‌فرض، دایرکتوری جاری در $TEXINPUTS قرار دارد، بنابراین افزودن یک فایل پیکربندی با این نام به دایرکتوری پروژه برای به کار انداختن آن کافی است. گزینه‌های درون فایل پیکربندی دقیقاً مشابه گزینه‌های طولانی خط فرمان شرح داده شده در بالا هستند، اما بدون نویسه‌های پیشین “--”. خطوطی که با علامت “#” شروع می‌شوند توضیح هستند. یک نمونه فایل پیکربندی:

no-page-delay
# no-page-delay enables shipouts, but we do not want that
no-shipouts
silence-string = Hyperreferences in rotated content will be misplaced
# no need to escape the "\" (or any other) character
silence-string = Using \overbracket and \underbracket from `mathtools'
# silence a string using lua pattern matching
silence-string = ////luaotfload | aux : font no %d+ %(.-%)
silence-files = *.sty

اگر مایلید یک فایل پیکربندی عمومی برای تمام پروژه‌های خود داشته باشید (که ایدهٔ خوبی است)، آن را در سیستم‌های شبه‌یونیکس در مسیر $HOME/.texlogsieverc قرار دهید؛ در ویندوز، آن را در %LOCALAPPDATA%\texlogsieverc (C:\Users\<username>\AppData\Local) یا %APPDATA%\texlogsieverc (C:\Documents and Settings\<username>\Application Data یا C:\Users\<username>\AppData\Roaming)..SH "محدودیت‌ها (LIMITATIONS)"

برنامه texlogsieve تلاش نمی‌کند کار هوشمندانه‌ای در قبال پیام‌های خطا انجام دهد (اما در صورت شناسایی خطا، هشداری را در خلاصه نمایش می‌دهد؛ در این رابطه بخش TIPS در مستندات pdf را بررسی کنید)؛ در صورت بروز خطا، احتمالاً در هر صورت ترجیح می‌دهید مستقیماً نگاهی به فایل log بیندازید. همچنین نمی‌تواند تشخیص دهد که آیا LaTeX برای دریافت ورودی کاربر متوقف شده است یا خیر، بنابراین هنگامی که texlogsieve در حال خواندن از یک pipe است، واقعاً باید LaTeX را در nonstopmode اجرا کنید.

از آنجا که باید بداند انتظار چه پیام‌هایی را داشته باشد، texlogsieve در حال حاضر برای LaTeX بهینه‌سازی شده است؛ نمی‌دانم با ConTeXt یا plain TeX چگونه کار خواهد کرد. با این حال، افزودن پشتیبانی از آن‌ها نباید چندان دشوار باشد.

همچنین ببینید (SEE ALSO)

مستندات pdf (در TeXLive، دستور texdoc texlogsieve را امتحان کنید) کمی مشروح‌تر از این manpage است و شامل بخش TIPS می‌باشد که ممکن است برایتان مفید باشد.

اگر می‌خواهید درباره فایل log در TeX و نحوه عملکرد برنامه بیشتر بدانید، توضیحات ابتدایی در کد را بررسی کنید.

گزارش باگ‌ها و توسعه (BUGS AND DEVELOPMENT)

https://gitlab.com/lago/texlogsieve

کپی‌رایت و تکثیر (COPYRIGHT)

کپی‌رایت © 2021-2026 Nelson Lago <lago@ime.usp.br>
اجازه‌نامه GPLv3+: گنو GPL نسخه ۳ یا بالاتر https://gnu.org/licenses/gpl.html.

این یک نرم‌افزار آزاد است: شما در تغییر و بازتوزیع آن آزاد هستید. تا حد مجاز قانون، هیچ ضمانتی وجود ندارد.