(Prawie) wszystko o skorowidzach: plmindex (makeindex)

Spis tre�ci

Wst�p
Schemat przetwarzania
Tworzenie zbioru hase�
Przetwarzanie zbioru hase�
Skorowidz wielopoziomowy
Zmiana kolejno�ci sortowania
Odsy�acze w skorowidzu, efekty dodatkowe
Grupowanie numer�w stron
Znaki specjalne
Definiowanie postaci skorowidza
U�ywane polecenia
Definiowanie zbioru polece�
Opcje programu

Wst�p

 Ka�da powa�na publikacja o charakterze naukowo-technicznym powinna posiada� skorowidz (indeks), czyli uporz�dkowany wykaz u�ywanych, b�d� definiowanych poj��, zawieraj�cy informacje na jakich stronach s� one u�ywane.

Jedn� z zalet TeX-a jest mo�liwo�� automatycznego tworzenia zbior�w dodatkowych, zawieraj�cych informacje zwi�zane z przetwarzanym tekstem. Utworzony zbi�r mo�emy przetworzy� innym programem; przy ponownym uruchomieniu TeX-a mo�e on zosta� do��czony do dokumentu podstawowego.

Do porz�dkowania zbioru hase� s�u�y program plmindex (lub makeindex). Opisuj�c proces tworzenia skorowidza powo�uj� si� na swoj� implementacj�; program plmindex, czyli Polish (Multilanguage) index. Program mo�e by� zastosowany do budowy skorowidza w polskich publikacjach. Dok�adny opis w�asno�ci programu plmindex znajduje si� w nast�pnym artykule tego cyklu.

Schemat przetwarzania

Tworzenie skorowidza w dokumencie przetwarzanym TeX-em zosta�o zrealizowane wed�ug powy�szego schematu zilustrowanego rysunkiem:


Po pierwszym przetwarzaniu dokumentu otrzymujemy zbi�r dodatkowy z rozszerzeniem .idx (podstawowy trzon nazwy jest identyczny z nazw� dokumentu). Zawiera on wszystkie has�a, definiowane w dokumencie �r�d�owym za pomoc� polecenia \index. W celu zainicjowania zbioru hase� nale�y wywo�a� polecenie \plmindex

Podstawow� rol� programu plmindex jest uporz�dkowanie i posortowanie zbioru hase� wygenerowanego przez pakiet LaTeX-a. Uporz�dkowany zbi�r skorowidza do��czamy do dokumentu podstawowego poleceniem \printindex. Standardowo zbi�r ten ma rozszerzenie .ind.

Tworzenie zbioru hase�

Niezb�dny zestaw polece� w dokumencie umo�liwiaj�cy utworzenie i do��czenie skorowidza: 
\documentclass{article}
\usepackage{makeidx}
\makeindex
\begin{document}
.
.
.
..... bqq\index{bqq}
        .... aqq\index{aqq}
.
.
.
\printindex
\end{document}
Po przetworzeniu pakietem LaTeX2e otrzymamy nast�puj�cy zbi�r skorowidza: 
\indexentry{bqq}{1}
\indexentry{aqq}{1}

Poszczeg�lne has�a sa definiowane poleceniem \index{...}. Najwygodniej jest umieszcza� polecenia tworz�ce has�a w momencie pisania dokumentu. Trudno sobie wyobrazi� automat wprowadzaj�cy wskazane s�owa do skorowidza, poniewa� has�a powinny wyst�powa� w swojej podstawowej formie (np. rzeczowniki w mianowniku), a nie w formie wynikaj�cej z kontekstu; pozostaje ,,r�czne'' definiowanie has�a przy okazji jego istotnego wyst�pienia.

W zbiorze hase� ka�de zdefiniowane poj�cie jest umieszczane jako pierwszy argument polecenia \indexentry, drugim argumentem jest numer strony na kt�rej ono wyst�pi�o (wg. aktualnego formatu pisania numer�w stron). Nale�y dba� o to, aby mi�dzy wyst�pieniem danego has�a, a poleceniem wprowadzaj�cym je do skorowidza nie nast�pi�o przej�cie do nowej strony.

