HXINDEX(1) HTML-XML-utils HXINDEX(1)

hxindex - ایجاد نمایه الفبایی برای فایل‌های HTML/XML

hxindex [-t] [-x] [-n|-N] [-f] [-r] [-c class[,class...]] [-b base] [-i indexdb] [-s template] [-u phrase] [-O element[,element...]] [-X element[,element...]] [-A delimiters] [-S delimiters] [--] [file-or-URL]

برنامه hxindex در یک سند به دنبال اصطلاحاتی می‌گردد که باید نمایه شوند، آن‌ها را جمع‌آوری کرده، به لنگرهای مقصد تبدیل می‌کند و یک نمایه مرتب‌شده به شکل یک فهرست HTML می‌سازد که به جای متغیر جای‌نگهدار در سند درج می‌شود. سند حاصل در خروجی استاندارد نوشته می‌شود.

نمایه در محل یک کامنت به شکل زیر درج می‌شود:


<!--index-->

یا بین دو کامنت به شکل:


<!--begin-index-->
...
<!--end-index-->

در حالت دوم، تمام محتوای موجود بین این دو کامنت ابتدا حذف می‌شود.

اصطلاحات نمایه یا عناصری از نوع <dfn> هستند یا عناصری با ویژگی کلاس "index". (برای سازگاری با گذشته، ویژگی‌های کلاس "index-inst" و "index-def" نیز شناسایی می‌شوند.) عناصر <dfn> (و کلاس "index-def") مهم‌تر از عناصر با کلاس "index" در نظر گرفته می‌شوند و در نمایه تولیدشده به صورت توپر (بولد) نمایش می‌یابند.

گزینه -c کلاس‌های اضافی را به عنوان نام‌های مستعار برای "index" اضافه می‌کند.

به طور پیش‌فرض، محتوای عنصر به عنوان اصطلاح نمایه در نظر گرفته می‌شود. در زیر دو نمونه از وقوع اصطلاح نمایه "shoe" آمده است:


A <dfn>shoe</dfn> is a piece of clothing that...
completed by a leather <span class="index">shoe</span>...

اگر اصطلاحی که قرار است نمایه شود با محتوای عنصر برابر نباشد، می‌توان از ویژگی title برای ارائه اصطلاح صحیح استفاده کرد:


... <dfn title="shoe">Shoes</dfn> are pieces of clothing that...
... with two leather <span class="index" title="shoe">shoes</span>...

همچنین ویژگی title باید زمانی استفاده شود که اصطلاح نمایه یک زیر‌اصطلاح از اصطلاحی دیگر باشد. زیر‌اصطلاحات به صورت تورفته در نمایه و زیر اصطلاح اصلی خود نمایش می‌یابند. برای تعریف یک زیر‌اصطلاح، از ویژگی title به همراه دو علامت تعجب ("!!") بین اصطلاح و زیر‌اصطلاح استفاده کنید، مانند این:


<dfn title="shoe!!leather">...</dfn>
<dfn title="shoe!!invention of">...</dfn>
<em class="index" title="shoe!!protective!!steel nosed">...</em>

همان‌طور که مثال آخر در بالا نشان می‌دهد، می‌تواند چندین سطح از زیر-زیر‌اصطلاحات وجود داشته باشد.

ویژگی title همچنین اجازه می‌دهد چندین اصطلاح نمایه با یک مورد وقوع مرتبط شوند. اصطلاحات متعدد با یک خط عمودی ("|") از هم جدا می‌شوند. مثال‌های زیر را با مثال‌های بالا مقایسه کنید:


<dfn title="shoe|boot">...</dfn>
<dfn title="shoe!!invention of|inventions!!shoe">...</dfn>

هر دوی این عناصر دو اصطلاح را در نمایه درج می‌کنند. توجه داشته باشید که مثال دوم در بالا زیر‌اصطلاحات و چندین اصطلاح را با هم ترکیب می‌کند.

