نام (NAME)

htags - ایجاد ابرمتن HTML از کد منبع برنامه با GNU GLOBAL

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

htags [-aDfFghInosTvw][-d dbpath][-m name][-t title][dir]

توضیحات (DESCRIPTION)

دستور Htags از مجموعه‌ای از فایل‌های منبع زبان‌های C، Yacc، Java، PHP و اسمبلی، ابرمتن (Hypertext) تولید می‌کند.

پیش از استفاده از این دستور، باید gtags(1) را در دایرکتوری ریشه پروژه منبع اجرا کنید. سپس می‌توانید htags را در همان مکان اجرا نمایید. Htags دایرکتوری جدیدی با نام ´HTML´ ایجاد کرده و ابرمتن را در آن قرار می‌دهد. می‌توانید مرور کد را از فایل ´HTML/index.html´ آغاز کنید.

از آنجا که htags تا زمانی که گزینه‌های -D یا -f مشخص نشده باشند یک ابرمتن ایستا تولید می‌کند، می‌توانید آن را به هر جایی منتقل کرده و بدون نیاز به کارساز وب HTTP در هر مرورگری مشاهده کنید. اگر از گزینه‌های -D یا -f استفاده کنید، به کارساز HTTP نیاز خواهید داشت. اگرچه هر کارساز وب قابل استفاده است، اما استفاده از htags-server(1) توصیه می‌شود.

این دستور گزینه‌های بسیار زیادی دارد. اگر در استفاده از htags تازه‌کار هستید، توصیه می‌شود از گزینه --suggest استفاده کنید. با این گزینه، htags گزینه‌های پرکاربرد و محبوب را از طرف شما انتخاب می‌کند.

گزینه‌ها (OPTIONS)

گزینه‌های زیر در دسترس هستند:

