Odsyďż˝acze

autor: Tomasz Przechlewski

Wstďż˝p

Istniejďż˝ systemy takie jak LaTeX (autor: Leslie Lamport), AmSTeX (Michael Spivak), ConTeXt (Hans Hagen) czy eplain (Karl Berry) umoďż˝liwiajďż˝ce automatyczne tworzenie odsyďż˝aczy do rďż˝nych elementďż˝w dokumentu (tabele, rysunki, rozdziaďż˝y, punkty, itp.). Zawierajďż˝ one takďż˝e wiele innych, gotowych do wykorzystania funkcji, ktďż˝rych nie ma formacie plain. Zadaniem tego tekstu nie jest ,,wywaďż˝anie drzwi do lasu'' ale raczej pokazanie w jaki sposďż˝b takie ,,zaawansowane'' funkcje sďż˝ implementowane. Przy okazji okaďż˝e siďż˝, ďż˝e wcale nie jest to takie trudne jakby siďż˝ mogďż˝o na poczďż˝tku wydawaďż˝.

Prezentowany zestaw makr, z racji swojej prostoty, moďż˝e byďż˝ bardzo ďż˝atwo modyfikowany przez uďż˝ytkownika w zaleďż˝noďż˝ci od potrzeb. Jest to podstawowa zaleta stosowania prostej TeX-niki a nie gotowych formatďż˝w. Te ostatnie sďż˝ skomplikowane, a ich przystosowanie do wďż˝asnych potrzeb jest z reguďż˝y bardzo trudne.

Problem

Odsyďż˝acz to znak (liczba, cyfra, asteryks), umieszczony w skďż˝adzie przy wyrazie, zwrocie lub fragmencie tekstu, odsyďż˝ajďż˝cy do objaďż˝nieďż˝ zawartych w innym miejscu tekstu. Czytelnik moďż˝e byďż˝ odesďż˝any do takich elementďż˝w tekstu jak: tabela, rysunek, poczďż˝tek rozdziaďż˝u, poczďż˝tek punktu, rďż˝wnanie matematyczne, pozycja bibliograficzna, inna strona dokumentu itp. Elementy te sďż˝ z reguďż˝y identyfikowalne poprzez kolejny numer, ktďż˝rym sďż˝ oznaczone (moďż˝e to byďż˝ liczba naturalna, para liczb itp.). Jako odsyďż˝acza uďż˝ywamy wtedy numeru elementu do, ktďż˝rego chcemy odesďż˝aďż˝ czytelnika. Przykďż˝ady uďż˝ycia odsyďż˝aczy to: patrz tabela 6, porďż˝wnaj punkt 2.5, z rďż˝wnania (4.5) wynika itd. Jeďż˝eli w tekďż˝cie nie stosuje siďż˝ odesďż˝aďż˝, zbďż˝dne jest numerowanie jakichkolwiek jego elementďż˝w (bo po co?).

Wstawianie do dokumentu TeX-owego numerďż˝w rozdziaďż˝ďż˝w, punktďż˝w, tabel czy rďż˝wnaďż˝ oraz uďż˝ywanie tych numerďż˝w jako odsyďż˝aczy jest zďż˝ďż˝ praktykďż˝. Naleďż˝y przyjďż˝ďż˝ zasadďż˝, ďż˝e na etapie tworzenia pliku ďż˝rďż˝dďż˝owego ostateczne numery tych elementďż˝w i odsyďż˝acze do nich sďż˝ nam nie znane. Elementy dokumentu winny byďż˝ numerowane automatycznie przez TeX-a podczas jego kompilowania i w taki sam sposďż˝b (tzn. automatycznie) wstawiane odsyďż˝acze. Tylko postďż˝pujďż˝c w ten sposďż˝b oszczďż˝dzimy sobie wiele czasu podczas pracy nad kolejnymi wersjami dokumentu.