اجرای مجدد نمایه روی فایلی که از قبل دارای نمایه است امکان‌پذیر است. لنگرهای مقصد قدیمی و نمایه پیشین قبل از تولید مجدد حذف خواهند شد.

گزینه‌های زیر پشتیبانی می‌شوند:

به طور پیش‌فرض، hxindex یک ویژگی ID به عنصری که شامل وقوع یک اصطلاح است اضافه می‌کند و همچنین یک عنصر <a> درون آن با ویژگی name برابر با همان ID درج می‌کند. این کار به مرورگرهای قدیمی که ویژگی‌های ID را نادیده می‌گیرند (مانند Netscape 4) اجازه می‌دهد تا مقصد را پیدا کنند. گزینه -t از درج عنصر <a> جلوگیری می‌کند.
این گزینه قواعد نگارشی XML را فعال می‌کند: عناصر خالی به جای > در HTML، به /> ختم می‌شوند. گزینه -x به صورت ضمنی گزینه -t را نیز فعال می‌کند.
برنامه hxindex می‌تواند یک نمایه اولیه را از یک فایل بخواند و مجموعه ادغام‌شده اصطلاحات نمایه را مجدداً در همان فایل بنویسد. این قابلیت اجازه می‌دهد تا یک نمایه در میان چندین سند گسترش یابد. گزینه -i برای مشخص کردن نام فایلی که نمایه را نگه می‌دارد استفاده می‌شود.
این گزینه در ترکیب با -i برای مشخص کردن نشانی وب پایه (Base URL) مرجع سند مفید است. به طور پیش‌فرض، hxindex پیوندها به موارد وقوع را در فایل indexdb به صورت #anchor ذخیره می‌کند، اما هنگامی که -b داده شود، پیوندها به شکل base#anchor خواهند بود.
هنگامی که در ترکیب با -n استفاده شود، ویژگی‌های title پیوندها شامل عنوان سندی خواهد بود که اصطلاح در آن قرار دارد. عنوان قبل از template (الگو - گزینه -s را ببینید) درج شده و با یک کاما و یک فاصله از آن جدا می‌شود. برای مثال، اگر hxindex با دستور زیر فراخوانی شود: 


hxindex -i termdb -n -base myfile.html myfile.html

و فایل termdb از قبل شامل مدخلی برای "foo" در بخش "3.1" از سندی به نام "file2.html" با عنوان "The foos" باشد، نمایه تولیدشده حاوی مدخلی به این شکل خواهد بود:


foo, <a href="file2.html#foo"
  title="The foos, section 3.1">3.1</a>
اصطلاحات معمول نمایه با داشتن کلاسی برابر با "index" شناسایی می‌شوند. گزینه -c نام‌های کلاس اضافی و جداشده با کاما را اضافه می‌کند که به عنوان نام مستعار برای "index" در نظر گرفته می‌شوند. برای مثال، -c instance اطمینان حاصل می‌کند که <span class="instance">term</span> به عنوان یک اصطلاح برای نمایه شناخته شود.
به طور پیش‌فرض، نمایه شامل پیوندهایی با متن لنگر "#" است. گزینه -n باعث می‌شود متن پیوند از شماره بخش‌هایی تشکیل شود که اصطلاحات در آن‌ها رخ داده‌اند، و در صورتی که شماره بخشی پیدا نشود به عبارت "بدون شماره" (گزینه -u در زیر را ببینید) بازمی‌گردد. شماره بخش‌ها با جستجوی نزدیک‌ترین برچسب شروع پیشین با کلاس "secno" یا "no-num" پیدا می‌شوند. در حالت "secno"، محتوای آن عنصر به عنوان شماره بخش در نظر گرفته می‌شود. در حالت "no-num"، فرض می‌شود که بخش فاقد شماره است و hxindex به جای آن "بدون شماره" را چاپ می‌کند. این کلاس‌ها همچنین توسط hxnum(1) استفاده می‌شوند، بنابراین اجرای hxindex پس از hxnum مفید است؛ مانند: 


