HTAGS(1) General Commands Manual HTAGS(1) نام (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 پیش از تگ . --insert-header file درج سرآیند سفارشی برگرفته از file پس از تگ . --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] استفاده از تگ برای نمایش نمایه فایل‌ها. می‌توانید به صورت اختیاری تعداد ردیف‌ها را مشخص کنید؛ مقدار پیش‌فرض 5 است. -t, --title title عنوان ابرمتن. مقدار پیش‌فرض، آخرین بخش از مسیر دایرکتوری جاری است. --tabs cols فواصل تب (Tab stops). مقدار پیش‌فرض 8 است. --table-list استفاده از تگ
برای نمایش فهرست برچسب‌ها. --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´. عیب‌یابی (DIAGNOSTICS) دستور Htags در صورت وقوع خطا با مقداری غیر از 0 و در غیر این صورت با مقدار 0 خارج می‌شود. همچنین ببینید (SEE ALSO) htags-server(1), global(1), gtags(1), gtags.conf(5). سامانه برچسب‌گذاری کد منبع GNU Global (http://www.gnu.org/software/global). اشکالات (BUGS) ابرمتن تولیدشده بسیار بزرگ است. پیش از اجرا، فضای دیسک خود را بررسی کنید. پشتیبانی از زبان PHP با کامل بودن فاصله زیادی دارد. گزینه‌های -f و -D برنامه‌های CGI تولید می‌کنند. اگر ابرمتن را در دسترس عموم قرار می‌دهید، لطفاً خطرات امنیتی را در نظر بگیرید. ابزار Htags از تجزیه‌کننده‌های افزونه‌ای (plug-in parser) پشتیبانی نمی‌کند. نویسندگان (AUTHORS) Shigio YAMAGUCHI، Hideki IWAMOTO و دیگران. تاریخچه (HISTORY) دستور htags نخستین بار در FreeBSD 2.2.2 ظاهر شد. GNU Project June 2013 HTAGS(1)