نام (NAME)

typog-grep - ابزار grep تخصصی برای عناصر typog-inspect در فایل‌های لاگ LaTeX

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

typog-grep -a|--all|--any [OPTION...] LOG-FILE...

typog-grep [OPTION...] REGEXP LOG-FILE...

فرم نخست، “حالت کشف”، تمام IDهای عناصرِ

<typog-inspect id="ID" ...>

در LOG-FILE را نمایش می‌دهد.

فرم دوم، محتویات (LOG-DATA) آن دسته از عناصر

<typog-inspect id="ID" ...>
LOG-DATA
</typog-inspect>

را که ID آن‌ها در LOG-FILE با REGEXP مطابقت دارد، نمایش می‌دهد.

اگر هیچ LOG-FILEی مشخص نشود، از stdin خوانده می‌شود. نام فایل "-" معادل stdin است..SH "توضیحات (DESCRIPTION)" typog-grep یک پس‌پردازشگر سفارشی‌شده برای فایل‌های log مربوط به LaTeX و محیط "typoginspect" ارائه‌شده توسط بستهٔ LaTeX به نام typog است. این ابزار شباهت بیشتری به ابزار قدیمی sgrep https://www.cs.helsinki.fi/u/jjaakkol/sgrep.html دارد تا به POSIX grep https://pubs.opengroup.org/onlinepubs/9699919799/utilities/grep.html.

در فایل مبدأ LaTeX، کاربر متن یا کد خود را درون یک محیط "typoginspect" قرار می‌دهد:

\begin{typoginspect}{ID}
TEXT-OR-CODE-TO-INVESTIGATE
\end{typoginspect}

که در آن ID برای شناسایی یک یا چند قطعه‌کد قرارگرفته در محیط استفاده می‌شود. ID نیازی نیست که یکتا باشد. سازوکار REGEXP انتخاب گروه‌هایی از IDهای مرتبط را در صورت نام‌گذاری متناسب، آسان می‌کند.

در LOG-FILE، نتیجهٔ محیط به همراه اطلاعات ردگیری (tracing)، به این صورت ظاهر می‌شود:

<typog-inspect id="ID" job="JOB-NAME" line="LINE-NUMBER" page="PAGE-NUMBER">
LOG-DATA
</typog-inspect>

که در آن تمام دنباله‌های حروف بزرگ، فرامتغیر هستند و به‌ویژه JOB-NAME بسط‌یافتهٔ "\jobname" است، LINE-NUMBER شماره خط فایل مبدأ LaTeX در نقطهٔ آغاز محیط "typoginspect" است، و PAGE-NUMBER صفحه‌ای است که خروجی "TEXT-OR-CODE-TO-INVESTIGATE" در آن قرار دارد.

typog-grep محتویات LOG-FILE را بین "<typog-inspect id="ID" ...>" و "</typog-inspect>" بدون در نظر گرفتن خود برچسب‌های XML آشکار می‌سازد. با استفاده از گزینه‌های خط فرمان --job-name، --line-number، و --page-number به JOB-NAME، LINE-NUMBER و PAGE-NUMBER دسترسی پیدا کنید. از --id برای نمایش نام IDهایی که با REGEXP تطابق دارند استفاده کنید.

محیط‌های "typoginspect" می‌توانند تو در تو باشند. typog-grep ساختار تو در تو را در نظر می‌گیرد؛ بدین معنا که اگر ID محیط تو در تو با REGEXP مطابقت نداشته باشد، در خروجی برنامه قرار نخواهد گرفت.

گزینه‌ها (OPTIONS)

فهرست گزینه‌ها بر اساس نام گزینه‌های بلند مرتب شده است.

-a, --all, --any

حالت کشف شناسه (ID-discovery mode): کشف تمام عنصرهای "typog-inspect" مستقل از هرگونه الگوی تطبیقی و چاپ IDهای آن‌ها. نتایج به ترتیب وقوع آن‌ها در LOG-FILEها چاپ می‌شوند. برای دریافت IDها با ترتیب الفبایی، خروجی را به sort هدایت (pipe) کنید.

برای اطلاعات بیشتر، با گزینه‌های --job-name، --line-number، --log-line-number یا --page-number ترکیب کنید.

--color, colour WHEN

رنگی‌کردن محتوای مشخص گزارش برای IDهای تطبیق‌یافته. آرگومان WHEN زمان اعمال رنگ را تعیین می‌کند: "always"، "never" یا "auto". تنظیم "auto" بررسی می‌کند که آیا خروجی استاندارد تغییر مسیر داده شده است یا خیر. این مقدار پیش‌فرض است.

-C, --config KEY=VALUE[:KEY=VALUE[:...]]

تنظیم یک یا چند جفت KEY=VALUE برای پیکربندی. برای توضیح تمام موارد پیکربندی موجود، بخش "CONFIGURATION" را ببینید. برای نمایش پیکربندی پیش‌فرض از گزینهٔ --show-config استفاده کنید.

--debug

فعال‌کردن خروجی اشکال‌زدایی روی stderr.

-E, --encoding ENCODING

تنظیم ENCODING مربوط به LOG-FILE برای تبدیل به UTF-8. حالت پیش‌فرض تنظیم‌نشده است.

از این گزینه برای خلاصی از توالی‌های گریز آزاردهندهٔ "<HEX-DIGITS>" روی پایانه‌های UTF-8 استفاده کنید. برای کدگذاری‌های شناخته‌شده گزینهٔ --show-encodings و برای خلاصه‌ای از تمام کدگذاری‌ها Encode::Supported را ببینید. همچنین به بخش "Some Common Encodings" مراجعه کنید.