-a, --alphabet: ایجاد نمایه الفبایی مناسب برای پروژه‌های بزرگ.
--auto-completion[=limit]: فعال‌سازی قابلیت تکمیل خودکار برای فرم ورودی. اگر limit مشخص شود، تعداد پیشنهادات به این مقدار محدود می‌شود. لطفاً توجه داشته باشید که این قابلیت نیازمند فعال بودن جاوااسکریپت در مرورگر شما است.
-C, --directory dir: تغییر دایرکتوری قبل از انجام کلیه کارها از جمله تجزیه و تحلیل پارامترها.
--caution: نمایش پیام هشدار و احتیاط در صفحه اصلی.
--cflow cflowfile: افزودن درخت فراخوانی توسط cflow(1). فایل cflowfile باید در قالب استاندارد posix باشد. اگر از GNU cflow استفاده می‌کنید، دستور را در دایرکتوری ریشه پروژه به همراه گزینه --format=posix اجرا کنید. این گزینه منسوخ شده است؛ لطفاً به جای آن از --call-tree یا --callee-tree استفاده کنید.
--call-tree callfile: افزودن درخت فراخوانی (call tree) توسط cflow(1)؛ فایل callfile باید در قالب posix باشد. اگر از GNU cflow استفاده می‌کنید، دستور را در دایرکتوری ریشه پروژه به همراه گزینه --format=posix اجرا کنید.
--callee-tree calleefile: افزودن درخت فراخوانده‌شده‌ها (callee tree) توسط cflow(1)؛ فایل calleefile باید در قالب posix باشد. اگر از GNU cflow استفاده می‌کنید، دستور را در دایرکتوری ریشه پروژه با گزینه‌های --format=posix و --reverse اجرا نمایید.
--colorize-warned-line: استفاده از رنگ برای برجسته‌سازی خطوط دارای هشدار.
--cvsweb url: افزودن پیوند به cvsweb؛ مقدار url به عنوان پایه نشانی اینترنتی (Base URL) استفاده می‌شود. زمانی که دایرکتوری ´CVS´ در دایرکتوری ریشه پروژه وجود داشته باشد، محتوای ´CVS/Repository´ به عنوان مسیر نسبی از پایه استفاده می‌شود.
--cvsweb-cvsroot cvsroot: مشخص کردن cvsroot در نشانی cvsweb.
-D, --dynamic: تولید پویا فهرست برچسب‌ها با استفاده از برنامه CGI. اگرچه این گزینه هم حجم و هم زمان تولید ابرمتن را کاهش می‌دهد، اما نیازمند راه‌اندازی کارساز HTTP است.
-d, --dbpath dbpath: مشخص کردن دایرکتوری حاوی فایل ´GTAGS´. مقدار پیش‌فرض، دایرکتوری جاری است.
--disable-grep: غیرفعال کردن grep در فرم جستجو (-f, --form).
--disable-idutils: غیرفعال کردن idutils در فرم جستجو (-f, --form).
-F, --frame: استفاده از فریم‌ها (Frame) برای صفحه اصلی.
-f, --form: افزودن فرم جستجو با استفاده از برنامه CGI. برای استفاده از این قابلیت باید یک کارساز HTTP راه‌اندازی کنید.
--fixed-guide: قرار دادن یک راهنمای ثابت در پایین صفحه نمایش مرورگر.
--full-path: استفاده از نام مسیر کامل در نمایه فایل‌ها. به طور پیش‌فرض، فقط آخرین بخش مسیر استفاده می‌شود.
-g, --gtags: اجرای دستور gtags(1) پیش از شروع کار. گزینه‌های -v، -w و dbpath به gtags پاس داده می‌شوند.
--gtagsconf file: تنظیم متغیر محیطی GTAGSCONF به مقدار file.
--gtagslabel label: تنظیم متغیر محیطی GTAGSLABEL به مقدار label.
-h, --func-header[=position]: درج سرآیند تابع برای هر تابع. به طور پیش‌فرض، htags آن‌ها را تولید نمی‌کند. می‌توانید موقعیت آن را با استفاده از position انتخاب کنید که یکی از مقادیر ´before´، ´right´ یا ´after´ (پیش‌فرض) را می‌پذیرد.
--help: چاپ پیام راهنمای نحوه استفاده.
--html-header file: درج یک رکورد هدر برگرفته از file درون هدر HTML هر فایل.
-I, --icon: استفاده از آیکون‌ها به جای متن برای برخی پیوندها.
--insert-footer file: درج پاورقی سفارشی برگرفته از file پیش از تگ </body>.
--insert-header file: درج سرآیند سفارشی برگرفته از file پس از تگ <body>.
--item-order spec: مشخص کردن ترتیب موارد در صفحه اصلی. مقدار spec رشته‌ای متشکل از نشانه‌های موارد به ترتیب مورد نظر است. معنی هر نشانه به صورت زیر است: ´c´: هشدار و احتیاط؛ ´s´: فرم جستجو؛ ´m´: توابع اصلی؛ ´d´: تعاریف؛ ´f´: فایل‌ها؛ ´t´: درخت فراخوانی. مقدار پیش‌فرض ´csmdf´ است.
-m, --main-func name: مشخص کردن نام تابع شروع و راه‌اندازی؛ مقدار پیش‌فرض ´main´ است.
--map-file: تولید فایل ´MAP´.
-n, --line-number[=columns]: چاپ شماره خطوط. به طور پیش‌فرض، شماره خطوط چاپ نمی‌شوند. مقدار پیش‌فرض برای columns برابر 4 است.
--no-order-list: اعداد در قالب لیست شماره‌دار نمایش داده نمی‌شوند.
-o, --other: شامل کردن نه تنها فایل‌های منبع بلکه سایر فایل‌ها در نمایه فایل.
-s, --symbol: ایجاد لنگر (anchor) نه تنها برای تعاریف و ارجاعات، بلکه برای سایر نمادها.
--show-position: چاپ موقعیت مکانی برای هر تعریف تابع. این رشته توسط ویرایشگرهای عمومی در یونیکس قابل تفسیر است. مقدار پیش‌فرض false است.
--statistics: چاپ اطلاعات آماری.
--suggest: دستور Htags گزینه‌های محبوب را از طرف کاربران تازه‌کار انتخاب می‌کند. این گزینه در حال حاضر معادل -aghInosTxv --show-position --fixed-guide است.
--suggest2: دستور Htags گزینه‌های محبوب را از طرف کاربران تازه‌کار انتخاب می‌کند. این گزینه علاوه بر امکانات گزینه --suggest، قابلیت‌های فریم، AJAX و CGI را نیز فعال می‌کند. این گزینه در حال حاضر معادل --suggest -DfF --auto-completion --tree-view=filetree است.
-T, --table-flist[=rows]: استفاده از تگ <table> برای نمایش نمایه فایل‌ها. می‌توانید به صورت اختیاری تعداد ردیف‌ها را مشخص کنید؛ مقدار پیش‌فرض 5 است.
-t, --title title: عنوان ابرمتن. مقدار پیش‌فرض، آخرین بخش از مسیر دایرکتوری جاری است.
--tabs cols: فواصل تب (Tab stops). مقدار پیش‌فرض 8 است.
--table-list: استفاده از تگ <table> برای نمایش فهرست برچسب‌ها.
--tree-view[=type]: استفاده از نمای درختی (treeview) برای نمایه فایل‌ها. لطفاً توجه داشته باشید که این قابلیت نیازمند فعال بودن جاوااسکریپت در مرورگر شما است. مقادیر ممکن برای type عبارتند از: treeview، filetree، treeview-red، treeview-black، treeview-gray، treeview-famfamfam. مقدار پیش‌فرض treeview است.
-v, --verbose: حالت پرگو با نمایش جزئیات کامل عملیات.
--version: نمایش شماره نسخه.
-w, --warning: چاپ پیام‌های هشدار.
dir: دایرکتوری که نتیجه این دستور در آن ذخیره می‌شود. مقدار پیش‌فرض، دایرکتوری جاری است.

