نام (NAME)

makeindex - قالب‌بندی و ساخت نمایه‌های الفبایی برای TeX یا troff

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

makeindex [-c] [-g] [-i] [-l] [-o ind] [-p num] [-q] [-r] [-s sfile] [-t log] [-L] [-T] [idx0 idx1 idx2...]

توضیحات (DESCRIPTION)

برنامه makeindex یک سازنده نمایه سلسله‌مراتبی با کاربرد عمومی است؛ این برنامه یک یا چند فایل ورودی (که اغلب توسط یک قالب‌بندی‌کننده متن مانند TeX (tex(1L)) یا troff(1) تولید شده‌اند) را دریافت می‌کند، مدخل‌ها را مرتب می‌سازد، و یک فایل خروجی تولید می‌نماید که قابل قالب‌بندی است. نمایه می‌تواند تا سه سطح (۰، ۱ و ۲) از تو در تویی زیرمدخل‌ها را داشته باشد. نحوه نشانه‌گذاری کلمات برای نمایه‌سازی در سند اصلی، وابسته به قالب‌بندی‌کننده مورد استفاده است؛ makeindex فرآیند انتخاب این کلمات را خودکار نمی‌کند. از آنجا که نمایه خروجی سلسله‌مراتبی است، makeindex می‌تواند مکمل سیستم make.index(1L) مبتنی بر awk(1) اثر بنتلی و کرنیهان تلقی شود که مختص troff(1) بوده، نمایه‌های غیرسلسله‌مراتبی تولید می‌کند و ساختار نحوی بسیار ساده‌تری را برای تعیین مدخل‌های نمایه به کار می‌گیرد. برای مشاهده نمونه‌های استفاده همراه با troff و TeX، بخش مثال‌ها (EXAMPLES) در ادامه را ببینید.

قالب فایل‌های ورودی و خروجی در یک فایل شیوه‌نامه مشخص می‌شود؛ به‌طور پیش‌فرض، فرض می‌شود ورودی یک فایل با پسوند .idx است، همان‌گونه که توسط LaTeX تولید می‌شود.

مگر در صورت تعیین صریح، نام پایه اولین فایل ورودی (idx0) برای تعیین نام فایل‌های دیگر استفاده می‌شود. برای هر نام فایل ورودی مشخص‌شده، فایلی با همان نام جستجو می‌شود. اگر این فایل پیدا نشود و نام فایل پسوندی نداشته باشد، پسوند .idx افزوده می‌شود. اگر هیچ فایلی با این نام یافت نشود، makeindex متوقف می‌شود.

اگر دقیقاً یک فایل ورودی داده شده باشد و هیچ فایل شیوه‌نامه صریحی با استفاده از -s مشخص نشده باشد، makeindex از فایلی با پسوند .mst به عنوان فایل شیوه‌نامه پیش‌فرض (در صورت وجود) استفاده می‌کند.

برای نکات مهم در رابطه با چگونگی انتخاب کلیدواژه‌های نمایه، سند لمپورت که در ادامه به آن ارجاع داده شده را ببینید. به عنوان موضوعی مجزا از انتخاب کلیدواژه‌های نمایه، یک سازوکار روش‌مند برای قرار دادن اصطلاحات نمایه در سند در مقاله Index Preparation and Processing که در ادامه ذکر شده، پیشنهاد گردیده است.

گزینه‌ها (OPTIONS)

-c

فشرده‌سازی فاصله‌های خالی میانی (نادیده گرفتن فاصله‌های خالی و تب‌ها در ابتدا و انتهای خط). به‌طور پیش‌فرض، فاصله‌های خالی در کلید نمایه حفظ می‌شوند.

-g

به کار بردن ترتیب کلمات آلمانی در نمایه، مطابق با قواعد تعیین‌شده در DIN 5007. به‌طور پیش‌فرض، makeindex از ترتیب کلماتی استفاده می‌کند که در آن اولویت عبارت است از: نمادها، اعداد، حروف بزرگ، حروف کوچک. این ترتیب در چینش کلمات آلمانی بدین صورت است: نمادها، حروف کوچک، حروف بزرگ، اعداد. علاوه بر این، این گزینه makeindex را قادر می‌سازد تا در طول مرتب‌سازی مدخل‌ها، دستورهای آلمانی TeX شامل {"a, "o, "u و "s} را به صورت {ae, oe, ue و ss} تشخیص دهد. نویسه نقل‌قول باید در یک فایل شیوه‌نامه بازتعریف شود (برای مثال، بازتعریف نقل‌قول به صورت '+'). اگر نویسه نقل‌قول بازتعریف نشود، makeindex یک پیام خطا تولید کرده و متوقف می‌شود.