Ideďż˝ automatycznego wstawiania odsyďż˝aczy przedstawimy na prostym przykďż˝adzie systemu sďż˝uďż˝ďż˝cego do numerowania rďż˝wnaďż˝ matematycznych. Niech plik fermat.tex zawiera nastďż˝pujďż˝cy kod:

Rďż˝wnanie~(\ref{eq:fermat}) na s.~\pref{eq:fermat} przedstawia sďż˝ynne twierdzenie Fermata: $$\eqalignno{% x^n + y^n &= z^n&\elab{eq:fermat}}$$ Historia dowodzenia (\ref{eq:fermat}) ilustruje znaczenie dostatecznie szerokich marginesďż˝w...

po kompilacji powinniďż˝my otrzymaďż˝ nastďż˝pujďż˝cy wynik:

Rďż˝wnanie (1) na s. 1 przedstawia sďż˝ynne twierdzenie Fermata:

Historia dowodzenia (1) ilustruje znaczenie dostatecznie szerokich marginesďż˝w...

Zauwaďż˝my, ďż˝e odnoďż˝niki mogďż˝ wskazywaďż˝ ,,w tyďż˝'' (do tekstu juďż˝ przeczytanego) jak i ,,w przďż˝d'' (do tekstu nie przeczytanego) konieczne jest zatem dwukrotne kompilowanie dokumentu do ich prawidďż˝owego wyznaczenia (pierwsza kompilacja) i wstawienia. Uďż˝ytkownik posďż˝uguje siďż˝ w tym celu trzema nastďż˝pujďż˝cymi instrukcjami:

\elab{etykieta}: wstawia kolejny numer rďż˝wnania oraz definiuje etykietďż˝, ktďż˝rej bďż˝dziemy uďż˝ywaďż˝ przy odwoďż˝aniach do tego rďż˝wnania,
\pref{etykieta}: wstawia numer strony na ktďż˝rej znajduje siďż˝ rďż˝wnanie oznakowane etykietďż˝.
\ref{etykieta}: wstawia numer rďż˝wnania oznakowanego etykietďż˝.

Rozwiďż˝zanie

Ogďż˝lny schemat dziaďż˝ania systemu jest nastďż˝pujďż˝cy: W czasie pierwszej kompilacji instrukcja \elab zwiďż˝ksza wartoďż˝ďż˝ licznika rďż˝wnaďż˝ o 1, wstawia do dokumentu bieďż˝ďż˝cďż˝ wartoďż˝ďż˝ tego licznika oraz przesyďż˝a do pliku dodatkowego trzy informacje: bieďż˝ďż˝cy numer strony, numer rďż˝wnania, etykietďż˝. Podczas drugiej kompilacji TeX sprawdza czy ten plik dodatkowy istnieje i jeďż˝eli tak to zostaje on wczytany. Zawarte tam informacje sďż˝ wykorzystywane przez instrukcje \ref i \pref do prawidďż˝owego wstawienia odsyďż˝aczy.

Przejdďż˝my teraz do szczegďż˝ďż˝w.

Zamiast definowaďż˝ od razu komendďż˝ \elab zdefiniujemy najpierw makro \defreference, majďż˝ce dwa parametry, z ktďż˝rych pierwszy bďż˝dzie etykietďż˝ dla odsyďż˝acza, a drugi zawieraďż˝ bďż˝dzie sam odsyďż˝acz oraz numer strony, na ktďż˝rej znajduje siďż˝ odesďż˝anie. Na przykďż˝ad jeďż˝eli TeX na 44 stronie dokumentu napotkaďż˝ definicjďż˝ \defreference{eq:fermat}{\the\eqnC}¹ to jej wykonanie powinno spowodowaďż˝ wysďż˝anie do pliku fermat.crf nastďż˝pujďż˝cej linii (zakďż˝adamy, ďż˝e w chwili wykonywania \defreference licznik \eqnC byďż˝ rďż˝wny 8):

\crlab{eq:fermat}{{8}{44}}