definicja b��dna definicja poprawna
aqq \index{aqq} aqq\index{aqq}

Przetwarzanie zbioru hase�

Zbi�r zawieraj�cy list� wszystkich hase� nale�y przetworzy� programem plmindex. W najprostszym przypadku linia wywo�ania programu wygl�da nast�puj�co: 
plmindex zbi�r
Has�a definiowane w zbiorze zbi�r.idx zostan� pogrupowane (usuni�te wielokrotne definicje na tej samej stronie) oraz posortowane i zapisane do zbioru zbi�r.ind. W naszym przyk�adzie, uporz�dkowany zbi�r (rozszerzenie .ind) b�dzie wygl�da� nast�puj�co: 
\begin{theindex}

  \item aqq, 1

  \indexspace

  \item bqq, 1

\end{theindex}
Podczas powt�rnego przetwarzania dokumentu pakietem LaTeX2e, powy�szy zbi�r zostanie do��czony w miejscu wyst�pienia polecenia \printindex.

Skorowidz wielopoziomowy

 Program plmindex pozwala na zdefiniowanie tr�jpoziomowej struktury has�a. Znakiem odzielaj�cym poziomy jest ! (wykrzyknik). Przyk�adowe polecenia: 
krowa\index{ssaki!parzysto-kopytne!krowa}
ko�\index{ssaki!nieparzysto-kopytne!ko�}
tapir\index{ssaki!nieparzysto-kopytne!tapir}
s� ssakami\index{ssaki}
okre�lenia: parzysto-kopytne i nieparzysto-kopytne s� has�ami podrz�dnymi has�a ssaki i samodzielnie nie wyst�puj� (nie s� definiowane w spos�b jawny). Nazwy krowa, ko� i tapir stanowi� najni�szy poziom.

Po przetworzeniu programem plmindex zbi�r .ind wygl�da nast�puj�co: 

\begin{theindex}

  \item ssaki, 1
    \subitem nieparzysto-kopytne
      \subsubitem ko�, 1
      \subsubitem tapir, 1
    \subitem parzysto-kopytne
      \subsubitem krowa, 1

\end{theindex}
Numery stron s� umieszczane tylko wtedy je�li has�o jest wprowadzone w spos�b jawny do indeksu (np. has�o parzysto-kopytne zostanie utworzone automatycznie, i nie zostanie opatrzone numerem strony).

Ostatecznie po wydrukowaniu powy�szy fragment skorowidza wygl�da nast�puj�co:

Zmiana kolejno�ci sortowania

Czasami zdarza si�, �e has�o powinno by� umieszczone w innym miejscu ni� wynika to z porz�dku leksykograficznego (np. polecenie TeX-a poprzedzone znakiem \ umieszczamy w miejscu wynikaj�cym z nazwy polecenia, ignoruj�c znak \). W tym wypadku polecenie \index ma nast�puj�c� skladni�: 
\index{has�o do sortowania@has�o do indeksu}
okre�lenie has�o do sortowania s�u�y programowi plmindex jako wzorzec do nadania porz�dku leksykograficznego, natomiast has�o do indeksu znajdzie si� w spisie. W przypadku hase� wielopoziomowych polecenie mo�e wygl�da� nast�puj�co: 
\index{sort@index!sort-1@index-1!sort-2@index-2}
Innym powodem u�ycia tej konstrukcji mo�e by� ch�� zmiany kroju pisma jakim sk�adane jest dane has�o (np. wyr�nienie s�owa kluczowego): 
\index{alfa@{\itshape alfa}}
Zbi�r .ind wygl�da nast�puj�co: 
\begin{theindex}

  \item {\itshape alfa}, 1

\end{theindex}

Odsy�acze w skorowidzu, efekty dodatkowe

 Definiuj�c has�o skorowidza, mo�emy w tym momencie zwr�ci� uwag� czytelnika na inne has�o, s�u�y do tego operator encapsulacji, kt�rym jest znak |.
Przyk�ad: 
\def\seename{p.}
\def\see#1#2{#2, ({\itshape \seename~#1}\/)}

aqq\index{aqq|see{bqq}}
da nam nast�puj�ce has�o w skorowidzu: 

  \item aqq, \see{bqq}{1}
