.\" This file is generated automatically by convert.pl from htags/manual.in.
.TH HTAGS 1 "June 2013" "GNU Project"
.SH "نام (NAME)"
htags \- ایجاد ابرمتن HTML از کد منبع برنامه با GNU GLOBAL
.SH "خلاصه دستور (SYNOPSIS)"
\fBhtags\fP [-aDfFghInosTvw][-d \fIdbpath\fP][-m \fIname\fP][-t \fItitle\fP][\fIdir\fP]
.br
.SH "توضیحات (DESCRIPTION)"
دستور
\fBHtags\fP
از مجموعه‌ای از فایل‌های منبع زبان‌های C، Yacc، Java، PHP و اسمبلی، ابرمتن (Hypertext) تولید می‌کند.
.PP
پیش از استفاده از این دستور، باید
\fBgtags\fP(1)
را در دایرکتوری ریشه پروژه منبع اجرا کنید. سپس می‌توانید
\fBhtags\fP
را در همان مکان اجرا نمایید.
\fBHtags\fP
دایرکتوری جدیدی با نام \'HTML\' ایجاد کرده و ابرمتن را در آن قرار می‌دهد. می‌توانید مرور کد را از فایل \'HTML/index.html\' آغاز کنید.
.PP
از آنجا که
\fBhtags\fP
تا زمانی که گزینه‌های
\fB-D\fP
یا
\fB-f\fP
مشخص نشده باشند یک ابرمتن ایستا تولید می‌کند، می‌توانید آن را به هر جایی منتقل کرده و بدون نیاز به کارساز وب HTTP در هر مرورگری مشاهده کنید. اگر از گزینه‌های
\fB-D\fP
یا
\fB-f\fP
استفاده کنید، به کارساز HTTP نیاز خواهید داشت. اگرچه هر کارساز وب قابل استفاده است، اما استفاده از
\fBhtags-server\fP(1)
توصیه می‌شود.
.PP
این دستور گزینه‌های بسیار زیادی دارد. اگر در استفاده از
\fBhtags\fP
تازه‌کار هستید، توصیه می‌شود از گزینه
\fB--suggest\fP
استفاده کنید. با این گزینه،
\fBhtags\fP
گزینه‌های پرکاربرد و محبوب را از طرف شما انتخاب می‌کند.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر در دسترس هستند:
.PP
.TP
\fB-a\fP, \fB--alphabet\fP
ایجاد نمایه الفبایی مناسب برای پروژه‌های بزرگ.
.TP
\fB--auto-completion\fP[=\fIlimit\fP]
فعال‌سازی قابلیت تکمیل خودکار برای فرم ورودی. اگر
\fIlimit\fP
مشخص شود، تعداد پیشنهادات به این مقدار محدود می‌شود. لطفاً توجه داشته باشید که این قابلیت نیازمند فعال بودن جاوااسکریپت در مرورگر شما است.
.TP
\fB-C\fP, \fB--directory\fP \fIdir\fP
تغییر دایرکتوری قبل از انجام کلیه کارها از جمله تجزیه و تحلیل پارامترها.
.TP
\fB--caution\fP
نمایش پیام هشدار و احتیاط در صفحه اصلی.
.TP
\fB--cflow\fP \fIcflowfile\fP
افزودن درخت فراخوانی توسط
\fBcflow\fP(1).
فایل
\fIcflowfile\fP
باید در قالب استاندارد posix باشد. اگر از GNU
\fBcflow\fP
استفاده می‌کنید، دستور را در دایرکتوری ریشه پروژه به همراه گزینه
\fB--format=posix\fP
اجرا کنید. این گزینه منسوخ شده است؛ لطفاً به جای آن از
\fB--call-tree\fP
یا
\fB--callee-tree\fP
استفاده کنید.
.TP
\fB--call-tree\fP \fIcallfile\fP
افزودن درخت فراخوانی (call tree) توسط
\fBcflow\fP(1)؛
فایل
\fIcallfile\fP
باید در قالب posix باشد. اگر از GNU
\fBcflow\fP
استفاده می‌کنید، دستور را در دایرکتوری ریشه پروژه به همراه گزینه
\fB--format=posix\fP
اجرا کنید.
.TP
\fB--callee-tree\fP \fIcalleefile\fP
افزودن درخت فراخوانده‌شده‌ها (callee tree) توسط
\fBcflow\fP(1)؛
فایل
\fIcalleefile\fP
باید در قالب posix باشد. اگر از GNU
\fBcflow\fP
استفاده می‌کنید، دستور را در دایرکتوری ریشه پروژه با گزینه‌های
\fB--format=posix\fP
و
\fB--reverse\fP
اجرا نمایید.
.TP
\fB--colorize-warned-line\fP
استفاده از رنگ برای برجسته‌سازی خطوط دارای هشدار.
.TP
\fB--cvsweb\fP \fIurl\fP
افزودن پیوند به cvsweb؛ مقدار
\fIurl\fP
به عنوان پایه نشانی اینترنتی (Base URL) استفاده می‌شود. زمانی که دایرکتوری \'CVS\' در دایرکتوری ریشه پروژه وجود داشته باشد، محتوای \'CVS/Repository\' به عنوان مسیر نسبی از پایه استفاده می‌شود.
.TP
\fB--cvsweb-cvsroot\fP \fIcvsroot\fP
مشخص کردن cvsroot در نشانی cvsweb.
.TP
\fB-D\fP, \fB--dynamic\fP
تولید پویا فهرست برچسب‌ها با استفاده از برنامه CGI. اگرچه این گزینه هم حجم و هم زمان تولید ابرمتن را کاهش می‌دهد، اما نیازمند راه‌اندازی کارساز HTTP است.
.TP
\fB-d\fP, \fB--dbpath\fP \fIdbpath\fP
مشخص کردن دایرکتوری حاوی فایل \'GTAGS\'. مقدار پیش‌فرض، دایرکتوری جاری است.
.TP
\fB--disable-grep\fP
غیرفعال کردن
\fBgrep\fP
در فرم جستجو (\fB-f\fP, \fB--form\fP).
.TP
\fB--disable-idutils\fP
غیرفعال کردن
\fBidutils\fP
در فرم جستجو (\fB-f\fP, \fB--form\fP).
.TP
\fB-F\fP, \fB--frame\fP
استفاده از فریم‌ها (Frame) برای صفحه اصلی.
.TP
\fB-f\fP, \fB--form\fP
افزودن فرم جستجو با استفاده از برنامه CGI. برای استفاده از این قابلیت باید یک کارساز HTTP راه‌اندازی کنید.
.TP
\fB--fixed-guide\fP
قرار دادن یک راهنمای ثابت در پایین صفحه نمایش مرورگر.
.TP
\fB--full-path\fP
استفاده از نام مسیر کامل در نمایه فایل‌ها. به طور پیش‌فرض، فقط آخرین بخش مسیر استفاده می‌شود.
.TP
\fB-g\fP, \fB--gtags\fP
اجرای دستور
\fBgtags\fP(1)
پیش از شروع کار. گزینه‌های
\fB-v\fP،
\fB-w\fP
و
\fIdbpath\fP
به
\fBgtags\fP
پاس داده می‌شوند.
.TP
\fB--gtagsconf\fP \fIfile\fP
تنظیم متغیر محیطی
\fBGTAGSCONF\fP
به مقدار
\fIfile\fP.
.TP
\fB--gtagslabel\fP \fIlabel\fP
تنظیم متغیر محیطی
\fBGTAGSLABEL\fP
به مقدار
\fIlabel\fP.
.TP
\fB-h\fP, \fB--func-header\fP[=\fIposition\fP]
درج سرآیند تابع برای هر تابع. به طور پیش‌فرض،
\fBhtags\fP
آن‌ها را تولید نمی‌کند. می‌توانید موقعیت آن را با استفاده از
\fIposition\fP
انتخاب کنید که یکی از مقادیر \'before\'، \'right\' یا \'after\' (پیش‌فرض) را می‌پذیرد.
.TP
\fB--help\fP
چاپ پیام راهنمای نحوه استفاده.
.TP
\fB--html-header\fP \fIfile\fP
درج یک رکورد هدر برگرفته از
\fIfile\fP
درون هدر HTML هر فایل.
.TP
\fB-I\fP, \fB--icon\fP
استفاده از آیکون‌ها به جای متن برای برخی پیوندها.
.TP
\fB--insert-footer\fP \fIfile\fP
درج پاورقی سفارشی برگرفته از
\fIfile\fP
پیش از تگ </body>.
.TP
\fB--insert-header\fP \fIfile\fP
درج سرآیند سفارشی برگرفته از
\fIfile\fP
پس از تگ <body>.
.TP
\fB--item-order\fP \fIspec\fP
مشخص کردن ترتیب موارد در صفحه اصلی. مقدار
\fIspec\fP
رشته‌ای متشکل از نشانه‌های موارد به ترتیب مورد نظر است. معنی هر نشانه به صورت زیر است:
\'c\': هشدار و احتیاط؛ \'s\': فرم جستجو؛
\'m\': توابع اصلی؛ \'d\': تعاریف؛ \'f\': فایل‌ها؛ \'t\': درخت فراخوانی.
مقدار پیش‌فرض \'csmdf\' است.
.TP
\fB-m\fP, \fB--main-func\fP \fIname\fP
مشخص کردن نام تابع شروع و راه‌اندازی؛ مقدار پیش‌فرض \'main\' است.
.TP
\fB--map-file\fP
تولید فایل \'MAP\'.
.TP
\fB-n\fP, \fB--line-number\fP[=\fIcolumns\fP]
چاپ شماره خطوط. به طور پیش‌فرض، شماره خطوط چاپ نمی‌شوند. مقدار پیش‌فرض برای
\fIcolumns\fP
برابر 4 است.
.TP
\fB--no-order-list\fP
اعداد در قالب لیست شماره‌دار نمایش داده نمی‌شوند.
.TP
\fB-o\fP, \fB--other\fP
شامل کردن نه تنها فایل‌های منبع بلکه سایر فایل‌ها در نمایه فایل.
.TP
\fB-s\fP, \fB--symbol\fP
ایجاد لنگر (anchor) نه تنها برای تعاریف و ارجاعات، بلکه برای سایر نمادها.
.TP
\fB--show-position\fP
چاپ موقعیت مکانی برای هر تعریف تابع. این رشته توسط ویرایشگرهای عمومی در یونیکس قابل تفسیر است. مقدار پیش‌فرض false است.
.TP
\fB--statistics\fP
چاپ اطلاعات آماری.
.TP
\fB--suggest\fP
دستور
\fBHtags\fP
گزینه‌های محبوب را از طرف کاربران تازه‌کار انتخاب می‌کند. این گزینه در حال حاضر معادل
\fB-aghInosTxv --show-position --fixed-guide\fP
است.
.TP
\fB--suggest2\fP
دستور
\fBHtags\fP
گزینه‌های محبوب را از طرف کاربران تازه‌کار انتخاب می‌کند. این گزینه علاوه بر امکانات گزینه
\fB--suggest\fP،
قابلیت‌های فریم، AJAX و CGI را نیز فعال می‌کند. این گزینه در حال حاضر معادل
\fB--suggest -DfF --auto-completion --tree-view=filetree\fP
است.
.TP
\fB-T\fP, \fB--table-flist\fP[=\fIrows\fP]
استفاده از تگ <table> برای نمایش نمایه فایل‌ها. می‌توانید به صورت اختیاری تعداد ردیف‌ها را مشخص کنید؛ مقدار پیش‌فرض 5 است.
.TP
\fB-t\fP, \fB--title\fP \fItitle\fP
عنوان ابرمتن. مقدار پیش‌فرض، آخرین بخش از مسیر دایرکتوری جاری است.
.TP
\fB--tabs\fP \fIcols\fP
فواصل تب (Tab stops). مقدار پیش‌فرض 8 است.
.TP
\fB--table-list\fP
استفاده از تگ <table> برای نمایش فهرست برچسب‌ها.
.TP
\fB--tree-view\fP[=\fItype\fP]
استفاده از نمای درختی (treeview) برای نمایه فایل‌ها. لطفاً توجه داشته باشید که این قابلیت نیازمند فعال بودن جاوااسکریپت در مرورگر شما است. مقادیر ممکن برای
\fItype\fP
عبارتند از:
\fItreeview\fP، \fIfiletree\fP، \fItreeview-red\fP، \fItreeview-black\fP، \fItreeview-gray\fP، \fItreeview-famfamfam\fP.
مقدار پیش‌فرض
\fItreeview\fP
است.
.TP
\fB-v\fP, \fB--verbose\fP
حالت پرگو با نمایش جزئیات کامل عملیات.
.TP
\fB--version\fP
نمایش شماره نسخه.
.TP
\fB-w\fP, \fB--warning\fP
چاپ پیام‌های هشدار.
.TP
\fIdir\fP
دایرکتوری که نتیجه این دستور در آن ذخیره می‌شود. مقدار پیش‌فرض، دایرکتوری جاری است.
.SH "مثال‌ها (EXAMPLES)"
.nf
$ gtags -v
$ htags -sanohITvt 'Welcome to XXX source tour!'
$ firefox HTML/index.html
.PP
$ htags --suggest2
$ htags-server >& log &
$ firefox http://127.0.0.1:8000
.fi
.SH "فایل‌ها (FILES)"
.TP
\'GTAGS\'
فایل برچسب برای تعاریف.
.TP
\'GRTAGS\'
فایل برچسب برای ارجاعات.
.TP
\'GPATH\'
فایل برچسب برای فایل‌های منبع.
.TP
\'gtags.conf\', \'$HOME/.globalrc\'
داده‌های پیکربندی برای GNU Global. به
\fBgtags.conf\fP(5)
مراجعه کنید.
.TP
\'HTML/FILEMAP\'
فایل نگاشت برای تبدیل نام فایل به مسیر فایل.
.TP
\'HTML/GTAGSROOT\'
در صورت وجود این فایل، برنامه CGI با نام \'global.cgi\' متغیر محیطی
\fBGTAGSROOT\fP
را به محتویات آن تنظیم می‌کند. اگر دایرکتوری \'HTML\' را از مکان اصلی آن منتقل کنید، لطفاً این فایل را ایجاد نمایید.
.TP
\'HTML/.htaccess\'
فایل پیکربندی محلی برای آپاچی (Apache). این فایل زمانی که گزینه‌های
\fB-f\fP
یا
\fB-D\fP
مشخص شده باشند، تولید می‌شود.
.TP
\'HTML/index.html\'
فایل شروع و صفحه اصلی.
.TP
\'HTML/MAP\'
فایل نگاشت برای تبدیل نام برچسب به مسیر فهرست برچسب.
.TP
\'HTML/style.css\'
فایل شیوه‌نامه (Style sheet).
.TP
\'/usr/local/share/gtags/style.css.tmpl\'
قالب فایل شیوه‌نامه (\'HTML/style.css\').
.SH "متغیرهای محیطی (ENVIRONMENT)"
متغیرهای محیطی زیر بر اجرای
\fBhtags\fP
تأثیر می‌گذارند:
.PP
.TP
\fBGTAGSCACHE\fP
اندازه حافظه نهان B-tree. مقدار پیش‌فرض 50000000 (بایت) است.
.TP
\fBGTAGSCONF\fP
فایل پیکربندی.
.TP
\fBGTAGSLABEL\fP
برچسب پیکربندی. مقدار پیش‌فرض \'default\' است.
.TP
\fBHTAGS_OPTIONS\fP
مقدار این متغیر به ابتدای آرگومان‌ها افزوده می‌شود.
.TP
\fBTMPDIR\fP
محل مورد استفاده برای ذخیره فایل‌های موقت. مقدار پیش‌فرض \'/tmp\' است.
.TP
\fBGTAGSFORCECPP\fP
اگر این متغیر تنظیم شود، هر فایلی که پسوند آن \'.h\' باشد به عنوان یک فایل منبع ++C در نظر گرفته می‌شود.
.SH "پیکربندی (CONFIGURATION)"
متغیرهای پیکربندی زیر بر اجرای
\fBhtags\fP
تأثیر می‌گذارند:
.PP
.TP
datadir(string)
دایرکتوری داده‌های مشترک. مقدار پیش‌فرض \'/usr/local/share\' است اما می‌توانید این مقدار را با استفاده از اسکریپت configure تغییر دهید.
\fBHtags\fP
فایل‌های قالب را در دایرکتوری \'gtags\' واقع در این دایرکتوری داده جستجو می‌کند.
.TP
include_file_suffixes(comma separated list)
پسوندهای فایل‌های include. مقدار پیش‌فرض عبارت است از:
.br
\'h,hh,hxx,hpp,H,inc.php\'.
.TP
langmap(comma separated list)
نگاشت زبان‌ها. هر نگاشت جداشده با کاما شامل نام زبان، دو نقطه و فهرستی از پسوندهای فایل است. نگاشت پیش‌فرض عبارت است از:
.br
\'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml\'.
.SH "عیب‌یابی (DIAGNOSTICS)"
دستور
\fBHtags\fP
در صورت وقوع خطا با مقداری غیر از 0 و در غیر این صورت با مقدار 0 خارج می‌شود.
.SH "همچنین ببینید (SEE ALSO)"
\fBhtags-server\fP(1),
\fBglobal\fP(1),
\fBgtags\fP(1),
\fBgtags.conf\fP(5).
.PP
سامانه برچسب‌گذاری کد منبع GNU Global
.br
(http://www.gnu.org/software/global).
.SH "اشکالات (BUGS)"
ابرمتن تولیدشده بسیار بزرگ است. پیش از اجرا، فضای دیسک خود را بررسی کنید.
.PP
پشتیبانی از زبان PHP با کامل بودن فاصله زیادی دارد.
.PP
گزینه‌های
\fB-f\fP
و
\fB-D\fP
برنامه‌های CGI تولید می‌کنند. اگر ابرمتن را در دسترس عموم قرار می‌دهید، لطفاً خطرات امنیتی را در نظر بگیرید.
.PP
ابزار Htags از تجزیه‌کننده‌های افزونه‌ای (plug-in parser) پشتیبانی نمی‌کند.
.SH "نویسندگان (AUTHORS)"
Shigio YAMAGUCHI، Hideki IWAMOTO و دیگران.
.SH "تاریخچه (HISTORY)"
دستور
\fBhtags\fP
نخستین بار در FreeBSD 2.2.2 ظاهر شد.