Co ma oznaczaďż˝, ďż˝e odsyďż˝aczem dla etykiety eq:fermat jest 8, a odesďż˝anie wskazuje na stronďż˝ 44. Niďż˝ej przedstawiona definicja wykonuje zadanie zapisania odpowiedniej linii do pliku fermat.crf.

1. \def\defreference#1#2{%
2. \edef\@tmp{\string\crlab
3. {#1}{{#2}{\noexpand\folio}}}%
4. \write\crfile\expandafter{\@tmp}}

Makro to musi sobie poradziďż˝ z podstawowym problemem: zapisania jednoczeďż˝nie prawidďż˝owego numeru odnoďż˝nika i prawidďż˝owego numeru strony na ktďż˝rďż˝ ten odnoďż˝nik wskazuje. Numer strony nie jest znany w momencie napotkania instrukcji \defreference. Jest on ustalany w momencie wykonywania procedury wyjďż˝cia (output routine). Z drugiej strony odnoďż˝nik jest znany i winien byďż˝ zapisany natychmiast. Jeďż˝eli jego rozwiniďż˝cie zostanie opďż˝nione to otrzymany numer bďż˝dzie bieďż˝ďż˝cym numerem odnoďż˝nika w czasie wykonywania tej procedury.

Problem ten jest rozwiďż˝zywany w liniach 2--4 makrodefinicji \defreference. Linie 2--3 definiujďż˝ makro \@tmp. Zamiast \def uďż˝yto \edef (expanded definition) co gwarantuje, ďż˝e zawartoďż˝ďż˝ definicji \@tmp zostanie rozwiniďż˝ta natychmiast. Nie ma to znaczenia gdy piszemy \defreference{foo}{7}, ale gdy odnoďż˝nik jest ustalany automatycznie, np. \defreference{foo}{\the\eqnC}, to chodzi nam o bieďż˝ďż˝cďż˝ wartoďż˝ďż˝ licznika a nie jego wartoďż˝ďż˝ w chwili wykonywania output routine.

Sekwencja \noexpand\folio spowoduje, ďż˝e komenda \folio (okreďż˝lajďż˝ca numer strony), nie zostanie rozwiniďż˝ta przy rozwijaniu zawartoďż˝ci definicji \@tmp. Zostanie to opďż˝nione do czasu rozwijania komendy \write podczas wykonywania output routine.

W linii 4 zawartoďż˝ďż˝ definicji \@tmp zostaje wysďż˝ana do pliku dodatkowego za pomocďż˝ instrukcji \write. Konstrukcja:

\write\crfile\expandafter{\@tmp}

jest prostym przykďż˝adem zastosowania instrukcji \expandafter w celu zmiany porzďż˝dku rozwiniďż˝cia dwďż˝ch ďż˝etonďż˝w (tokens) { oraz \@tmp. Kiedy TeX napotka konstrukcjďż˝ \write\crfile oczekuje nastďż˝pnie ďż˝etonu { (por. The TeXbook str. 226), a potem ciďż˝gu ďż˝etonďż˝w koďż˝czďż˝cego siďż˝ }, ktďż˝ry zapisuje do pliku. Zapis do pliku jest opďż˝niony, co oznacza, ďż˝e caďż˝y materiaďż˝ zawarty pomiďż˝dzy klamrami { i } nie jest rozwijany w chwili napotkania instrukcji \write ale umieszczany jako tzw. whatsit na gďż˝ďż˝wnej liďż˝cie pionowej (main vertical list) i rozwijany pďż˝niej przy wykonywaniu output routine (por. The TeXbook str. 227).

Jednakďż˝e wykonujďż˝c sekwencjďż˝ instrukcji z linii 4 TeX napotyka \expandafter zamiast {. Powoduje to przeczytanie (czyli rozwiniďż˝cie) przez TeX-a najpierw makra \@tmp a dopiero potem umieszczenie przed rozwiniďż˝tym juďż˝ makrem \@tmp ďż˝etonu {. W efekcie na gďż˝ďż˝wnďż˝ listďż˝ pionowďż˝, do pďż˝niejszego zapisu do pliku fermat.crf wďż˝druje sekwencja ďż˝etonďż˝w tworzďż˝ca makro \@tmp a nie ďż˝eton \@tmp, ktďż˝ry jest od tej chwili gotowy do uďż˝ycia w nastďż˝pnej instrukcji \defreference. Gdyby na gďż˝ďż˝wnďż˝ listďż˝ pionowďż˝ trafiaďż˝ ďż˝eton \@tmp rozwijany podczas wykonywania output routine to zawartoďż˝ďż˝ (meaning) wszystkich ďż˝etonďż˝w byďż˝aby jednakowa i rďż˝wna zawartoďż˝ci ostatniego zdefiniowanego ďż˝etonu \@tmp --- rezultat caďż˝kowicie rďż˝ny od poprzedniego i raczej przez nas nie oczekiwany!

Makro \elab moďż˝na zdefiniowaďż˝ nastďż˝pujďż˝co:

5. \newcount\eqnC
6. \def\elab#1{\global\advance\eqnC 1
7. \defreference{#1}{\the\eqnC}%
8. (\the\eqnC)}

Po pierwszej kompilacji plik fermat.crf zawiera informacje o wszystkich odsyďż˝aczach, ktďż˝re wykorzystujemy przy powtďż˝rnej kompilacji dokumentu. W tym celu najpierw zdefiniujemy komendďż˝ \crlab. Jak widaďż˝ wyďż˝ej, posiada ona dwa parametry, z ktďż˝rych pierwszy zawiera etykietďż˝ odsyďż˝acza a drugi ďż˝ďż˝cznie odsyďż˝acz oraz numer strony, na ktďż˝rej odesďż˝anie siďż˝ znajduje. Zarďż˝wno odsyďż˝acz, jak i numer strony zawarte sďż˝ w parze nawiasďż˝w klamrowych.

9. \def\crlab#1#2{%
10.  \global\expandafter
11.  \def\csname #1\endcsname{#2}}

Wykonanie makra \crlab{eq:fermat}{{8}{44}} spowoduje utworzenie nowego makra o nazwie eq:fermat rozwijajďż˝cego siďż˝ dokďż˝adnie do {8}{44}. Wykorzystanie konstrukcji \csname...\endcsname umoďż˝liwia definiowanie etykiet zawierajďż˝cych znaki o dowolnych ,,egzotycznych'' kodach, np. &, :, #, itd. Wrďż˝cz wskazane jest umieszczenie takich znakďż˝w, co zapobiegnie niezamierzonej zmianie znaczenia ,,normalnych'' makr o przypadkowo identycznej nazwie. Teraz moďż˝emy zdefiniowaďż˝ instrukcjďż˝ \ref. Makro to powinno wstawiaďż˝ odsyďż˝acz a pomijaďż˝ numer strony. Kopiujemy w tym celu pomysďż˝owe rozwiďż˝zanie tego problemu z formatu {\LaTeX}, w ktďż˝rym znowu w roli gďż˝ďż˝wnej wystďż˝puje instrukcja \expandafter:

12. \def\@car#1#2{#1}
13. \def\ref#1{%
14.  \edef\@tempa{\csname #1\endcsname}
15. \expandafter\@car\@tempa}

Makrodefinicja \ref ma jeden argument --- etykietďż˝ odnoďż˝nika. W linii 14 tworzona jest instrukcja \@tempa, ktďż˝rej zawartoďż˝ciďż˝ jest wykonanie makrodefinicji o nazwie toďż˝samej z nazwďż˝ etykiety. W nastďż˝pnej linii najpierw rozwijana jest instrukcja \@tempa, co oznacza rozwiniďż˝cie jej zawartoďż˝ci do postaci {odnoďż˝nik}{strona}. Nastďż˝pnie rozwijane jest makro \@car, ktďż˝re z dwďż˝ch swoich parametrďż˝w wstawia pierwszy a pomija drugi. Proste!

Skonstruowane w analogiczny sposďż˝b makro \pref wstawia numer strony a pomija odnoďż˝nik:

16. \def\@cdr#1#2{#2}
17. \def\pref#1{%
18.  \edef\@tempa{\csname #1\endcsname}
19.  \expandafter\@cdr\@tempa}

Teraz okreďż˝lmy wreszcie plik, z ktďż˝rego pobierane bďż˝dďż˝ odnoďż˝niki a nastďż˝pnie otwďż˝rzmy go do czytania:

20. \newread\crfile
21. \openin\crfile=\jobname.crf
22. \input \jobname.crf

Powyďż˝szy kod ma jeden powaďż˝ny minus. Mianowicie gdyby z jakichďż˝ wzglďż˝dďż˝w plik fermat.crf nie istniaďż˝ (w pierwszej kompilacji dokumentu na pewno go nie bďż˝dzie) to wtedy prďż˝ba wykonania linii \input \jobname.crf spowoduje bďż˝ďż˝d I can't find file fermat.crf. Lepiej zabezpieczyďż˝ siďż˝ na tďż˝ okolicznoďż˝ďż˝ uďż˝ywajďż˝c komendy \ifeof. Tak wiďż˝c w powyďż˝szym fragmencie kodu ostatniďż˝ liniďż˝ naleďż˝y zastďż˝piďż˝ przez:

22. \ifeof\crfile \else
23.   \input \jobname.crf \fi

Wreszcie pozostaje do zdefiniowania plik do ktďż˝rego bďż˝dďż˝ wysyďż˝ane informacje o odesďż˝aniach:

24. \newwrite\crfile
25. \openout\crfile=\jobname.crf

I te 25 linii kodu pokazane wyďż˝ej wystarczďż˝ dla TeX-a do prawidďż˝owego wstawienia odpowiednich odsyďż˝aczy. Wystarczďż˝ TeX-owi ale nie TeX-owcowi, ktďż˝ry z pewnoďż˝ciďż˝ popeďż˝niaďż˝ bďż˝dzie bďż˝ďż˝dy. Dlatego powyďż˝sze makra naleďż˝y rozbudowaďż˝ o obsďż˝ugďż˝ bďż˝ďż˝dďż˝w i ostrzeďż˝eďż˝. W szczegďż˝lnoďż˝ci naleďż˝y zadbaďż˝ o ostrzeganie uďż˝ytkownika o:

odwoďż˝aniu siďż˝ do niezdefiniowanej etykiety. W tym przypadku system powinien wysďż˝aďż˝ komunikat do pliku .log i na ekran a takďż˝e oznakowaďż˝ brakujďż˝ce odnoďż˝niki w skďż˝adanym dokumencie,
dwukrotnym (lub wielokrotnym) zdefiniowanie tej samej etykiety. W tym przypadku system powinien wysďż˝aďż˝ odpowiedni komunikat do pliku .log i na ekran.

Poniewaďż˝ w przedstawionych wyďż˝ej makrach uďż˝ywamy znaku @ w nazwach komend, powinny zostaďż˝ one zawarte pomiďż˝dzy liniami:

\catcode`@=11
...
\catcode`@=12

Makra

Prezentowany poniďż˝ej zestaw makr jest dostďż˝pny na serwerze GUST w pliku: tp-crf.tex. W porďż˝wnaniu do przedstawionych juďż˝ makrodefinicji dodano nastďż˝pujďż˝ce waďż˝niejsze komendy:

\nocrwarns: Ostrzeďż˝enia o bďż˝ďż˝dach nie sďż˝ wyďż˝wietlane na ekranie (przydatne na wstďż˝pnym etapie pracy nad dokumentem),
\nocrfile: Dodatkowy plik nie jest odtwarzany,
\makecrfile: Dodatkowy plik jest tworzony,
\crstatistics: Wyďż˝wietlenie sumarycznej informacji o uďż˝ytych odsyďż˝aczach. Przedefiniowana komenda \bye wywoďż˝uje to makro.

%% --------------------------------
%% Cross-reference generic macros
%% Tomasz Przechlewski
%% Date: 02.01.1995
%% --------------------------------
\catcode`@=11
\def\@crwrn#1{\if@crwrns\immediate
\write16{#1}\fi}
\def\@markmissingcr{{\bf ??}\@marginmarker}
\def\@marginmarker{\vadjust{\vbox to0pt{%
\kern-.77\normalbaselineskip
\hbox{{\it\kern\hsize\kern15pt?}}\vss}}}

\newif\if@crwrns 
\global\@crwrnstrue % default
\def\nocrfile{\global\@crfilefalse}
\def\nocrwrns{\global\@crwrnsfalse}

\def\@car#1#2{#1}
\def\@cdr#1#2{#2}

\long\def\@ifundefined#1#2#3{%
 \expandafter\ifx\csname
 #1\endcsname\relax#2\else#3\fi}

\def\namedef#1{\expandafter
  \def\csname #1\endcsname}

\def\newlabel#1#2{\@ifundefined{#1}{}%
{\@crwrn{-> WARNING: multiple label #1}}%
\global\namedef{#1}{#2}}
\newread\crfile

\openin\crfile=\jobname.crf
\ifeof\crfile
  \@crwrn{-> WARNING: CR-FILE UNDEFINED!!}
 \else
  \@crwrn{READING REFS FROM \jobname.crf}
  \input \jobname.crf
\fi
\closein\crfile

\def\makecrfile{%
  \openout\crfile=\jobname.crf}
\def\nocrfile{\@crwrn{-> WARNING: 
        CR-FILE not created}
 \def\crfile{-1}}

\def\ref#1{\@nextcrf\@ifundefined{#1}{%
 \@markmissingcr
 \@crwrn{undefined cr -> \string#1}}%
 {\edef\@tempa{\csname #1\endcsname}
 \expandafter \@car\@tempa}}

\def\pageref#1{\@nextpcrf
 \@ifundefined{#1}{\@markmissingcr
 \@crwrn{undefined cr -> \string#1}}%
 {\edef\@tempa{\csname #1\endcsname}%
 \expandafter \@cdr\@tempa}}

\def\defreference#1#2{\@nextdrf%
 \edef\save{\string\newlabel{#1}%
 {{#2}{\noexpand\folio}}}%
 \write\crfile\expandafter{\save}}

\newcount\@crfC\newcount\@pcrfC
\newcount\@dcrfC
\def\@nextdrf{\global\advance\@dcrfC1}
\def\@nextcrf{\global\advance\@crfC1}
\def\@nextpcrf{\global\advance\@pcrfC1}
\def\crstatistics{%
\@crwrn{==============================}
\@crwrn{= REFERENCE STATISTICS =======}
\@crwrn{= refs defined.... \the\@dcrfC}
\@crwrn{= refs used....... \the\@crfC}
\@crwrn{= page refs used.. \the\@pcrfC}
\@crwrn{==============================}}
\outer\def\bye{\crstatistics\end}
\catcode`@=12
\endinput

Bibliografia

Knuth D. E., The TeXbook, Addison-Weley, Reading MA: 1986.
Salomon D., Macros for Indexing and Table-of Contents Preparation, TUGboat, 10(3): s. 394--400.

Przypisy

¹Wystďż˝pujďż˝ce w poniďż˝szym opisie nazwy i konstrukcje prďż˝dzej lub pďż˝niej zostanďż˝ wyjaďż˝nione.

Zredagowaďż˝: Wďż˝odzimierz Macewicz (modyfikacja: 15.05.2014)