kt�re w dokumencie wynikowym, b�dzie wygl�da�o nast�puj�co:
aqq, 1, (p. bqq)
�atwo wida�, �e napis po znaku | jest traktowany jako makropolecenie (jego argumentem aktualnym jest zawsze numer strony). W przypadku konstrukcji see definiowany jest w�asny parametr okre�laj�cy has�o podobne -- parametr drugi (numer strony) jest pobierany z listy parametr�w aktualnych, ale nie jest wykorzystywany (w przeciwnym wypadku pojawi�by si� jako blok {1}.

Za pomoc� enkapsulacji mo�na zrealizowa� rozr�nianie typu wyst�puj�cego has�a, np. miejsce definicji odr�niamy od normalnego wyst�pienia u�yciem innej czcionki przy podawaniu numeru strony; i tak:

italic has�o u�ywane w przyk�adzie
bold miejsce zdefniowania poj�cia
pozosta�e sk�adane czcionk� standardow�
Przyk�ad: 
\def\italic#1{{\itshape #1}}
\def\bold#1{{\bfseries #1}}

\def\idxb#1{\index{#1|bold}}
\def\idxi#1{\index{#1|italic}}
\let\idx=\index

aqq\idxb{aqq}		%miejsce definicji
aqq\idx{aqq}		%normalne wyst�pienie 
aqq\idxi{aqq}		%u�ycie w przyk�adzie
i rezultat: 

  \item aqq, 1, \bold{1}, \italic{1}

Grupowanie numer�w stron

 U�ywaj�c polecenia \index mo�emy zadeklarowa�, �e dane has�o jest opisywane na kilku stronach. Pocz�tek opisu has�a zaznaczamy: 
strona 1: aqq\index{aqq|(}
a ko�czymy 
strona 3: aqq\index{aqq|)}
w wyniku dzia�ania programu plmindex i ponownego przetwarzania LaTeX-em otrzymamy: 
    aqq, 1-3
je�eli mi�dzy konstrukcj� \index{...|(}, a \index...|)} pojawi si� normalna definicja tego samego has�a to zostanie ona zignorowana (jako zawieraj�ca si� w zadanym zakresie). Je�eli konstrukcja zamykaj�ca nie wyst�pi, to ostatnia definicja has�a spe�ni t� rol�.

Standardowo, je�eli has�o wyst�puje na kolejnych stronach to numery stron s� grupowane (efekt taki jak w powy�szym przyk�adzie). U�ywanie powy�szej konstrukcji ma sens, je�li chcemy uzyska� ten efekt tylko dla wybranych hase�, wtedy nale�y wywo�a� program plmindex z opcj� -r, kt�ra wy��czy standardowe grupowanie numer�w stron.

Znaki specjalne