-i

دریافت ورودی از stdin. هنگامی که این گزینه مشخص شود و -o تعیین نشده باشد، خروجی در stdout نوشته می‌شود.

-l

ترتیب حرف‌به‌حرف؛ به‌طور پیش‌فرض، از ترتیب کلمه‌به‌کلمه استفاده می‌شود (بخش مرتب‌سازی (ORDERING) را ببینید).

-o ind

استفاده از ind به عنوان فایل نمایه خروجی. به‌طور پیش‌فرض، نام فایل با افزودن پسوند .ind به نام پایه اولین فایل ورودی (idx0) ساخته می‌شود.

-p num

تنظیم شماره صفحه شروع فایل نمایه خروجی بر روی num (کاربردی هنگامی که فایل نمایه باید به‌طور جداگانه قالب‌بندی شود). آرگومان num می‌تواند عددی یا یکی از موارد زیر باشد:

آخرین صفحه منبع با جستجوی رو به عقب در فایل لاگ به دنبال اولین نمونه از عددی که در جفت براکت ([...]) قرار دارد به دست می‌آید. اگر شماره صفحه‌ای وجود نداشته باشد یا فایل لاگ پیدا نشود، هیچ تلاشی برای تنظیم شماره صفحه شروع انجام نخواهد شد. نام فایل لاگ منبع با افزودن پسوند .log به نام پایه اولین فایل ورودی (idx0) تعیین می‌شود.

-q

حالت بی‌صدا؛ هیچ پیامی به stderr ارسال نمی‌شود. به‌طور پیش‌فرض، پیام‌های پیشرفت و خطا به stderr و همچنین به فایل گزارش (transcript) فرستاده می‌شوند.

-r

غیرفعال کردن تشکیل ضمنی بازه صفحات؛ بازه‌های صفحات باید با استفاده از عملگرهای صریح بازه ایجاد شوند؛ بخش جلوه‌های ویژه (SPECIAL EFFECTS) در ادامه را ببینید. به‌طور پیش‌فرض، سه یا چند صفحه متوالی به‌طور خودکار به صورت یک بازه خلاصه می‌شوند (مانند 1—5).

-s sty

استفاده از sty به عنوان فایل شیوه‌نامه (بدون پیش‌فرض). متغیر محیطی INDEXSTYLE مسیری را مشخص می‌کند که فایل شیوه‌نامه باید در آن پیدا شود.

-t log

استفاده از log به عنوان فایل گزارش (transcript). به‌طور پیش‌فرض، نام فایل با افزودن پسوند .ilg به نام پایه اولین فایل ورودی (idx0) ساخته می‌شود.

-L

مرتب‌سازی بر اساس تنظیمات محلی (locale). در همه سیستم‌ها در دسترس نیست.

-T

پشتیبانی ویژه از اسناد تایلندی. در همه سیستم‌ها در دسترس نیست.

فایل شیوه‌نامه (STYLE FILE)

فایل شیوه‌نامه، makeindex را از قالب فایل‌های ورودی .idx و قالب مورد نظر برای فایل خروجی نهایی مطلع می‌سازد؛ نمونه‌هایی از آن در ادامه آمده است. این فایل می‌تواند در هر مکانی در مسیر تعریف‌شده توسط متغیر محیطی INDEXSTYLE قرار گیرد. فایل شیوه‌نامه شامل فهرستی از جفت‌های <specifier, attribute> است. دو نوع مشخص‌کننده وجود دارد: ورودی و خروجی. نیازی نیست جفت‌ها با ترتیب خاصی قرار گیرند. خطی که با «%» آغاز شود یک توضیح (کامنت) است. در فهرست زیر از مشخص‌کننده‌ها و آرگومان‌ها، <string> یک رشته دلخواه است که با علامت نقل‌قول جفتی ("...") محدود شده است، <char> یک نویسه منفرد در میان علامت نقل‌قول تکی ('...') است، و <number> یک عدد صحیح غیرمنفی است. حداکثر طول یک <string> برابر ۲۰۴۸ است. یک بک‌اسلش یا علامت نقل‌قول صریح باید (با یک بک‌اسلش) اسکیپ شود. هر آنچه در فایل شیوه‌نامه مشخص نشود، یک مقدار پیش‌فرض دریافت خواهد کرد که در بالای ستون سمت راست نمایش داده شده است.

