.\" See section COPYING for copyright and redistribution information.
.TH ETAGS 1 "2025-03-22" "GNU Tools" "GNU"
.de BP
.sp
.ti -.2i
\(**
..

.SH "نام (NAME)"
etags \- ایجاد فایل برچسب برای ویرایشگرهای Emacs و vi
.SH "خلاصه دستور (SYNOPSIS)"
.hy 0
.na
\fBetags\fP [\|\-aCDGIQRVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|]
.if n .br
[\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|]
[\|\-\-parse\-stdin=\fIfile\fP\|]
.br
[\|\-\-append\|] [\|\-\-no\-defines\|] [\|\-\-globals\|]
[\|\-\-no\-globals\|] [\|\-\-no\-line\-directive\|] [\|\-\-include=\fIfile\fP\|]
[\|\-\-ignore\-indentation\|] [\|\-\-language=\fIlanguage\fP\|]
[\|\-\-members\|] [\|\-\-no\-members\|] [\|\-\-output=\fItagfile\fP\|]
[\|\-\-class\-qualify\|]
[\|\-\-regex=\fIregexp\fP\|] [\|\-\-no\-regex\|]
[\|\-\-no\-fallback\-lang\|] [\|\-\-fallback\-lang\|]
[\|\-\-no\-empty\-file\-entries\|] [\|\-\-empty\-file\-entries\|]
[\|\-\-help\|] [\|\-\-version\|]
\fIfile\fP .\|.\|.

\fBetags \-\-ctags\fP [\|\-aCdgIQRVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|]
.if n .br
[\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|]
[\|\-\-parse\-stdin=\fIfile\fP\|]
.br
[\|\-\-append\|] [\|\-\-backward\-search\|]
[\|\-\-cxref\|] [\|\-\-no\-defines\|] [\|\-\-globals\|]
[\|\-\-no\-globals\|] [\|\-\-no\-line\-directive\|] [\|\-\-ignore\-indentation\|]
[\|\-\-language=\fIlanguage\fP\|] [\|\-\-members\|] [\|\-\-no\-members\|]
[\|\-\-class\-qualify\|]
[\|\-\-output=\fItagfile\fP\|] [\|\-\-regex=\fIregexp\fP\|]
[\|\-\-update\|]
[\|\-\-help\|] [\|\-\-version\|]
\fIfile\fP .\|.\|.
.ad b
.hy 1
.SH "توضیحات (DESCRIPTION)"
برنامه
.B etags
برای ایجاد یک فایل جدول برچسب (tag table)، در قالبی قابل فهم برای
.BR emacs ( 1 )\c
\& استفاده می‌شود؛ چنانچه نخستین آرگومان، گزینه منسوخ‌شده
.B \-\-ctags
باشد، برنامه در عوض جدول مشابهی در قالبی قابل فهم برای
.BR vi ( 1 )\c
\& ایجاد می‌کند. این برنامه نحو زبان‌های C، Objective C، C++، Java، Fortran، Ada، Cobol، Erlang، Forth، Go، HTML، LaTeX، Emacs Lisp/Common Lisp، Lua، Makefile، Mercury، Pascal، Perl، Ruby، Rust، PHP، PostScript، Python، Prolog، Scheme و بیشتر نحوهای شبیه به اسمبلی را می‌شناسد.
.PP
این برنامه فایل‌های مشخص‌شده در خط فرمان را می‌خواند و یک جدول برچسب (پیش‌فرض:
.BR TAGS ،
یا در صورت استفاده از
.BR \-\-ctags ،
فایل
.BR tags )
در دایرکتوری کاری جاری می‌نویسد.
فایل‌هایی که با نام‌های نسبی مشخص شده‌اند، در جدول برچسب با نام‌های فایلی نسبت به دایرکتوری محل استقرار جدول برچسب ثبت می‌شوند. با این حال، اگر جدول برچسب در /dev باشد یا همان خروجی استاندارد باشد، نام فایل‌ها نسبت به دایرکتوری کاری ثبت خواهند شد.
فایل‌هایی که با نام‌های مطلق مشخص شده‌اند، با نام‌های مطلق ثبت می‌شوند. فایل‌های تولیدشده از یک فایل منبع \(en مانند یک فایل C تولیدشده از یک فایل منبع Cweb \(en با نام فایل منبع ثبت خواهند شد.
.PP
فایل‌های فشرده‌شده با استفاده از gzip، bzip2، xz و zstd پشتیبانی می‌شوند.
.PP
برنامه‌ها زبان مورد استفاده در یک فایل ورودی را بر اساس نام فایل و محتویات آن تشخیص می‌دهند. از سوییچ
.B \-\-language
می‌توان برای اجبار در تجزیه نام‌های فایلی که پس از این سوییچ می‌آیند بر اساس زبان ارائه‌شده استفاده کرد، که بر حدس‌های مبتنی بر پسوند نام فایل اولویت دارد.
.SH "گزینه‌ها (OPTIONS)"
برخی از گزینه‌ها تنها برای فایل‌های برچسب به سبک
.B vi
که با گزینه
.B \-\-ctags
تولید می‌شوند معنا دارند؛ در غیر این صورت نادیده گرفته می‌شوند.
این برنامه‌ها مخفف‌های بدون ابهام را برای نام‌های طولانی گزینه‌ها می‌پذیرند.
.TP
.B \-a, \-\-append
افزودن به انتهای فایل برچسب موجود. (برای فایل‌های برچسب با قالب
.BR vi ،
همچنین
.B \-\-update
را ببینید.)
.TP
.B \-B, \-\-backward\-search
فایل‌های برچسب نوشته‌شده در قالبی که
.B vi
انتظار دارد شامل دستورالعمل‌های جستجوی عبارت منظم هستند؛ گزینه
.B \-B
آن‌ها را با استفاده از جداکننده \(dq\|\fB?\fP\|\(dq می‌نویسد تا جستجو در فایل‌ها
.I رو به عقب
انجام گیرد. پیش‌فرض، استفاده از جداکننده \(dq\|\fB/\fP\|\(dq برای جستجوی
.I رو به جلو
در فایل‌ها است.
این گزینه تنها در صورت استفاده از
.B \-\-ctags
کاربرد دارد.
.TP
.B \-\-declarations
در C و زبان‌های مشتق‌شده از آن، برای اعلانات توابع برچسب ایجاد می‌کند و برای متغیرهای extern نیز برچسب می‌سازد مگر اینکه از
.B \-\-no\-globals
استفاده شود.
در Lisp، برای اعلانات (defvar foo) برچسب می‌سازد.
در Mercury، اعلانات خط را با \(dq\|\fB:-\fP\|\(dq آغاز می‌کنند و همیشه برچسب‌گذاری می‌شوند. علاوه بر این، این گزینه محمول‌ها یا توابع را در نخستین قواعد بندها، مانند Prolog، برچسب‌گذاری می‌کند.
.TP
.B \-D, \-\-no\-defines
عدم ایجاد مدخل‌های برچسب برای تعاریف ثابت‌های پیش‌پردازنده C و ثابت‌های enum.
در صورتی که فایل‌های هدر زیادی برچسب‌گذاری شوند، این گزینه می‌تواند اندازه فایل برچسب‌ها را بسیار کوچک‌تر کند.
.TP
.B \-\-globals
ایجاد مدخل‌های برچسب برای متغیرهای سراسری در Perl و Makefile. این حالت پیش‌فرض در C و زبان‌های مشتق‌شده از آن است.
.TP
.B \-\-no\-globals
عدم برچسب‌گذاری متغیرهای سراسری در C و زبان‌های مشتق‌شده از آن. به‌طور معمول این گزینه اندازه فایل را به میزان یک چهارم کاهش می‌دهد.
.TP
.B \-\-no\-line\-directive
نادیده گرفتن دستورات پیش‌پردازنده
.B #line
در C و زبان‌های مشتق‌شده از آن. حالت پیش‌فرض این است که این دستورات در نظر گرفته شده و برچسب‌ها به‌گونه‌ای ثبت شوند که گویی فایل اسکن‌شده همان فایلی بوده که در دستور
.B #line
نام برده شده است. این سوییچ هنگامی سودمند است که فایل اصلی نام‌برده‌شده توسط
.B #line
دیگر در دسترس نباشد.
.TP
\fB\-i\fP \fIfile\fP, \fB\-\-include=\fIfile\fP
درج یادداشتی در فایل برچسب که مشخص می‌کند هنگام جستجو برای یک برچسب، پس از بررسی فایل جاری باید فایل برچسب‌های
.I file
نیز بررسی شود. تنها
.B etags
این گزینه را می‌پذیرد.
.TP
.B \-I, \-\-ignore\-indentation
عدم تکیه بر تورفتگی‌ها به اندازه حالت عادی. در حال حاضر، این بدان معناست که فرض نشود یک آکوالاد بسته در ستون نخست، لزوماً آکوالاد پایانی تعریف تابع یا ساختار در C و C++ است. این گزینه برای کدهایی اهمیت دارد که از قراردادهای کدنویسی گنو مبنی بر قرار دادن آکوالادهای سطح بالا در ستون صفر پیروی نمی‌کنند.
.TP
\fB\-l\fP \fIlanguage\fP, \fB\-\-language=\fIlanguage\fP
تجزیه فایل‌های بعدی بر اساس زبان ارائه‌شده. بیش از یک مورد از این گزینه‌ها می‌تواند در میان نام‌های فایل قرار گیرد. برای دریافت فهرستی از زبان‌های موجود و پسوندهای پیش‌فرض نام فایل آن‌ها از
.B \-\-help
استفاده کنید. برای نمونه، از آنجا که هر دو زبان Mercury و Objective-C پسوند فایل یکسان
.I .m
دارند، یک بررسی مبتنی بر محتوا برای تشخیص زبان تلاش می‌کند. اگر این بررسی ناموفق باشد، باید از
\fB\-\-language=\fP\fImercury\fP
یا
\fB\-\-language=\fP\fIobjc\fP
استفاده شود.
زبان \(dqauto\(dq می‌تواند برای بازگرداندن تشخیص خودکار زبان بر پایه نام فایل استفاده شود. زبان \(dqnone\(dq می‌تواند برای غیرفعال کردن کامل تجزیه زبان به کار رود؛ در این صورت تنها تطبیق عبارات منظم انجام خواهد شد (گزینه
.B \-\-regex
را ببینید).
.TP
.B \-\-members
ایجاد مدخل‌های برچسب برای متغیرهایی که عضو ساختارهای شبه‌استراکچر در PHP هستند. این حالت پیش‌فرض برای C و زبان‌های مشتق‌شده از آن است.
.TP
.B \-\-no\-members
عدم برچسب‌گذاری متغیرهای عضو.
.TP
.B \-\-packages\-only
تنها برچسب‌گذاری بسته‌ها در فایل‌های Ada.
.TP
\fB\-\-parse\-stdin=\fIfile\fP
می‌تواند (تنها یک‌بار) به‌جای نام فایل در خط فرمان استفاده شود.
.B etags
از ورودی استاندارد می‌خواند و برچسب‌های تولیدشده را به عنوان برچسب‌های متعلق به فایل
.B FILE
علامت‌گذاری می‌کند.
.TP
\fB\-Q, \-\-class\-qualify\fP
توصیف نام‌های برچسب با نام کلاس آن‌ها در C++، ObjC، Java و Perl. این گزینه نام‌های برچسب را به شکل
\fIclass\fP\fB::\fP\fImember\fP
برای C++ و Perl،
\fIclass\fP\fB(\fP\fIcategory\fP\fB)\fP
برای Objective C، و
\fIclass\fP\fB.\fP\fImember\fP
برای Java تولید می‌کند. برای Objective C، همچنین متدهای کلاسی توصیف‌شده با آرگومان‌هایشان را مانند
\fIfoo\fP\fB:\fP\fIbar\fP\fB:\fP\fIbaz\fP\fB:\fP\fImore\fP
تولید می‌کند.
.TP
\fB\-o\fP \fItagfile\fP, \fB\-\-output=\fItagfile\fP
نام صریح فایل برای جدول برچسب؛ تنها برای
.BR etags ،
نام فایل
.B \-
به معنای خروجی استاندارد است؛ بر مقادیر پیش‌فرض
.B TAGS
یا
.B tags
اولویت دارد. (اما در صورت همراهی با
.B \-v
یا
.B \-x
نادیده گرفته می‌شود.)
.TP
\fB\-r\fP \fIregexp\fP, \fB\-\-regex=\fIregexp\fP

ایجاد برچسب‌ها بر اساس تطبیق عبارت منظم برای فایل‌های پس از این گزینه، افزون بر برچسب‌های ساخته‌شده با تجزیه استاندارد مبتنی بر زبان. می‌تواند آزادانه با نام‌های فایل و گزینه
.B \-R
ترکیب شود. عبارات منظم حالت تجمعی دارند، یعنی هر یک از این گزینه‌ها به موارد قبلی افزوده خواهد شد. عبارات منظم به یکی از شکل‌های زیر هستند:
.br
	[\fB{\fP\fIlanguage\fP\fB}\fP]\fB/\fP\fItagregexp/\fP[\fInameregexp\fP\fB/\fP]\fImodifiers\fP
.br
	\fB@\fP\fIregexfile\fP
.br

که در آن \fItagregexp\fP برای تطبیق برچسب استفاده می‌شود. این عبارت نباید با کاراکترهای بیهوده تطبیق یابد. چنانچه تطبیق به‌گونه‌ای باشد که ناگزیر کاراکترهایی بیش از اندازه مورد نیاز توسط \fItagregexp\fP تطبیق داده شوند، افزودن \fInameregexp\fP برای محدود کردن دامنه برچسب می‌تواند سودمند باشد. گزینه
.B \-\-ctags
عبارات منظم بدون \fInameregexp\fP را نادیده می‌گیرد. نحو عبارات منظم همانند Emacs است، جز اینکه گریزهای بک‌اسلش همانند GNU grep هستند (که به عنوان نمونه به معنای عدم پشتیبانی از shy groupها است)، و
\fB[:ascii:]\fP،
\fB[:multibyte:]\fP،
\fB[:nonascii:]\fP،
\fB[:word:]\fP
و
\fB[:unibyte:]\fP
پشتیبانی نمی‌شوند.
توالی‌های گریز کاراکتری زیر پشتیبانی می‌شوند:
\\a, \\b, \\d, \\e, \\f, \\n, \\r, \\t, \\v
که به‌ترتیب نماینده کاراکترهای اسکی BEL، BS، DEL، ESC، FF، NL، CR، TAB و VT هستند.
.br
بخش \fImodifiers\fP دنباله‌ای از ۰ یا چند کاراکتر از میان موارد زیر است:
\fIi\fP، که به معنای نادیده گرفتن بزرگی و کوچکی حروف در تطبیق است؛
\fIm\fP، که بدان معناست که \fItagregexp\fP به جای خط به خط، با کل محتوای فایل به‌طور یکجا تطبیق داده می‌شود و توالی تطبیق می‌تواند چندین خط را شامل شود؛ و
\fIs\fP، که متضمن \fIm\fP بوده و به این معناست که کاراکتر نقطه در \fItagregexp\fP با کاراکتر خط جدید نیز مطابقت می‌یابد.
.br
جداکننده، که در مثال‌ها
.B /
است، می‌تواند هر کاراکتری غیر از فاصله، تب، آکوالادها و
.B @
باشد. اگر کاراکتر جداکننده در درون عبارت منظم مورد نیاز باشد، باید با قرار دادن
.B \\
پیش از آن، اسکیپ شود.
.br
پیشوند اختیاری
\fB{\fP\fIlanguage\fP\fB}\fP
بدان معناست که برچسب باید تنها برای فایل‌های زبان \fIlanguage\fP ایجاد شده و در غیر این صورت نادیده گرفته شود. این ویژگی به‌ویژه هنگام ذخیره عبارات منظم از پیش تعریف‌شده بسیار در یک فایل مفید است.
.br
در شکل دوم، \fIregexfile\fP نام فایلی است که شامل تعدادی از آرگومان‌های گزینه
\fI\-\-regex=\fP،
هر کدام در یک خط است. خطوطی که با یک فاصله یا تب آغاز می‌شوند، توضیح (comment) تلقی شده و نادیده گرفته می‌شوند.

.br
در اینجا چند مثال آورده شده است. تمام عبارات منظم نقل‌قول شده‌اند تا از تفسیر آن‌ها توسط شل جلوگیری شود.
.br

برچسب‌گذاری ماکروهای DEFVAR در فایل‌های منبع emacs:
.br
\fI\-\-regex='/[ \\t]*DEFVAR_[A-Z_ \\t(]+"\\([^"]+\\)"/'\fP
.\"" This comment is to avoid confusion to Emacs syntax highlighting
.br

برچسب‌گذاری فایل‌های VHDL (این مثال یک خط طولانی منفرد است که به دلایل قالب‌بندی در اینجا شکسته شده است):
.br
\fI\-\-language=none\ \-\-regex='/[\ \\t]*\\(ARCHITECTURE\\|\\
CONFIGURATION\\)\ +[^\ ]*\ +OF/'\ \-\-regex='/[\ \\t]*\\
\\(ATTRIBUTE\\|ENTITY\\|FUNCTION\\|PACKAGE\\(\ BODY\\)?\\
\\|PROCEDURE\\|PROCESS\\|TYPE\\)[\ \\t]+\\([^\ \\t(]+\\)/\\3/'\fP
.br

برچسب‌گذاری فایل‌های Tcl (این مثال پایانی نحوه استفاده از یک \fItagregexp\fP را نشان می‌دهد):
.br
\fI\-\-lang=none \-\-regex='/proc[\ \\t]+\\([^\ \\t]+\\)/\\1/'\fP

.br
یک عبارت منظم می‌تواند با {\fIlang\fP} آغاز شود، که بدین ترتیب تطبیق آن به خطوط فایل‌های زبان مشخص‌شده محدود می‌گردد. برای دریافت فهرستی از زبان‌های شناخته‌شده از
.B etags \-\-help
استفاده کنید. این ویژگی به‌ویژه در داخل
\fBفایل‌های عبارات منظم (regex files)\fP
سودمند است. یک فایل عبارت منظم حاوی یک عبارت منظم در هر خط است. خطوط خالی و خطوطی که با فاصله یا تب آغاز می‌شوند نادیده گرفته می‌شوند. خطوطی که با @ شروع می‌شوند ارجاعاتی به فایل‌های عبارت منظمی هستند که نام آن‌ها پس از علامت @ می‌آید. سایر خطوط به عنوان عبارات منظم مانند موارد پس از
.B \-\-regex
در نظر گرفته می‌شوند.
.br
برای نمونه، دستور
.br
\fIetags \-\-regex=@regex.file *.c\fP
.br
عبارات منظم موجود در فایل regex.file را می‌خواند.
.TP
.B \-R, \-\-no\-regex
عدم انجام تطبیق عبارت منظم بیشتر بر روی فایل‌های بعدی. می‌تواند آزادانه با نام‌های فایل و گزینه
.B \-\-regex
ترکیب شود.
.TP
\fB\-\-fallback\-lang\fP
اگر زبان فایلی قابل تشخیص نباشد، تلاش می‌کند آن را به عنوان Fortran و C/C++ تجزیه کند. این حالت پیش‌فرض است.
.TP
\fB\-\-no\-fallback\-lang\fP
عدم استفاده از Fortran و C/C++ به عنوان جایگزین برای فایل‌هایی که زبان آن‌ها قابل تشخیص نیست.
.TP
\fB\-\-empty\-file\-entries\fP
تولید مدخل‌های فایل برای فایل‌های بدون برچسب. این حالت پیش‌فرض است.
.TP
\fB\-\-no\-empty\-file\-entries\fP
عدم ایجاد مدخل‌های فایل در خروجی برای فایل‌های بدون برچسب.
.TP
.B \-u, \-\-update
به‌روزرسانی مدخل‌های برچسب برای
.I فایل‌های
مشخص‌شده در خط فرمان، بدون تغییر در مدخل‌های برچسب سایر فایل‌ها. در حال حاضر، این قابلیت با حذف مدخل‌های موجود برای فایل‌های ارائه‌شده و سپس بازنویسی مدخل‌های جدید در انتهای فایل برچسب‌ها پیاده‌سازی شده است. معمولاً ساخت مجدد کل فایل برچسب‌ها سریع‌تر از استفاده از این گزینه است. این گزینه تنها در صورت استفاده از
.B \-\-ctags
کاربرد دارد.
.TP
.B \-v, \-\-vgrind
به‌جای تولید یک فایل برچسب، نمایه (در قالب
.BR vgrind )
را در خروجی استاندارد می‌نویسد. این گزینه تنها در صورت استفاده از
.B \-\-ctags
کاربرد دارد.
.TP
.B \-x, \-\-cxref
به‌جای تولید یک فایل برچسب، ارجاع متقابل (در قالب
.BR cxref )
را در خروجی استاندارد می‌نویسد. این گزینه تنها در صورت استفاده از
.B \-\-ctags
کاربرد دارد.
.TP
.B \-h, \-H, \-\-help
چاپ اطلاعات راهنمای استفاده. در صورت همراهی با یک یا چند مورد از
\-\-language=LANG
اطلاعات تفصیلی درباره چگونگی ایجاد برچسب‌ها برای زبان LANG چاپ می‌شود.
.TP
.B \-V, \-\-version
چاپ نسخه جاری برنامه (مشابه نسخه emacs که
.B etags
همراه با آن منتشر شده است).

.SH "همچنین ببینید (SEE ALSO)"
مدخل \(dq\|\fBemacs\fP\|\(dq در \fBinfo\fP؛ \fIGNU Emacs Manual\fP، اثر ریچارد استالمن (Richard Stallman).
.br
.BR cxref ( 1 ),
.BR emacs ( 1 ),
.BR vgrind ( 1 ),
.BR vi ( 1 ).

.SH "کپی‌رایت و تکثیر (COPYING)"
حق نشر ۱۹۹۲، ۱۹۹۹، ۲۰۰۱\(en۲۰۲۶ بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)
.PP
اجازه ساخت و توزیع نسخه‌های عین متن این سند به شرطی داده می‌شود که اعلان حق نشر و این اعلان اجازه در تمام نسخه‌ها حفظ شوند.
.PP
اجازه کپی و توزیع نسخه‌های اصلاح‌شده این سند تحت شرایط کپی عین متن داده می‌شود، مشروط بر آنکه کل اثر اشتقاقی حاصل تحت شرایط اعلان اجازه‌ای یکسان با این اعلان توزیع شود.
.PP
اجازه کپی و توزیع ترجمه‌های این سند به زبانی دیگر، تحت شرایط فوق برای نسخه‌های اصلاح‌شده داده می‌شود، با این استثنا که این اعلان اجازه ممکن است در یک ترجمه تاییدشده توسط بنیاد نرم‌افزارهای آزاد بیان شود.

.\" Local Variables:
.\" eval: (add-hook 'before-save-hook 'time-stamp nil t)
.\" time-stamp-pattern: "^\\.TH [^ ]+ [^ ]+ \"?%Y-%m-%d\\_>"
.\" time-stamp-time-zone: "UTC0"
.\" End: