'\" t
.\"     Title: pdfgrep
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 03/15/2024
.\"    Manual: Pdfgrep Manual
.\"    Source: Pdfgrep 2.1.2
.\"  Language: Persian
.\"
.TH "PDFGREP" "1" "03/15/2024" "Pdfgrep 2\&.1\&.2" "Pdfgrep Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
pdfgrep \- جستجوی عبارات باقاعده در فایل‌های PDF
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBpdfgrep\fR [\fIOPTION\fR\&...] \fIPATTERN\fR \fIFILE\fR\&...
\fBpdfgrep\fR [\fIOPTION\fR\&...] {\fB\-e\fR \fIPATTERN\fR|\fB\-f\fR \fIFILE\fR}\&... \fIFILE\fR\&...
\fBpdfgrep\fR [\fIOPTION\fR\&...] \fB\-r\fR|\fB\-R\fR \fIPATTERN\fR [\fIFILE\fR|\fIDIR\fR\&...]
\fBpdfgrep\fR [\fIOPTION\fR\&...] \fB\-r\fR|\fB\-R\fR {\fB\-e\fR \fIPATTERN\fR|\fB\-f\fR \fIFILE\fR}\&... [\fIFILE\fR|\fIDIR\fR\&...]
.fi
.SH "توضیحات (DESCRIPTION)"
.sp
در هر \fIFILE\fR از نوع PDF به دنبال \fIPATTERN\fR می‌گردد و خطوط منطبق را چاپ می‌کند\&. به‌طور پیش‌فرض، \fIPATTERN\fR یک عبارت باقاعده گسترش‌یافته (extended regular expression) است\&.
.sp
برنامهٔ \fBpdfgrep\fR تلاش می‌کند تا حد امکان با \fBGNU grep\fR سازگار باشد، با این تفاوت که برخی تمایزها و گزینه‌های اضافی مختص به PDF دارد\&. از همه قابل‌توجه‌تر اینکه گزینهٔ \fB\-n\fR به جای شماره خط، شماره صفحه را چاپ می‌کند\&.
.SH "گزینه‌ها (OPTIONS)"
.SS "اطلاعات عمومی (General Information)"
.PP
\fB\-\-help\fR
.RS 4
خلاصه‌ای کوتاه از گزینه‌ها را چاپ می‌کند\&.
.RE
.PP
\fB\-V\fR, \fB\-\-version\fR
.RS 4
اطلاعات نسخه را نمایش می‌دهد\&.
.RE
.SS "تفسیر الگو (Pattern Interpretation)"
.PP
\fB\-F\fR, \fB\-\-fixed\-strings\fR
.RS 4
الگوی
\fIPATTERN\fR
را به عنوان فهرستی از رشته‌های ثابت که با خط جدید جدا شده‌اند تفسیر می‌کند که هر یک از آن‌ها می‌تواند تطابق داده شود\&.
.RE
.PP
\fB\-P\fR, \fB\-\-perl\-regexp\fR
.RS 4
الگوی
\fIPATTERN\fR
را به عنوان یک عبارت باقاعده سازگار با پرل (PCRE2) تفسیر می‌کند\&. برای یک مرور اجمالی،
\fIpcre2syntax\fR(3) را ببینید\&.
.RE
.SS "کنترل تطابق (Matching Control)"
.PP
\fB\-e\fR \fIPATTERN\fR, \fB\-\-regexp=\fR\fIPATTERN\fR
.RS 4
از
\fIPATTERN\fR
به عنوان الگوی جستجو استفاده می‌کند\&. اگر این گزینه چندین بار مشخص شود یا با
\fB\-\-file\fR
ترکیب گردد، همهٔ الگوها به نوبت امتحان می‌شوند تا زمانی که یکی از آن‌ها تطابق یابد\&.
.RE
.PP
\fB\-f\fR \fIFILE\fR, \fB\-\-file=\fR\fIFILE\fR
.RS 4
الگوها را از
\fIFILE\fR،
یک مورد در هر خط، می‌خواند\&. اگر
\fIFILE\fR
حاوی چندین الگو باشد یا این گزینه چندین بار اعمال شده یا با
\fB\-e\fR
ترکیب شود، همهٔ الگوها به نوبت امتحان می‌شوند تا یکی از آن‌ها مطابقت یابد\&. یک فهرست الگوی خالی با هیچ چیز مطابقت نخواهد داشت\&.
.RE
.PP
\fB\-i\fR, \fB\-\-ignore\-case\fR
.RS 4
تمایز بین حروف بزرگ و کوچک را هم در
\fIPATTERN\fR
و هم در فایل‌های ورودی نادیده می‌گیرد\&.
.RE.SS "کنترل عمومی خروجی (General Output Control)"
.PP
\fB\-c\fR, \fB\-\-count\fR
.RS 4
خروجی عادی را بازداری می‌کند\&. به‌جای آن تعداد تطابق‌ها را برای هر فایل ورودی چاپ می‌کند\&. توجه داشته باشید که برخلاف grep، چندین تطابق در همان صفحه به‌صورت جداگانه شمارش خواهند شد\&.
.RE
.PP
\fB\-p\fR, \fB\-\-page\-count\fR
.RS 4
مانند
\fB\-c\fR، اما تعداد تطابق‌ها را در هر صفحه چاپ می‌کند\&. به‌طور ضمنی
\fB\-n\fR
را فعال می‌کند\&.
.RE
.PP
\fB\-\-color\fR \fIWHEN\fR
.RS 4
نام‌های فایل، شماره‌های صفحه و متن تطبیق‌یافته را با توالی‌های گریز احاطه می‌کند تا در ترمینال به‌صورت رنگی نمایش داده شوند\&.
\fIWHEN\fR
می‌تواند یکی از مقادیر زیر باشد:
.TS
tab(:);
lt lt
lt lt
lt lt.
T{
\fBalways\fR
T}:T{
همیشه از رنگ‌ها استفاده کن، حتی زمانی که stdout یک ترمینال نباشد\&.
T}
T{
\fBnever\fR
T}:T{
از رنگ‌ها استفاده نکن\&.
T}
T{
\fBauto\fR
T}:T{
تنها زمانی از رنگ‌ها استفاده کن که stdout یک ترمینال باشد (این حالت پیش‌فرض است)\&.
T}
.TE
.sp 1
.RE
.PP
\fB\-L\fR, \fB\-\-files\-without\-match\fR
.RS 4
خروجی عادی را بازداری می‌کند\&. به‌جای آن نام هر فایل ورودی را که حاوی هیچ تطابقی نیست چاپ می‌کند\&. این گزینه به‌خوبی با
\fB\-Z\fR
کار می‌کند، اما در صورت مشخص شدن
\fB\-L\fR،
بسیاری از گزینه‌های خروجی دیگر مانند
\fB\-n\fR
یا
\fB\-c\fR
نادیده گرفته می‌شوند\&.
.RE
.PP
\fB\-l\fR, \fB\-\-files\-with\-matches\fR
.RS 4
خروجی عادی را بازداری می‌کند\&. به‌جای آن نام هر فایل ورودی را که حاوی تطابق است چاپ می‌کند\&. این گزینه به‌خوبی با
\fB\-Z\fR
کار می‌کند، اما در صورت مشخص شدن
\fB\-l\fR،
بسیاری از گزینه‌های خروجی دیگر مانند
\fB\-n\fR
یا
\fB\-c\fR
نادیده گرفته می‌شوند\&.
.RE
.PP
\fB\-m\fR, \fB\-\-max\-count\fR \fINUM\fR
.RS 4
خواندن یک فایل را پس از
\fINUM\fR
تطابق متوقف می‌کند\&. هنگامی که گزینه \-c یا \-\-count نیز استفاده شود، pdfgrep عددی بزرگ‌تر از
\fINUM\fR
را در خروجی چاپ نخواهد کرد\&.
.RE
.PP
\fB\-o\fR, \fB\-\-only\-matching\fR
.RS 4
تنها بخش تطبیق‌یافته از یک سطر را بدون بافت پیرامونی آن چاپ می‌کند\&.
.RE
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
تمام خروجی‌های عادی به stdout را بازداری می‌کند\&. در صورت یافتن تطابق، حتی در صورت بروز خطا، بلافاصله با وضعیت خروج 0 خارج می‌شود\&. اگر تنها وجود تطابق‌ها برای شما اهمیت دارد، نه تعداد یا محتوای آن‌ها، از این گزینه استفاده کنید\&.
.RE.SS "کنترل پیشوند سطر"
.PP
\fB\-H\fR, \fB\-\-with\-filename\fR
.RS 4
چاپ نام فایل برای هر تطابق\&. این تنظیم پیش‌فرض در حالتی است که بیش از یک فایل برای جست‌وجو وجود داشته باشد\&.
.RE
.PP
\fB\-h\fR, \fB\-\-no\-filename\fR
.RS 4
جلوگیری از درج نام فایل به عنوان پیشوند در خروجی\&. این تنظیم پیش‌فرض در حالتی است که تنها یک فایل برای جست‌وجو وجود داشته باشد\&.
.RE
.PP
\fB\-n\fR, \fB\-\-page\-number\fR[=\fITYPE\fR]
.RS 4
افزودن شمارهٔ صفحه‌ای که تطابق در آن یافت شده به عنوان پیشوند به هر تطابق\&.
.sp
آرگومان اختیاری
\fITYPE\fR
نحوهٔ تعیین شماره‌های صفحه را کنترل می‌کند\&. در صورت استفاده، می‌تواند یکی از مقادیر زیر باشد:
.TS
tab(:);
lt lt
lt lt.
T{
\fBindex\fR
T}:T{
اندیس صفحه در PDF، شروع از ۱ برای صفحهٔ نخست\&. این مقدار پیش‌فرض است\&.
T}
T{
\fBlabel\fR
T}:T{
برچسب صفحهٔ PDF\&. این مقدار می‌تواند یک رشتهٔ دلخواه برای هر صفحه باشد که توسط سازندهٔ PDF تنظیم شده است (برای نمونه، ارقام رومی برای چند صفحهٔ اول)\&.
T}
.TE
.sp 1
.RE
.PP
\fB\-Z\fR, \fB\-\-null\fR
.RS 4
خروجی دادن یک بایت تهی (که در
\fINUL\fR
در ASCII و \*(Aq\e0\*(Aq در C نامیده می‌شود) به جای دونقطه‌ای که معمولاً نام فایل را از بقیهٔ سطر جدا می‌کند\&. این گزینه خروجی را در صورت وجود دونقطه، فاصله یا خطوط جدید در نام فایل بدون ابهام می‌سازد\&. می‌تواند در ترکیب با دستورهایی مانند
\fIxargs\ \&\-0\fR
یا
\fIperl\ \&\-0\fR
استفاده شود\&.
.RE
.PP
\fB\-\-match\-prefix\-separator\fR \fISEP\fR
.RS 4
تغییر دونقطه‌ای که برای جداسازی نام فایل، شماره سطر و متن در خروجی استفاده می‌شود به
\fISEP\fR، که می‌تواند یک رشتهٔ دلخواه باشد\&. این گزینه زمانی که نام‌های فایل حاوی دونقطه باشند مفید است، اما تنها برای کاربردهای تعاملی توصیه می‌شود\&. برای اسکریپت‌نویسی، باید از
\fB\-\-null\fR
استفاده شود\&.
.RE
.SS "کنترل زمینه"
.PP
\fB\-A\fR \fINUM\fR, \fB\-\-after\-context=NUM\fR
.RS 4
چاپ
\fINUM\fR
سطر از زمینه پس از سطرهای منطبق\&. گروه‌های پیوستهٔ تطابق‌ها با سطری حاوی
\fB\-\-\fR
از هم جدا می‌شوند\&. با
\fB\-o\fR، این گزینه هیچ اثری ندارد\&.
.RE
.PP
\fB\-B\fR \fINUM\fR, \fB\-\-before\-context=NUM\fR
.RS 4
چاپ
\fINUM\fR
سطر از زمینه پیش از سطرهای منطبق\&. گروه‌های پیوستهٔ تطابق‌ها با سطری حاوی
\fB\-\-\fR
از هم جدا می‌شوند\&. با
\fB\-o\fR، این گزینه هیچ اثری ندارد\&.
.RE
.PP
\fB\-C\fR \fINUM\fR, \fB\-\-context=NUM\fR
.RS 4
چاپ
\fINUM\fR
سطر از زمینه پیش و پس از سطرهای منطبق\&. گروه‌های پیوستهٔ تطابق‌ها با سطری حاوی
\fB\-\-\fR
از هم جدا می‌شوند\&. با
\fB\-o\fR، این گزینه هیچ اثری ندارد\&.
.RE.SS "انتخاب فایل (File Selection)"
.PP
\fB\-r\fR, \fB\-\-recursive\fR
.RS 4
جستجوی بازگشتی در تمام فایل‌های زیر هر دایرکتوری (محدودشده توسط
\fB\-\-include\fR
و
\fB\-\-exclude\fR)؛
پیوندهای نمادین (symlinks) تنها در صورتی دنبال می‌شوند که در خط فرمان مشخص شده باشند\&.
.RE
.PP
\fB\-R\fR, \fB\-\-dereference\-recursive\fR
.RS 4
همانند
\fB\-r\fR،
اما تمام پیوندهای نمادین را دنبال می‌کند\&.
.RE
.PP
\fB\-\-exclude=\fR\fIGLOB\fR
.RS 4
نادیده‌گرفتن فایل‌هایی که نام پایه (base name) آن‌ها با
\fIGLOB\fR
تطابق دارد\&. برای نویسه‌های عامی که می‌توانید استفاده کنید به
\fIglob\fR(7)
مراجعه کنید\&. می‌توانید از این گزینه چندین بار برای مستثنی‌کردن الگوهای بیشتر استفاده کنید\&. این گزینه بر
\fB\-\-include\fR
اولویت دارد\&. توجه داشته باشید که include و exclude تنها برای فایل‌های یافته‌شده از طریق
\fB\-\-recursive\fR
اعمال می‌شوند و بر فهرست آرگومان‌ها اثر ندارند\&.
.RE
.PP
\fB\-\-include=\fR\fIGLOB\fR
.RS 4
فقط جستجوی فایل‌هایی که نام پایه آن‌ها با
\fIGLOB\fR
تطابق دارد\&. برای جزئیات به
\fB\-\-exclude\fR
مراجعه کنید\&. مقدار پیش‌فرض
\fI*\&.[Pp][Dd][Ff]\fR
است\&.
.RE
.SS "سایر گزینه‌ها (Other Options)"
.PP
\fB\-\-cache\fR
.RS 4
استفاده از حافظه موقت (cache) برای متن پردازش‌شده جهت افزایش سرعت عملیات روی فایل‌های حجیم\&.
.RE
.PP
\fB\-\-password=\fR\fIPASSWORD\fR
.RS 4
استفاده از PASSWORD برای رمزگشایی فایل‌های PDF\&. می‌تواند چندین بار مشخص شود؛ تمام گذرواژه‌ها روی تمامی PDFها آزمایش خواهند شد\&.
\fBتوجه\fR
داشته باشید که این گذرواژه در تاریخچه فرمان‌ها و در خروجی
\fIps\fR(1)
نمایش داده خواهد شد\&. بنابراین در صورتی که امنیت
\fIPASSWORD\fR
اهمیت دارد، لطفاً از این گزینه استفاده نکنید\&.
.RE
.PP
\fB\-\-page\-range=\fR\fIRANGE\fR
.RS 4
محدود کردن جستجو به مجموعه‌ای مشخص از صفحه‌ها\&.
\fIRANGE\fR
فهرستی جداشده با کاما از شماره یک صفحه یا عبارت بازه‌ای به شکل
PAGE1\-PAGE2
است\&. مثال:
2\-3,5,7\-10\&.
.RE
.PP
\fB\-\-debug\fR
.RS 4
فعال‌سازی خروجی اشکال‌زدایی (debug)\&.
\fBنکته\fR:
به دلیل محدودیت‌های poppler قبل از نسخه 0\&.30\&.0، هنگام استفاده از چنین نسخه‌ای از poppler، برخی از خروجی‌های اشکال‌زدایی حتی بدون
\fB\-\-debug\fR
نیز چاپ می‌شوند\&.
.RE
.PP
\fB\-\-warn\-empty\fR
.RS 4
چاپ هشدار در
\fIstderr\fR
اگر یک فایل PDF حاوی هیچ متن قابل جستجویی نباشد\&. این حالت برای PDFهایی رخ می‌دهد که تنها از تصویر تشکیل شده‌اند، مانند اسناد اسکن‌شده\&.
.RE
.PP
\fB\-\-unac\fR
.RS 4
حذف اکسان‌ها، اعراب و ادغام حروف (ligatures) از هر دو الگوی جستجو و اسناد PDF\&. این گزینه زمانی مفید است که می‌خواهید کلمه‌ای حاوی «ae» را جستجو کنید، اما در PDF به جای آن از نویسه تکی «æ» استفاده شده است\&. برای جزئیات به
\fBunac(3)\fR
و
\fBunaccent(1)\fR
مراجعه کنید\&.
.sp
\fBاین گزینه آزمایشی است و تنها در صورتی در دسترس است که pdfgrep با پشتیبانی از unac کامپایل شده باشد\&.\fR
.RE.SH "وضعیت خروج (EXIT STATUS)"
.sp
به‌طور معمول، اگر دست‌کم یک مورد منطبق پیدا شود وضعیت خروج 0 است، اگر هیچ موردی یافت نشود 1 است و در صورت بروز خطا 2 است\&. اما اگر گزینهٔ \fB\-\-quiet\fR یا \fB\-q\fR به کار رود و موردی پیدا شده باشد، \fBpdfgrep\fR صرف‌نظر از خطاها 0 را برمی‌گرداند\&.
.SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)"
.sp
رفتار \fBpdfgrep\fR تحت تأثیر متغیر محیطی زیر قرار می‌گیرد\&.
.PP
\fBGREP_COLORS\fR
.RS 4
رنگ‌ها و دیگر ویژگی‌های به‌کاررفته برای برجسته‌سازی بخش‌های گوناگون خروجی را مشخص می‌کند\&. ساختار و مقادیر آن مانند
\fBGREP_COLORS\fR
در
\fBgrep\fR
است\&. برای جزئیات بیشتر به
\fIgrep\fR(1)
مراجعه کنید\&. در حال حاضر تنها قابلیت‌های
\fBmt\fR،
\fBms\fR،
\fBmc\fR،
\fBfn\fR،
\fBln\fR
و
\fBse\fR
توسط
\fBpdfgrep\fR
استفاده می‌شوند، که در این میان
\fBmt\fR،
\fBms\fR
و
\fBmc\fR
تأثیر یکسانی دارند\&.
.RE
.SH "فایل‌ها (FILES)"
.PP
\fB${XDG_CACHE_HOME}/pdfgrep/\fR*
.RS 4
فایل‌های حافظهٔ موقت (کَش) که هنگام فعال بودن
\fB\-\-cache\fR
نوشته و استفاده می‌شوند\&. حداکثر ۲۰۰ مدخل کَش با قدمت بیش از یک روز نگهداری می‌شوند\&.
.RE
.SH "مثال‌ها (EXAMPLES)"
.PP
\fBچاپ ده سطر نخست منطبق با \fR\fB\fIpattern\fR\fR\fB و چاپ شمارهٔ صفحهٔ آن‌ها:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
pdfgrep \-n \-\-max\-count 10 pattern foo\&.pdf
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBجست‌وجوی بازگشتی همهٔ فایل‌های \&.pdf که نام آن‌ها با \fR\fB\fIfoo\fR\fR\fB آغاز می‌شود در دایرکتوری جاری:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
pdfgrep \-r \-\-include "foo*\&.pdf" pattern
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBجست‌وجوی همهٔ فایل‌های PDF در دایرکتوری جاری برای \fR\fB\fIfoo\fR\fR\fB که شامل \fR\fB\fIbar\fR\fR\fB نیز باشند:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
pdfgrep \-Z \-\-files\-with\-matches "bar" *\&.pdf | xargs \-0 pdfgrep \-H foo
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBجست‌وجوی بازگشتی همهٔ فایل‌های \&.pdf با اندازهٔ کوچک‌تر از 12M در دایرکتوری جاری:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
find \&. \-name "*\&.pdf" \-size \-12M \-print0 | xargs \-0 pdfgrep pattern
.fi
.if n \{\
.RE
.\}
.sp
توجه داشته باشید که برخلاف مثال‌های پیشین، این کار را نمی‌شد تنها با pdfgrep انجام داد، بلکه باید از ابزارهای یونیکس
\fBfind(1)\fR
و
\fBxargs(1)\fR
استفاده می‌شد\&. دلیل این امر آن است که pdfgrep خودش گزینه‌هایی برای مستثنی کردن فایل‌ها بر اساس اندازه‌شان ندارد\&. اما همان‌طور که می‌بینید، نیازی هم به آن ندارد!
.RE
.PP
\fBجست‌وجوی همهٔ فایل‌های \&.pdf در دایرکتوری جاری به‌صورت موازی روی یک پردازندهٔ چند‌هسته‌ای\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
find \&. \-name "*\&.pdf" \-print0 | parallel \-q0 pdfgrep \-H foobar
.fi
.if n \{\
.RE
.\}
.sp
این دستور از GNU
\fBparallel(1)\fR
علاوه بر
\fBfind(1)\fR
برای جست‌وجوی چندین فایل به‌طور موازی روی پردازنده‌های چند‌هسته‌ای استفاده می‌کند\&. در صورتی که چندین فایل برای جست‌وجو و یک پردازنده با ظرفیت استفاده‌نشده داشته باشید، انجام این کار می‌تواند به بهبود سرعت قابل‌توجهی منجر شود\&.
.RE.SH "گزارش باگ‌ها (BUGS)"
.SS "گزارش باگ‌ها"
.sp
باگ‌ها را می‌توان به فهرست پستی (pdfgrep\-users@pdfgrep\&.org) یا به ردیاب باگ در gitlab (https://gitlab\&.com/pdfgrep/pdfgrep/issues) گزارش کرد\&.
.SH "نویسندگان (AUTHORS)"
.sp
\fBpdfgrep\fR توسط Hans\-Peter Deifel نگهداری می‌شود\&.
.sp
برای فهرست کامل مشارکت‌کنندگان، فایل \fIAUTHORS\fR را در کد منبع ببینید\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
grep(1), pcre2(3), regex(7)
.sp
برای اطلاعات بیشتر، بارگیری‌ها، مخزن git و موارد دیگر، وبگاه pdfgrep به نشانی https://pdfgrep\&.org را مشاهده کنید\&.