.de d \" begin display
.sp
.in +4
.nf
..
.de e \" end display
.in -4
.fi
.sp
..
.TH "HXTOC" "1" "10 Jul 2011" "7.x" "HTML-XML-utils"
.SH "نام (NAME)"
hxtoc \- درج فهرست مطالب در پرونده‌های HTML
.SH "خلاصه دستور (SYNOPSIS)"
.B hxtoc
.RB "[\| " \-x " \|]"
.RB "[\| " \-l
.IR low " \|]"
.RB "[\| " \-h
.IR high " \|]"
.RB "[\| " \-t " \|]"
.RB "[\| " \-d " \|]"
.RB "[\| " \-c
.IR class " \|]"
.RB "[\| " \-f " \|]"
.RI "[\| " file-or-URL " \|]"
.SH "توضیحات (DESCRIPTION)"
.LP
دستور
.B hxtoc
یک پروندهٔ HTML را می‌خواند و شناسه‌های (ID) ناموجود را در تمام عناصر H1 تا H6 بین سطوح
.B \-l
و
.B \-h
درج می‌کند (مگر اینکه گزینهٔ
.B \-d
فعال باشد؛ پایین‌تر را ببینید). اگر گزینهٔ
.B \-t
داده نشود، عنصرهای A را نیز با خصوصیت NAME درج می‌کند، زیرا مرورگرهای قدیمی خصوصیت‌های ID را به عنوان لنگرگاه مقصد تشخیص نمی‌دهند. خروجی در خروجی استاندارد (stdout) نوشته می‌شود.
.LP
اگر یادداشتی به شکل
.d
<!\-\-toc\-\->
.e
یا جفتی از یادداشت‌ها به شکل
.d
<!\-\-begin-toc\-\->
\&...
<!\-\-end-toc\-\->
.e
وجود داشته باشد، آن یادداشت یا جفت‌کامنت به همراه هر آنچه بین آن‌هاست، با یک فهرست مطالب جایگزین خواهد شد که شامل فهرستی (UL) از پیوندها به تمام سربرگ‌های درون سند است.
.LP
متن سربرگ‌ها، از جمله هرگونه نشانه‌گذاری درون‌خطی، در این فهرست مطالب کپی می‌شود؛ به جز خصوصیت‌های ID، برچسب‌های DFN و برچسب‌های SPAN با کلاس "index" که نادیده گرفته می‌شوند (اما محتوای عناصر کپی می‌شود).
.LP
متن کپی‌شده را می‌توان به‌صورت اختیاری ابتدا «تخت» (flatten) کرد؛ گزینهٔ
.BR \-f
را ببینید.
.LP
اگر یک سربرگ دارای ویژگی CLASS با مقدار (یا یکی از مقادیر) کلیدواژهٔ "no-toc" باشد، آن سربرگ در فهرست مطالب ظاهر نخواهد شد.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر پشتیبانی می‌شوند:
.TP 10
.B \-x
استفاده از قواعد XML: عناصر خالی با یک اسلش در انتها نوشته می‌شوند: <IMG\ />
.TP
.BI \-l " low"
پایین‌ترین شمارهٔ سربرگی که در فهرست مطالب نمایش داده می‌شود را تعیین می‌کند. مقدار پیش‌فرض 1 است (یعنی H1).
.TP
.BI \-h " high"
بالاترین شمارهٔ سربرگی که در فهرست مطالب نمایش داده می‌شود را تعیین می‌کند. مقدار پیش‌فرض نامحدود است.
.TP
.B \-t
به‌طور معمول،
.B hxtoc
هم خصوصیت‌های ID و هم عناصر خالی A با ویژگی NAME و CLASS="bctarget" را اضافه می‌کند تا مرورگرهای قدیمی‌تری که ID را تشخیص نمی‌دهند نیز مقصد را بیابند. با این گزینه، عناصر A تولید نخواهند شد.
.TP
.BI \-c " class"
عناصر UL تولیدشده در فهرست مطالب، ویژگی CLASS با مقدار
.I class
خواهند داشت. مقدار پیش‌فرض "toc" است.
.TP
.B \-d
تلاش می‌کند به‌جای H1 تا H6، از عناصر بخش‌بندی (sectioning) به عنوان مقصد در فهرست مطالب استفاده کند. عنصر بخش‌بندی یک عنصر DIV، SECTION، ARTICLE، ASIDE یا NAV است که دست‌کم شامل یک عنصر سربرگ (H1 تا H6) یا HGROUP باشد. اگر عنصر بخش‌بندی فاقد شناسه (ID) باشد، یک شناسه دریافت خواهد کرد. با این گزینه، سطح هر H1 تا H6 که نخستین سربرگِ یک عنصر بخش‌بندی باشد، بر اساس نام آن تعیین نمی‌شود، بلکه بر اساس عمق تو در تویی عناصر بخش‌بندی تعیین می‌گردد. (هر H1 تا H6 که نخستین سربرگ عنصر بخش‌بندی نباشد، همچنان سطح خود را از نامش می‌گیرد.)
.TP
.B \-f
تخت کردن متن فهرست مطالب. بدون
.BR \-f ،
محتوای عناصر سربرگ تقریباً بدون تغییر در فهرست مطالب کپی می‌شوند؛ یعنی شامل تمام عناصر فرزند و ویژگی‌های آن‌ها (به‌جز خصوصیت‌های ID، عناصر DFN و برخی عناصر خاص SPAN، همان‌طور که در بالا توضیح داده شد). با
.BR \-f ،
محتوا در عوض تخت می‌شود: تمامی عناصر فرزند حذف شده و فقط محتوای آن‌ها در فهرست مطالب کپی می‌شود. علاوه بر این، عناصر دارای ویژگی ALT، مانند IMG، با محتوای ویژگی ALT جایگزین می‌شوند. استثنا: برچسب‌های BDO بدون تغییر کپی می‌شوند و عناصر دارای ویژگی DIR با یک SPAN دارای همان ویژگی DIR جایگزین می‌گردند. (BDO و DIR ممکن است در زبان‌های راست‌به‌چپ استفاده شوند.)
.SH "عملوندها (OPERANDS)"
عملوند زیر پشتیبانی می‌شود:
.TP 10
.I file-or-URL
نام یا نشانی اینترنتی (URL) یک پروندهٔ HTML. در صورت عدم درج، ورودی استاندارد خوانده می‌شود.
.SH "عیب‌یابی (DIAGNOSTICS)"
مقدارهای خروج زیر بازگردانده می‌شوند:
.TP 10
.B 0
اجرای موفقیت‌آمیز.
.TP
.B > 0
خطایی در پردازش پروندهٔ HTML رخ داده است.
.B hxtoc
تلاش خواهد کرد خطا را تصحیح کرده و در هر صورت خروجی را تولید کند.
.SH "همچنین ببینید (SEE ALSO)"
.BR asc2xml (1),
.BR hxnormalize (1),
.BR hxnum (1),
.BR xml2asc (1)
.SH "اشکالات (BUGS)"
.LP
بازیابی خطا برای HTML ناصحیح ابتدایی است.