پیش از اجرای این ابزار، می‌توانید iconv https://pubs.opengroup.org/onlinepubs/9699919799/utilities/iconv.html (POSIX) یا recode https://github.com/rrthomas/recode (GNU) را روی LOG-FILE اعمال کنید تا نیازی به استفاده از گزینهٔ --encoding نباشد.

-h, --help

نمایش راهنمای مختصر و سپس خروج.

-i, --[no-]id

چاپ نام واقعی ID که با REGEXP مطابقت داشته است. ظاهر ID تطبیق‌یافته را با مورد پیکربندی "id-heading" کنترل کنید.

-y, --[no-]ignore-case

تطبیق IDها بدون تمایز بین حروف بزرگ و کوچک در الگوها و داده‌ها.

-j, --[no-]job-name

چاپ "\jobname" که latex به فایل ورودی مرتبط کرده است.

-n, --[no-]line-number

چاپ شماره خطی در فایل مبدأ LaTeX که محیط "typoginspect" در آن یافت شده است.

-N, --[no-]log-line-number

چاپ شماره خط فایل log که خط فعلی در آن قرار دارد.

-p, --[no-]page-number

چاپ شماره صفحه‌ای در سند حروف‌چینی‌شده که محتوای محیط "typoginspect" در آن شروع می‌شود.

-P, --[no-]pager

تغییر مسیر خروجی از stdout به صفحه‌بندی‌کنندهٔ (pager) پیکربندی‌شده.

--show-config

نمایش پیکربندی پیش‌فرض و خروج.

--show-encodings

نمایش تمام کدگذاری‌های شناخته‌شده و خروج.

-V, --version

نمایش اطلاعات نگارش و خروج.

-w, --[no-]word-regexp

فقط تطبیق کلمات کامل..SH "پیکربندی (CONFIGURATION)"

"id-format"=FORMAT

کنترل FORMAT برای چاپ شناسه‌های منطبق در حالت درون‌خطی (inline-mode)، که در آن FORMAT به "printf" در Perl ارسال می‌شود. پیش‌فرض: %s:.

"id-heading"=0|1

انتخاب میان شیوه‌های چاپ IDهای منطبق با گزینهٔ --id: درون‌خطی (0) یا به‌صورت سربرگ پیش از داده‌های منطبق (1). پیش‌فرض: 0.

"id-heading-format"=FORMAT

کنترل FORMAT برای چاپ IDهای منطبق در حالت سربرگ (heading-mode)، که در آن FORMAT به "printf" در Perl ارسال می‌شود. پیش‌فرض: "--> %s <--".

"id-indent"=INDENT

دندانه‌گذاری برچسب‌های تودرتوی typog-inspect. فقط در ``حالت کشف'' (فرم اول) استفاده می‌شود؛ یعنی زمانی که --all فعال باشد. پیش‌فرض: 8.

"id-max-length"=MAXIMUM-LENGTH

تنظیم حداکثر طول یک ID منطبق برای چاپ. اگر یک ID منطبق از این طول تجاوز کند، بریده می‌شود و سه نویسهٔ آخر آن (تا سقف MAXIMUM-LENGTH) با نقطه جایگزین خواهد شد. پیش‌فرض: 40.

"line-number-format"=FORMAT

کنترل FORMAT برای چاپ شماره خطوط فایل سورس TeX، که در آن FORMAT به "printf" در Perl ارسال می‌شود. پیش‌فرض: %5d.

"log-line-number-format"=FORMAT

کنترل FORMAT برای چاپ شماره خطوط فایل گزارش (log)، که در آن FORMAT به "printf" در Perl ارسال می‌شود. پیش‌فرض: %6d.

"page-number-format"=FORMAT

کنترل FORMAT برای چاپ شماره صفحات، که در آن FORMAT به "printf" در Perl ارسال می‌شود. پیش‌فرض: "[%3d]".

"pager"=PAGER

نام برنامهٔ صفحه‌بندی (pager) برای هدایت خروجی به آن از طریق لوله‌کشی (pipe)، در صورتی که با گزینهٔ --pager اجرا شود. پیش‌فرض: "less".

"pager-flags"=FLAGS

ارسال FLAGS به PAGER. پیش‌فرض: "--quit-if-one-screen".

پیکربندی رنگ (Color Configuration)

برای نحو تعیین مشخصات رنگ، صفحهٔ راهنمای Term::ANSIColor(pm) را ببینید.

وضعیت خروج (EXIT STATUS)

وضعیت خروج برابر 0 است اگر دست‌کم یک ID با REGEXP مطابقت داشته باشد، 1 است اگر هیچ ID با REGEXP مطابقت نداشته باشد، و 2 است اگر خطایی رخ دهد.

هشدارها (CAVEATS)

برچسب پایانی "</typog-inspect>" گاهی بسیار زود در خروجی قرار می‌گیرد و ردگیری به نظر می‌رسد ناقص شده است. با این حال، LaTeX اطلاعات ردگیری درخواست‌شده را با قابلیت اطمینان ثبت می‌کند، اما عملیات نوشتن برای داده‌های ردگیری و کدی که برای چاپ برچسب پایانی استفاده می‌شود همگام‌سازی نشده‌اند..SH "همچنین ببینید (SEE ALSO)" grep(1), printf(3), Encode::Supported(pm), Term::ANSIColor(pm)