W wy�ej opisywanych konstrukcjach znaki |, |, ! i @ mia�y znaczenie specjalne, je�eli chcemy w ha�le skorowidza u�y� jednego z wy�ej wymienionych znak�w nale�y poprzedzi� go znakiem " np. 
aqq!aqq\index{aqq"!aqq}
wprowadzi do skorowidza has�o: 
aqq!aqq, 1

Definiowanie postaci skorowidza

 Program plmindex porz�dkuj�c zbi�r hase� wstawia szereg polece�. Mo�emy mie� wp�yw zar�wno na ich zestaw, jak i na ich definicj�. W�a�ciwo�ci programu mo�emy zmienia� na trzy sposoby:
zmieni� standardowe definicje u�ywanych polece� (makroinstrukcji)
Program plmindex zanurza zbi�r posortowanych i posegregowanych hase� w �rodowisku index. U�ycie �rodowiska powoduje zdefiniowanie podrozdzia�u o nazwie zdefiniowanej przez makroinstrukcj� \indexname. Standardowo warto�ci� polecenia jest napis Index, je�eli chcemy zmieni� napis nale�y zmieni� definicj� tego polecenia np: 
\renewcommand\indexname{Skorowidz}
Do definiowania sposobu prezentacji hase� na r�nych poziomach u�ywane s� nast�puj�ce makroinstrukcje:
poziom nazwa standardowa definicja
1 \item \par\hangindent 40\p@
2 \subitem \par\hangindent 40\p@ \hspace*{20\p@}
3 \subsubitem \par\hangindent 40\p@ \hspace*{30\p@}

mi�dzy grupy hase� (mi�dzy has�a zaczynaj�ce si� od r�nych znak�w -- ale tylko na najwy�szym poziomie) jest wstawiane polecenie:
\indexspace o warto�ci
\par\vskip10\p@ \@plus5\p@ \@minus 3\p@\relax

zmieni� zestaw polece� (makroinstrukcji)
Mo�emy utworzy� specjalny zbi�r zawieraj�cy szereg polece� steruj�cych programem plmindex. Program plmindex wczytuje ten zbi�r je�eli jest zdefiniowana opcja -s (p. opcje); standardowym rozszerzeniem nazwy jest .mst. W zbiorze tym mo�na zdefiniowa� nast�puj�ce warto�ci:

NazwaWarto�� standardowaOpis
preamble string "\\begin{theindex}\n" pocz�tek zbioru
postamble string "\n\n\\end{theindex}\n" koniec zbioru
setpage_prefix string "\n \\setcounter{page}{" pocz�tek polecenia definiuj�cy zmian� warto�ci numeru strony
setpage_suffix string "}\n" koniec definicji polecenia zmiany numeru strony
group_skip string "\n\n \\indexspace\n" polecenie wstawiane przed rozpocz�ciem grupy hase�
headings_flag string 0 flaga aktywuj�ca wstawianie polece� przy zmianie pierwszego znaku hase�, warto�� pozytywna (>0) wstawiany b�dzie znak w postaci du�ej litery, je�li <0 znak ma�ej litery
heading_prefix string "" ci�g znak�w, kt�ry b�dzie poprzedza� w.m. znak
symhead_positive string "Symbols" nazwa grupy hase� nie zaczynaj�cych si� liter� (wstawiany je�li flaga >0)
symhead_negative string "symbols" nazwa grupy hase� nie zaczynaj�cych si� liter� (wstawiany je�li flaga <0)
numhead_positive string "Numbers" nazwa grupy hase� zaczynaj�cych si� cyfr� (wstawiany je�li flaga <0)
numhead_negative string "numbers" nazwa grupy hase� zaczynaj�cych si� cyfr� (wstawiany je�li flaga <0)
item_0 string "\n \\item " polecenie wstawiane mi�dzy dwie pozycje na poziomie 0
item_1 string "\n \\subitem " polecenie wstawiane mi�dzy dwie pozycje na poziomie 1
item_2 string "\n \\subsubitem " polecenie wstawiane mi�dzy dwie pozycje na poziomie 2
item_01 string "\n \\subitem " polecenie wstawiane mi�dzy pozycje poziomu 0 i 1
item_x1 string "\n \\subitem " polecenie wstawiane mi�dzy pozycje poziomu 0 i 1, je�li pozycja poziomu 0 nie wyst�pi�a w spos�b jawny (nie b�dzie opatrzona numerem strony)
item_12 string "\n \\subsubitem " polecenie wstawiane mi�dzy pozycje poziomu 1 i 2
item_x2 string "\n \\subsubitem " polecenie wstawiane mi�dzy pozycje poziomu 1 i 2 je�li pozycja poziomu 1 nie wyst�pi�a w spos�b jawny (nie b�dzie opatrzona numerem strony)
delim_0 string ", " separator mi�dzy has�em poziomu 0, a pierwszym numerem strony
delim_1 string ", " separator mi�dzy has�em poziomu 1, a pierwszym numerem strony
delim_2 string ", " separator mi�dzy has�em poziomu 2, a pierwszym numerem strony
delim_n string ", " separator mi�dzy kolejnymi numerami stron (wszystkie poziomy hase�)
delim_r string "--" separator odzielaj�cy numery zakres�w stron wyst�powania has�a
delim_t string "" ci�g znak�w umieszczany na ko�cu listy numer�w stron
encap_prefix string "\\" pierwsza cz�� ci�gu znak�w wstawiana przy u�ywaniu znaku steruj�cego enkapsulacji (|)
encap_infix string "{" druga cz�� znak�w wstawiana przy u�ywaniu znaku steruj�cego enkapsulacji (|)
encap_suffix string "}" ci�g znak�w zamykaj�cy polecenie enkapsulacji
line_max number 72 maksymalna liczba znakow w linii (je�li definicja has�a b�dzie d�u�sza, zostanie przeniesiona do nast�pnej linii)
indent_space string "\t\t" ci�g znak�w wstawiany na pocz�tku ,,�amanej linii''
indent_length number 16 okre�lenie szeroko�ci w.m. ci�gu znak�w (potrzebne do prowadzenia pozycji w bie��cej linii

Przyk�ad: Zawatro�� zbioru .mst 

delim_0	"~~"
delim_1	"~~"
delim_2	"~~"
headings_flag 1
heading_prefix "{\\par\\goodbreak\\vskip2ex\\par\\large\\bf\\noindent "
heading_suffix "}\\par\\nobreak\\vskip 1.5ex"
daje nast�puj�cy efekt: 
\begin{theindex}
{\par\goodbreak\vskip2ex\par\large\bf\noindent A}\par\nobreak\vskip 1.5ex
  \item a~~\bold{16}, \see{odsy�acz}{16}, \bold{25}
    \subitem effect~~\bold{20}
      \subsubitem new~~\bold{20}
      \subsubitem overlay~~\bold{20}
      \subsubitem replace~~\bold{20}
    \subitem href~~\bold{25}
      \subsubitem \#~~\bold{19}

.
.
.

  \indexspace
{\par\goodbreak\vskip2ex\par\large\bf\noindent Z}\par\nobreak\vskip 1.5ex
  \item zlecenie poszukiwania~~54
  \item zmiana czcionki~~28
  \item znaki specjalne~~92

\end{theindex}
makroinstrukcja \bold zosta�a zdefiniowana jako:
\def\bold#1{{\bfseries #1}}

zmieni� spos�b dzia�ania programu plmindex definiuj�c parametry wywo�ania (opcje)
Program plmindex posiada szereg parametr�w wywo�ania. Og�lna posta� wygl�da nast�puj�co: 
plmindex [<opt>] [<idx0> ...]
<opt> mog� przyjmowa� jedn� z nast�puj�cych warto�ci:

opcja opis
-l podczas sortowania ignoruj spacje mi�dzy s�owami has�a; np. has�o aqq bqq zostanie potraktowane tak jak aqqbqq
-i jako zbioru hase� u�yj standardowego strumienia (stdin)
-q nie wy�wietlaj komunikat�w
-r nie grupuj numer�w stron; np. je�eli has�o wyst�pi na stronie 1, 2 i 3 to w skorowidzu nie zostanie to przedstawione jako 1-3, natomiast has�a grupowane w spos�b jawny (p. grupowanie numer�w stron), b�d� mia�y pogrupowane numery stron
-c ci�g spacji i tabulator�w jest zamieniany na jedn� spacj�
-L lang wyb�r j�zyka, determinuj�cego porz�dek leksykograficzny
lang english
PL-latin2
PL-mazowia
PL-cp1250
PL-cp852
-s sty nazwa zbioru definicji (standardowe rozszerzenie .mst)
-o ind nazwa zbiory wyj�ciowego (standardowo taka jak zbi�r wej�ciowy z rozszerzeniem .ind)
-?
-h 		wy�wietlenie listy opcji
-! opcja procedur specjalnych (zale�y od wybranego j�zyka; dla j�zyka polskiego oznacza, �e liczby (cyfry) b�da umieszczane w miejscu wynikaj�cym z napisu reprezentuj�cego ich warto�ci; np. cyfra 1 zostanie potraktowana tak jak napis jeden) (czywi�cie mo�na wymusi� inn� kolejno�� sortowania)
-t log log zbi�r zawieraj�cy dodatkowe komunikaty (standardowo nazwa taka jak zbi�r wej�ciowy z rozszerzeniem .ilg)
-p num num pocz�tkowa warto�� licznika stron
<idx0> - zbi�r hase� (standardowe rozszerzenie .idx)
Opracowa�: W�odzimierz Macewicz; zmiany 05.05.2014 (StaW)