نام (NAME)

lexgrog - تجزیه اطلاعات سرآیند در صفحات راهنما

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

lexgrog [-m|-c] [-dfw?V] [-E encoding] file ...

توضیحات (DESCRIPTION)

برنامهٔ lexgrog یک پیاده‌سازی از ابزار سنتی “groff guess” در lex است. این ابزار فهرست فایل‌ها را در خط فرمان خود به عنوان فایل‌های منبع صفحه راهنما یا صفحات پیش‌قالب‌بندی‌شدهٔ “cat” می‌خواند، و نام و شرح آن‌ها را همان‌گونه که توسط apropos و whatis استفاده می‌شود، فهرست فیلترهای پیش‌پردازشی مورد نیاز صفحه راهنما پیش از ارسال به nroff یا troff، یا هر دو را نمایش می‌دهد.

اگر ورودی آن قالب‌بندی نامناسبی داشته باشد، lexgrog عبارت “parse failed” را چاپ می‌کند؛ این ویژگی ممکن است برای برنامه‌های خارجی که نیاز به بررسی صحت صفحات راهنما دارند مفید باشد. اگر یکی از فایل‌های ورودی lexgrog علامت “-” باشد، از ورودی استاندارد می‌خواند؛ اگر هر یک از فایل‌های ورودی فشرده باشد، نسخهٔ از فشرده خارج‌شدهٔ آن به طور خودکار خوانده خواهد شد.

گزینه‌ها (OPTIONS)

-d, --debug

چاپ اطلاعات اشکال‌زدایی.

-m, --man

تجزیه ورودی به عنوان فایل‌های منبع صفحه راهنما. اگر هیچ‌یک از --man یا --cat مشخص نشده باشد، این حالت پیش‌فرض است.

-c, --cat

تجزیه ورودی به عنوان صفحات راهنمای پیش‌قالب‌بندی‌شده (“cat pages”). گزینه‌های --man و --cat را نمی‌توان به‌طور هم‌زمان استفاده کرد.

-w, --whatis

نمایش نام و شرح از سرآیند صفحه راهنما، همان‌طور که توسط apropos و whatis استفاده می‌شود. اگر هیچ‌یک از --whatis یا --filters مشخص نشده باشد، این حالت پیش‌فرض است.

-f, --filters

نمایش فهرست فیلترهای مورد نیاز برای پیش‌پردازش صفحه راهنما قبل از قالب‌بندی با nroff یا troff.

-E encoding, --encoding encoding

بازنویسی مجموعه نویسه‌های حدس‌زده‌شده برای صفحه به encoding.

-?, --help

چاپ یک پیام راهنما و خروج.

--usage

چاپ پیام کوتاه نحوه استفاده و خروج.

-V, --version

نمایش اطلاعات نسخه.

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

0

اجرای موفقیت‌آمیز برنامه.

1

خطای استفاده.

2

برنامهٔ lexgrog در تجزیه یک یا چند فایل ورودی خود ناموفق بود.

مثال‌ها (EXAMPLES)

$ lexgrog man.1
man.1: "man - an interface to the system reference manuals"
$ lexgrog -fw man.1
man.1 (t): "man - an interface to the system reference manuals"
$ lexgrog -c whatis.cat1
whatis.cat1: "whatis - display manual page descriptions"
$ lexgrog broken.1
broken.1: parse failed

تجزیه چهرهنما (WHATIS PARSING)

برنامهٔ mandb (که از همان کد lexgrog استفاده می‌کند) بخش NAME را در بالای هر صفحه راهنما با هدف یافتن نام‌ها و توصیفات قابلیت‌های مستندشده در هر یک، تجزیه می‌کند. اگرچه تجزیه‌کننده بسیار منعطف است، زیرا باید با چندین شکل متفاوت که در طول تاریخ مورد استفاده قرار گرفته‌اند سازگار باشد، اما ممکن است گاهی در استخراج اطلاعات مورد نیاز با شکست مواجه شود.

هنگام استفاده از مجموعه ماکروهای سنتی man، یک بخش NAME صحیح شبیه به این خواهد بود:

.SH NAME
foo \- program to do something

برخی از صفحه‌بندهای راهنما نیازمند این هستند که عبارت ‘\-’ دقیقاً به صورت نمایش‌داده‌شده باشد؛ mandb انعطاف بیشتری دارد، اما برای سازگاری با سایر سیستم‌ها، بهتر است بک‌اسلش حفظ شود.

در سمت چپ، ممکن است چندین نام با کاما از هم جدا شده باشند. نام‌های دارای نویسهٔ فاصله برای جلوگیری از رفتارهای غیرعادی در بخش‌های NAME نادرست، نادیده گرفته می‌شوند. متن سمت راست آزاد است و می‌تواند در چندین خط پخش شود. اگر چندین ویژگی با توصیف‌های متفاوت در یک صفحه راهنما مستند شده باشند، از قالب زیر استفاده می‌شود:

.SH NAME
foo, bar \- programs to do something
.br
baz \- program to do nothing

(به جای ماکروی شکست خط .br می‌توان از ماکرویی که پاراگراف جدید را شروع می‌کند، مانند .PP استفاده کرد.)

هنگام استفاده از مجموعه ماکروهای برگرفته از BSD یعنی mdoc، یک بخش NAME صحیح شبیه به این خواهد بود:

.Sh NAME
.Nm foo
.Nd program to do something

چند دلیل متداول برای ناموفق بودن تجزیه چهره‌نما (whatis) وجود دارد. گاهی نویسندگان صفحات راهنما عبارت ‘.SH NAME’ را با ‘.SH MYPROGRAM’ جایگزین می‌کنند، و در نتیجه mandb نمی‌تواند بخشی را که باید اطلاعات مورد نیازش را از آن استخراج کند بیابد. گاهی نویسندگان بخش NAME را قرار می‌دهند، اما به جای ‘name \- description’ متنی آزاد در آن قرار می‌دهند. با این وجود، هر دستوری که مشابه موارد فوق باشد باید پذیرفته شود.

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

apropos(1), man(1), whatis(1), mandb(8)

نکات (NOTES)

lexgrog تلاش می‌کند تا فایل‌های حاوی درخواست‌های .so را تجزیه کند، اما تنها در صورتی قادر به انجام صحیح این کار خواهد بود که فایل‌ها به درستی در ساختار سلسله‌مراتبی صفحات راهنما نصب شده باشند.

نویسندگان (AUTHORS)

کد استفاده شده توسط lexgrog جهت پویش صفحات راهنما توسط افراد زیر نوشته شده است:

Wilf. (G.Wilford@ee.surrey.ac.uk).
Fabrizio Polacco (fpolacco@debian.org).
Colin Watson (cjwatson@debian.org).

کالین واتسون (Colin Watson) نسخهٔ کنونی رابط خط فرمان و همچنین این صفحه راهنما را نوشته است.

گزارش اشکال (REPORTING BUGS)

https://gitlab.com/man-db/man-db/-/issues
https://savannah.nongnu.org/bugs/?group=man-db