مثال‌ها (EXAMPLES)

$ gtags -v
$ htags -sanohITvt 'Welcome to XXX source tour!'
$ firefox HTML/index.html

$ htags --suggest2
$ htags-server >& log &
$ firefox http://127.0.0.1:8000

فایل‌ها (FILES)

´GTAGS´: فایل برچسب برای تعاریف.
´GRTAGS´: فایل برچسب برای ارجاعات.
´GPATH´: فایل برچسب برای فایل‌های منبع.
´gtags.conf´, ´$HOME/.globalrc´: داده‌های پیکربندی برای GNU Global. به gtags.conf(5) مراجعه کنید.
´HTML/FILEMAP´: فایل نگاشت برای تبدیل نام فایل به مسیر فایل.
´HTML/GTAGSROOT´: در صورت وجود این فایل، برنامه CGI با نام ´global.cgi´ متغیر محیطی GTAGSROOT را به محتویات آن تنظیم می‌کند. اگر دایرکتوری ´HTML´ را از مکان اصلی آن منتقل کنید، لطفاً این فایل را ایجاد نمایید.
´HTML/.htaccess´: فایل پیکربندی محلی برای آپاچی (Apache). این فایل زمانی که گزینه‌های -f یا -D مشخص شده باشند، تولید می‌شود.
´HTML/index.html´: فایل شروع و صفحه اصلی.
´HTML/MAP´: فایل نگاشت برای تبدیل نام برچسب به مسیر فهرست برچسب.
´HTML/style.css´: فایل شیوه‌نامه (Style sheet).
´/usr/local/share/gtags/style.css.tmpl´: قالب فایل شیوه‌نامه (´HTML/style.css´).

متغیرهای محیطی (ENVIRONMENT)

متغیرهای محیطی زیر بر اجرای htags تأثیر می‌گذارند:

GTAGSCACHE: اندازه حافظه نهان B-tree. مقدار پیش‌فرض 50000000 (بایت) است.
GTAGSCONF: فایل پیکربندی.
GTAGSLABEL: برچسب پیکربندی. مقدار پیش‌فرض ´default´ است.
HTAGS_OPTIONS: مقدار این متغیر به ابتدای آرگومان‌ها افزوده می‌شود.
TMPDIR: محل مورد استفاده برای ذخیره فایل‌های موقت. مقدار پیش‌فرض ´/tmp´ است.
GTAGSFORCECPP: اگر این متغیر تنظیم شود، هر فایلی که پسوند آن ´.h´ باشد به عنوان یک فایل منبع ++C در نظر گرفته می‌شود.

پیکربندی (CONFIGURATION)

متغیرهای پیکربندی زیر بر اجرای htags تأثیر می‌گذارند:

datadir(string): دایرکتوری داده‌های مشترک. مقدار پیش‌فرض ´/usr/local/share´ است اما می‌توانید این مقدار را با استفاده از اسکریپت configure تغییر دهید. Htags فایل‌های قالب را در دایرکتوری ´gtags´ واقع در این دایرکتوری داده جستجو می‌کند.
include_file_suffixes(comma separated list): پسوندهای فایل‌های include. مقدار پیش‌فرض عبارت است از:
´h,hh,hxx,hpp,H,inc.php´.
langmap(comma separated list): نگاشت زبان‌ها. هر نگاشت جداشده با کاما شامل نام زبان، دو نقطه و فهرستی از پسوندهای فایل است. نگاشت پیش‌فرض عبارت است از:
´c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml´.