مثال‌ها (EXAMPLES)

preamble
"\\documentstyle[12pt]{book}
\\begin{document}
\\begin{theindex}
{\\small\n"
postamble
"\n\n}
\\end{theindex}
\\end{document}\n"

keyword "IX:"
preamble
".\\\" start of index output
\".\\\" enter two column mode
.2C
.SH
.ce
INDEX
.XS
INDEX
.XE
.R
.ps 9p
.vs 11p
.sp
.de I1
.ti 0.25i
..
.de I2
.ti 0.5i
.."
postamble "\n.\\\" end of index output"
setpage_prefix "\n.nr % "
setpage_suffix ""
group_skip "\n.sp 1.0"
headings_flag 1
heading_prefix "\n.IS\n"
heading_suffix "\n.IE"
item_0 "\n.br\n"
item_1 "\n.I1\n"
item_2 "\n.I2\n"
item_01 "\n.I1\n"
item_x1 "\n.I1\n"
item_12 "\n.I2\n"
item_x2 "\n.I2\n"
delim_0 ", "
delim_1 ", "
delim_2 ", "
delim_r "-"
delim_t "."
encap_prefix "\\fB"
encap_infix ""
encap_suffix "\\fP"
indent_space ""
indent_length 0

.
.de IX
.ie '\\n(.z'' .tm IX: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
..

This is a sample file to test the \fImakeindex\fP(1L)
program, and see
.IX {indexing!programs!C language}
.IX {makeindex@\fImakeindex\fP(1L)}
.bp
.rs
.IX {Knuth}
.IX {typesetting!computer-aided}
how well it functions in the \fItroff\fP(1) environment.

psroff -ms -Tpsc -t sample.txt > /dev/null 2> sample.tmp

psroff -ms -I sample.inp -Tpsc -t sample.txt > /dev/null

ترتیب‌بندی (ORDERING)

به‌طور پیش‌فرض، makeindex حالت ترتیب کلمه‌ای (word ordering) را در نظر می‌گیرد؛ اگر گزینه -l فعال باشد، ترتیب حرفی (letter ordering) به کار می‌رود. در ترتیب کلمه‌ای، یک فاصله خالی بر هر حرف الفبا تقدم دارد، در حالی که در ترتیب حرفی، فاصله اصلاً به حساب نمی‌آید. این موضوع در مثال زیر نشان داده شده است:

اعداد همیشه به ترتیب عددی مرتب می‌شوند. برای مثال،

حروف ابتدا بدون در نظر گرفتن بزرگی و کوچکی مرتب می‌شوند؛ هنگامی که کلمات یکسان باشند، نسخه با حروف بزرگ بر همتای با حروف کوچک خود تقدم دارد.

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

جلوه‌های ویژه (SPECIAL EFFECTS)

مدخل‌هایی مانند

\indexentry{alpha}{1}
\indexentry{alpha!beta}{3}
\indexentry{alpha!beta!gamma}{10}

در فایل ورودی، تبدیل خواهند شد به

\item alpha, 1
   \subitem beta, 3
      \subsubitem gamma, 10

در فایل نمایه خروجی. توجه داشته باشید که نماد level (یعنی `!') در بالا برای تعیین مرز سطوح سلسله‌مراتبی استفاده شده است.

می‌توان با استفاده از عملگر actual (یعنی `@')، کاری کرد که یک مدخل به شکلی مشخص نمایش یابد. برای نمونه،

پس از پردازش تبدیل خواهد شد به

الگوی پیش از `@' به عنوان کلید مرتب‌سازی به کار می‌رود، در حالی که الگوی پس از آن در فایل خروجی نوشته می‌شود. توجه کنید دو مورد از یک کلید یکسان، یکی با عملگر actual و دیگری بدون آن، به عنوان مدخل‌های متمایز در نظر گرفته می‌شوند.

فیلدهای item، subitem و subsubitem می‌توانند کلیدهای مرتب‌سازی مجزایی داشته باشند:

\indexentry{aa@{\it aa\/}!bb@{\it bb\/}!cc@{\it cc\/}}{1}

این مورد تبدیل خواهد شد به

\item {\it aa}, 1
   \subitem {\it bb}, 3
      \subsubitem {\it cc}, 10

با استفاده از عملگر encap (یعنی `|') می‌توان شماره صفحه را در یک دستور مشخص کپسوله‌سازی کرد:

تبدیل خواهد شد به

که در آن با تعریفی مناسب برای TeX، عبارت \bold{n} به {\bf n} بسط می‌یابد. در این مثال، سه ویژگی خروجی مرتبط با کپسوله‌سازی شماره صفحه، یعنی encap_prefix، encap_infix و encap_suffix، به ترتیب متناظر با بک‌اسلش، آکولاد باز و آکولاد بسته هستند. این سازوکار امکان درج شماره صفحات با قلم‌های مختلف را فراهم می‌سازد. برای مثال، صفحه‌ای که تعریف یک کلیدواژه در آن آمده می‌تواند با یک قلم، محل یک مثال اصلی با قلمی دیگر و سایر موارد با قلم سومی چاپ شوند.

از عملگر encap همچنین می‌توان برای ایجاد ارجاع‌های متقابل در نمایه استفاده کرد:

در فایل خروجی تبدیل خواهد شد به

که در آن

بسط خواهد یافت به

توجه داشته باشید که در چنین ارجاع متقابلی، شماره صفحه حذف می‌شود.

یک جفت encap پیوسته با range_open (یعنی `|(') و range_close (یعنی `|)') یک محدوده صفحه صریح ایجاد می‌کند:

\indexentry{alpha|(}{1}
\indexentry{alpha|)}{5}

تبدیل خواهد شد به

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

\indexentry{alpha|(bold}{1}
\indexentry{alpha|)}{5}

تبدیل خواهد شد به

چندین مشکل احتمالی شایان ذکر است. نخست، مدخل‌هایی مانند

\indexentry{alpha|(}{1}
\indexentry{alpha|bold}{3}
\indexentry{alpha|)}{5}

به این صورت تفسیر خواهند شد:

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

\indexentry{alpha|(}{i}
\indexentry{alpha}{iv}
\indexentry{alpha}{3}
\indexentry{alpha|)}{7}

تبدیل خواهد شد به

همراه با یک پیام هشدار در فایل رونوشت (transcript) مبنی بر تشکیل محدوده غیرمجاز.

تمام نمادهای ویژه‌ای که در این بخش به آن‌ها اشاره شد، می‌توانند با عملگر quote («"») اسکیپ شوند. بدین ترتیب

در واقع به

در نتیجه اجرای makeindex تبدیل خواهد شد. قابلیت نقل‌قول عملگر quote در صورتی که بلافاصله پس از escape («\») بیاید، از بین می‌رود. به عنوان مثال،

به

تبدیل می‌شود که برای خانواده پردازشگرهای TeX نشان‌دهنده یک حرف «u» با نشان اوملاوت است.

شماره صفحه می‌تواند ترکیبی از یک یا چند فیلد باشد که با جداکننده مقید به page_compositor («-») از هم جدا شده‌اند؛ مانند II-12 برای صفحه ۱۲ از فصل II. شماره‌های صفحه می‌توانند تا ۱۰ فیلد داشته باشند.

از نگارش ۲.۱۱ برنامه makeindex، عملگر quote می‌تواند هر نویسه‌ای در محدوده ۱ ... ۲۵۵ را اسکیپ کند. نویسه ۰ مستثنی است زیرا به صورت داخلی در کد منبع makeindex به عنوان پایان‌دهنده رشته استفاده می‌شود. با این تغییر، کلیدهای مرتب‌سازی را می‌توان برای تمامی نویسه‌های هشت‌بیتی به جز ۰ ایجاد کرد. ترتیب مرتب‌سازی به این صورت است:

نویسه‌های نشانه‌گذاری (به ترتیب اسکی)،
ارقام،
نویسه‌های کنترلی (۱ ... ۳۱)،
فاصله (۳۲)،
حروف (بدون در نظر گرفتن بزرگی و کوچکی)،
نویسه‌های ۱۲۷ ... ۲۵۵.

\indexentry{" @"  (space)}{32}
\indexentry{"!@"! (exclamation point)}{33}
\indexentry{""@"" (quotation mark)}{34}
\indexentry{"#@"\# (sharp sign)}{35}
\indexentry{"$@"\$ (dollar sign)}{36}
\indexentry{"%@"\% (percent sign)}{37}
\indexentry{"&@"\& (ampersand)}{38}
\indexentry{"<@"$<$ (left angle bracket)}{60}
\indexentry{"=@"= (equals)}{61}
\indexentry{">@"$>$ (right angle bracket)}{62}
\indexentry{"?@"? (query)}{63}
\indexentry{"@@"@ (at sign)}{64}
\indexentry{"[@"[ (left square bracket)}{91}
\indexentry{"\@"\verb=\= (backslash)}{92}
\indexentry{"]@"] (right square bracket)}{93}
\indexentry{"^@"\verb=^= (caret)}{94}
\indexentry{"_@"\verb=_= (underscore)}{95}
\indexentry{"`@"\verb=~= (grave accent)}{96}
\indexentry{"{@"\"{ (left brace)}{123}
\indexentry{"|@"\verb="|= (vertical bar)}{124}
\indexentry{"}@"\"} (right brace)}{125}
\indexentry{"~@"\verb=~= (tilde)}{126}

\begin{theindex}
  \item ! (exclamation point), 33
  \item " (quotation mark), 34
  \item \# (sharp sign), 35
  \item \$ (dollar sign), 36
  \item \% (percent sign), 37
  \item \& (ampersand), 38
  \item $<$ (left angle bracket), 60
  \item = (equals), 61
  \item $>$ (right angle bracket), 62
  \item ? (query), 63
  \item @ (at sign), 64
  \item [ (left square bracket), 91
  \item \verb=\= (backslash), 92
  \item ] (right square bracket), 93
  \item \verb=^= (caret), 94
  \item \verb=_= (underscore), 95
  \item \verb=~= (grave accent), 96
  \item \{ (left brace), 123
  \item \verb=|= (vertical bar), 124
  \item \} (right brace), 125
  \item \verb=~= (tilde), 126
  \indexspace
  \item   (space), 32
\end{theindex}

فایل‌ها (FILES)

makeindex

فایل اجرایی

$TEXMFMAIN/tex/plain/makeindex/idxmac.tex

فایل ماکروی TeX استفاده شده توسط makeindex

$TEXMFMAIN/tex/latex/base/makeidx.sty

فایل ماکروی TeX استفاده شده توسط makeindex

همچنین ببینید (SEE ALSO)

ditroff(1L), latex(1L), make.index (1L), qsort(3), tex(1L), troff(1L)

UCSF Enhanced troff/TRANSCRIPT — An Overview, R. P. C. Rodgers and Conrad Huang, LSMB Technical Report 90-2, UCSF School of Pharmacy, San Francisco, 1990.

Index Preparation and Processing, Pehong Chen and Michael A. Harrison, Software: Practice and Experience, 19(9), 897–915, September 1988.

Automating Index Preparation, Pehong Chen and Michael A. Harrison. Technical Report 87/347, Computer Science Division, University of California, Berkeley, 1987 (یک سند LaTeX ارائه شده همراه با makeindex).

MakeIndex: An Index Processor for LaTeX, Leslie Lamport, February 1987 (یک سند LaTeX ارائه شده همراه با makeindex).

Tools for Printing Indices, Jon L. Bentley and Brian W. Kernighan, Electronic Publishing — Origination, Dissemination, and Design, 1(1), 3–18, June 1988 (همچنین در دسترس به صورت: Computing Science Technical Report No. 128, AT&T Bell Laboratories, Murray Hill, NJ 07974, 1986).

نویسنده (AUTHOR)

Pehong Chen, Chen & Harrison International Systems, Inc. Palo Alto, California, USA.
صفحه راهنما به طور گسترده توسط Rick P. C. Rodgers از UCSF School of Pharmacy بازبینی و تصحیح شده و مثال‌های troff(1) توسط او ایجاد گردیده‌اند.

سپاسگزاری‌ها (ACKNOWLEDGMENTS)

Leslie Lamport سهم بسزایی در طراحی MakeIndex داشت. Michael Harrison نظرات و پیشنهادات ارزشمندی ارائه کرد. Nelson Beebe نسخه پرتابل را بهبود بخشید و توزیع منبع را برای سال‌های متمادی برای گروه کاربران TeX نگهداری کرد. Andreas Brosig در ترتیب کلمات آلمانی مشارکت داشت. اصلاح ماکروهای -ms از روش پیشنهادی Ravi Sethi از آزمایشگاه‌های AT&T Bell برگرفته شد. فایل‌های LOG و CONTRIB در توزیع کد منبع makeindex سایر مشارکت‌ها را ثبت کرده‌اند.

makeindex در حال حاضر به عنوان بخشی از توزیع TeX Live نگهداری می‌شود (https://tug.org/texlive)؛ لطفاً گزارش‌های اشکال را به tex-k@tug.org ارسال کنید.