hxnum myfile.html | hxindex -n >mynewfile.html
با این گزینه، متن لنگر پیوندها در نمایه عنوان کامل بخشی است که اصطلاح در آن قرار دارد. عنوان بخش، نزدیک‌ترین عنصر H1، H2، H3، H4، H5 یا H6 پیشین است، یا اگر عنصر H* پیشینی وجود نداشته باشد، عنوان خود سند است. این گزینه نمی‌تواند همراه با -n استفاده شود. اگر هر دو استفاده شوند، آخرین گزینه مشخص‌شده اعمال می‌شود.
هنگامی که از گزینه -n استفاده می‌شود، پیوند دارای یک ویژگی title خواهد بود و template (الگو) محتوای آن را مشخص می‌کند. مقدار پیش‌فرض "section %s" است که در آن %s جای‌نگهداری برای شماره بخش است. به عبارت دیگر، نمایه شامل مدخل‌هایی مانند زیر خواهد بود: 


term, <a href="#term" title="section 7.8">7.8</a>
چند مثال: 


hxindex -n -s 'chapter %s'
hxindex -n -s 'part %s'
hxindex -n -s 'hoofdstuk %s' -u 'zonder nummer'
این گزینه فقط در ترکیب با گزینه -n مفید است.
هنگامی که گزینه -n برای نمایش شماره بخش‌ها استفاده می‌شود، مراجعی که هیچ شماره بخشی برای آن‌ها یافت نشود به جای آن به صورت phrase (عبارت مشخص‌شده) نمایش داده می‌شوند. مقدار پیش‌فرض "??" است.
این گزینه فقط در ترکیب با گزینه -n مفید است.
حذف ویژگی‌های title که برای نمایه استفاده شده‌اند و همچنین کامنت‌هایی که نمایه درج‌شده را محدود می‌کنند. این کار از نمایش این ویژگی‌ها توسط مرورگرها جلوگیری می‌کند. توجه داشته باشید که اگر از این گزینه استفاده شود، hxindex را نمی‌توان دوباره روی خروجی خودش اجرا کرد. (یادآور: "freeze" یا "final").
هنگام مرتب‌سازی اصطلاحات نمایه، علائم نگارشی انتهایی را نادیده نگیرید. برای مثال، اگر دو اصطلاح به صورت زیر نوشته شده باشند: 


<dfn>foo,</dfn>... <span class=index>foo</span>

برنامه hxindex به طور معمول کاما را نادیده می‌گیرد و با آن‌ها به عنوان یک اصطلاح یکسان رفتار می‌کند، اما با گزینه -r، آن‌ها متفاوت در نظر گرفته می‌شوند. این امر بر کاماهای انتهایی (,)، نقطه‌ویرگول (;)، دونقطه (:)، علامت تعجب (!)، علامت سوال (؟) و نقطه (.) تاثیر می‌گذارد. اگر دو یا چند نقطه در اصطلاح وجود داشته باشد، نقطه پایانی هرگز نادیده گرفته نمی‌شود تا از مخفف‌ها ("B.C.") و نشانه‌های تعلیق ("...more") محافظت شود. این گزینه بر نحوه چاپ اصطلاح نمایه تاثیری نمی‌گذارد (همیشه همان‌طور که در متن آمده چاپ می‌شود)، بلکه فقط بر نحوه مقایسه آن با اصطلاحات مشابه اثر می‌گذارد. (یادآور: "raw").

اگر -O مشخص شده باشد، تنها عناصر با نام‌های داده‌شده نمایه می‌شوند. برای مثال: 


hxindex -O span,i,em

بدین معناست که hxindex تنها به دنبال ویژگی class="index" (و سایر کلاس‌ها بر اساس -c) روی عناصر span، i و em می‌گردد. آرگومان گزینه -O باید فهرستی از نام‌های عناصر باشد که با کاما از هم جدا شده‌اند. توجه داشته باشید که این موضوع بر عنصر dfn تاثیری ندارد؛ این عنصر همیشه به عنوان یک نمونه تعریف‌کننده نمایه خواهد شد.

گزینه -X عناصر مشخص‌شده را از نمایه‌سازی مستثنی می‌کند. برای مثال: 


hxindex -X ul,ol

اطمینان حاصل می‌کند که عناصر ul و ol حتی اگر ویژگی class="index" داشته باشند، نمایه نشوند. این گزینه فرزندان آن‌ها را از نمایه‌سازی مستثنی نمی‌کند. برای مثال:


<ul class=index>
 <li class=index>foo
 <li class=index>bar
 <li>baz
</ul>

موارد foo و bar را به نمایه اضافه می‌کند، اما کل محتوای عنصر ul را که (foo bar baz) است اضافه نمی‌کند. اگر هر دو گزینه -O و -X داده شوند و یک عنصر در هر دو گزینه وجود داشته باشد، مستثنی خواهد شد. برای مثال:


hxindex -X p,h1,ul -O em,span,h1,h2

باعث می‌شود که hxindex فقط به دنبال ویژگی‌های کلاس روی عناصر em، span و h2 بگردد، زیرا h1 مستثنی شده است.

فهرستی از رشته‌های جداشده با فاصله که اصطلاحات متعدد را از هم جدا می‌کنند. مقدار پیش‌فرض "|" است. توجه داشته باشید که هنگام استفاده از این گزینه در خط فرمان، فاصله‌ها باید درون نقل‌قول قرار گیرند تا از تفسیر آن‌ها توسط پوسته جلوگیری شود.
فهرستی از رشته‌های جداشده با فاصله که زیر‌اصطلاحات را از هم جدا می‌کنند. مقدار پیش‌فرض "!! ::" است، یعنی دو رشته "!!" و "::". توجه داشته باشید که هنگام استفاده از این گزینه در خط فرمان، فاصله‌ها باید درون نقل‌قول قرار گیرند تا از تفسیر آن‌ها توسط پوسته جلوگیری شود.

عملوند زیر پشتیبانی می‌شود:

نام یک فایل HTML یا XML یا نشانی وب (URL) آن. در صورت عدم وجود، یا اگر فایل "-" باشد، ورودی استاندارد خوانده می‌شود.

مقادیر خروج زیر بازگردانده می‌شوند:

0
اجرای موفقیت‌آمیز.
>0
خطایی در تجزیه فایل HTML رخ داده است.

فرض می‌شود که ورودی با کدگذاری UTF-8 است، اما از لوکال جاری سیستم برای تعیین ترتیب مرتب‌سازی اصطلاحات نمایه استفاده می‌شود؛ یعنی hxindex به متغیرهای محیطی LANG، LC_ALL و/یا LC_COLLATE نگاه می‌کند. locale(1) را ببینید.

برای استفاده از یک پروکسی جهت دریافت فایل‌های راه دور، متغیرهای محیطی http_proxy یا ftp_proxy را تنظیم کنید؛ مانند:


http_proxy="http://localhost:8080"

ورودی را با کدگذاری UTF-8 فرض می‌کند. موجودیت‌های نویسه‌ای (به جز موارد استاندارد: "&amp;"، "&lt;"، "&gt;" و "&quot;") را باز نمی‌کند. در عوض، ورودی را از طریق hxunent(1) و در صورت نیاز asc2xml(1) هدایت (pipe) کنید تا به UTF-8 تبدیل شود.

فایل‌های راه دور (مشخص‌شده با URL) در حال حاضر تنها برای پروتکل HTTP پشتیبانی می‌شوند. فایل‌های محافظت‌شده با رمز عبور یا فایل‌هایی که به کوکی‌های ("cookies") پروتکل HTTP وابسته‌اند مدیریت نمی‌شوند. (می‌توانید از ابزارهایی مانند curl(1) یا wget(1) برای دریافت چنین فایل‌هایی استفاده کنید.)

دسترس‌پذیری نمایه تولیدشده، حتی هنگامی که با گزینه -n ایجاد شده باشد، ضعیف است.

asc2xml(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1), hxunent(1), xml2asc(1), locale(1), UTF-8 (RFC 2279)

10 Jul 2011 7.x