## caption

Pakiet (v.3.0 -- znacznie zmodyfikowany) zmienia definicje standardowego polecenia `\caption` tworzącego opisy obiektów ruchomych (standardowo: `figure` i `table`). Zdefiniowano polecenia pozwalające na tworzenie wzorców lub bezpośrednie kształtowanie podpisów. Za jego pomocą możemy zdefiniować sposób opisu nowych obiektów tworzonych za poleceniami pakietu float, współpracuje również z pakietami subfig (który jest swego rodzaju nakładką) i~starszym od niego subfigure.

### Opis polecenia `\caption`

Polecenie służy do tworzenia podpisów pod obiektami ruchomymi (a także środowiska `longtable`), moża je wywołać na kilka sposobów:
`\caption{opis}`
postać najczęściej spotykana; tekst opisu jest identyczny w spisie (o ile taki jest tworzony) i w obiekcie, podpis jest opatrzony etykietą (o ile nie zadysponowano inaczej)
`\caption[wersja opisu do spisu obiektów]{opis}`
postać używana jeśli opis w spisie objektów ma być inny niż w obiekcie; podpis jest opatrzony etykietą (o ile nie zadysponowano inaczej)
`\caption*{opis}`
opis nie jest wstawiany do spisu obiektów i nie jest opatrywany etykietą
`\caption[]{opis}`
opis nie jest wstawiany do spisu obiektów, ale jest on opatrywany etykietą
`\caption*[]{opis}`
opis nie jest wstawiany do spisu obiektów i nie jest opatrywany etykietą

Polecenie `\caption` zawsze inkrementuje licznik obiektów.

Zdefiniowano też polecenie `\captionof` słuzące do sformatowania tekstu, analogicznie jak obiekt ruchomy:
`\captionof{typ obiektu}{tekst opisu}
\captionof{typ obiektu}[tekst do spisu]{tekst opisu}
\captionof{typ obiektu}[]{tekst opisu}
\captionof{typ obiektu}*[]{tekst opisu}
\captionof{typ obiektu}*{tekst opisu}`
gdzie `typ obiektu` jest zdefiniowanym obiektem ruchomym -- polecenie inkrementuje licznik skojarzony z tym typem (patrz też pakiet capt-of).

Dodatkowo zdefiniowano polecenie `\ContinuedFloat`, które powoduje że nie jest inkrementowany licznik obiektów (powinno ono być użyte przed poleceniem `\caption`). Wszystkie inne aspekty formatowania i etykietowania są zachowane.

### Formatowanie opisu

W nowej wersji pakietu unowocześniono sposób określania parametrów składu podpisów z modyfikacji kodu na parametryczny (dla kompatybilności pozostawiono również stary sposób). Parametrom można nadawać wartości w dwu momentach: przy poleceniu ładowania pakietów np.:

    \usepackage[margin=10pt, font={small,it}, labelfont=bf]{caption}

lub za pomocą polecenia `\captionsetup` (nie wszystkie parametry)

    \usepackage{caption}
    \captionsetup{margin=10pt, font={small,it}, labelfont=bf}

dyspozycje będą dotyczyły podpisów obiektów wszystkich typów; lub
`\captionsetup[nazwa typu obiektu]{margin=10pt, font={small,it}, labelfont=bf}`
dyspozycje będą dotyczyły jedynie określonego typu (nie musi być on w tym momencie zdefiniowany).

Wartością parametru może być pojedyncza wartość lub lista wartości (ujęta w nawiasy `{}`, wartości oddzielone przecinkiem, w przypadku wartości będących w sprzeczności brana jest wartość ostatnia na liście) -- w przypadku parametru w którym nie przewidziano wartości (wartość logiczna) nie jest sprawdzana poprawność, a w pozostałych przypadkach wartość jest sprawdzana dopiero w momencie użycia polecenia `\caption`.

#### Parametry, którym można nadać wartość tylko przy wywołaniu pakietu

Poniższe parametry mogą przyjmować wartości logiczne `on` lub `off` i deklarują współdziałanie (lub nie) z dodatkowymi pakietami. Powinny one być załadowane przed pakietem `caption`. Ustawienie wartości na `off` może spowodować, że definicja makroinstrukcji `\caption` nie zostanie redefiniowana (mechanizmy pakietu `caption` nie zadziałają).

Parametr | Opis
--- | ---
`float` | współpraca z pakietem float
`longtable` | współpraca z pakietem longtable
`rotating` | współpraca z pakietem rotating
`sidecap` | współpraca z pakietem sidecap
`supertabular` | współpraca z pakietem supertabular

#### Pozostałe parametry

Parametr | Wartości | Opis
--- | --- | ---
`font` | zmiana cech pisma całego podpisu (również etykiety)
| `default` | nic nie zmienia -- cechy pisma pozostają bez zmian, takie jak określono poprzednio | `scriptsize` | zmiana wielkości na `scriptsize` | `footnotesize` | zmiana wielkości na `footnotesize` | `small` | zmiana wielkości na `small` | `normalsize` | zmiana wielkości na `normalsize` | `large` | zmiana wielkości na `large` | `Large` | zmiana wielkości na `Large` | `up` | zmiana kroju na `upshape` | `it` | zmiana kroju na `itshape` | `sl` | zmiana kroju na `slshape` | `sc` | zmiana kroju na `scshape` | `md` | zmiana kroju na `mdseries` | `bf` | zmiana kroju na `bfseries` | `rm` | zmiana kroju na `rmfamily` | `sf` | zmiana kroju na `sffamily` | `tt` | zmiana kroju na `ttfamily`
`labelfont` | wartości jw, ale zmiana tylko cech pisma etykiety; cechy niezdefiniowane są dziedziczone z parametru `font`
`textfont` | wartości jw, ale zmiana tylko cech pisma objaśnienia; cechy niezdefiniowane są dziedziczone z parametru `font`
`margin` | dimen | wielkość lewego i prawego marginesu podpisu
`width` | dimen | szerokość pola przeznaczonego na podpis
`parskip` | dimen | odległość między akapitami, jeśli podpis składa się z wielu akapitów; jeśli wpis do spisu obiektów jest tożsamy z podpisem to w przypadku podpisu wieloakapitowego generowany jest błąd -- wymagane jest aby podpis w spisie obiektów był jednoakapitowy (parametr opcjonalny polecenia `\caption`
`format` | sposób formatowania opisu. Do definiowania nowych sposobów formatowania służy polecenie `\DeclareCaptionFormat{nazwa}{ciąg poleceń}` Do wnęrza drugiego parametru (zawierającego kod formatujący) są przekazywane: jako `#1` -- etykieta, `#2` -- separator etykiety i `#3` -- tekst opisu; np.:
    \DeclareCaptionFormat{default}{#1#2#3\par}
`default` | łamanie ,,w ciągu''
`hang` | efekt wyróżnionego pola etykiety, tekst opisu jest składany w polu o szerokości pomniejszonej o szerokość etykiety (i ewentualnie o wielkość marginesów lub skład na polu o szerokości określonej przez parametr `width`
`belowskip` | dimen | dodatkowa odległość pod podpisem (patrz parametr `position`)
`aboveskip` | dimen | dodatkowa odległość nad podpisem (patrz parametr `position`)
`indention` | dimen | dodatkowy margines (może być ujemny) względem szerokości etykiety (ma senes w przypadku formatu typu `hang`) -- ustawienie różnych wartości `indention` i `hangindent` może dać efekt wcięcia akapitowego dla dalszych akapitów
`hangindent` | dimen | dodatkowy margines (może być ujemny) względem szerokości etykiety (ma senes w przypadku formatu typu `hang`) -- dotyczy tylko pierwszego (począwszy od drugiej linii) akapitu podpisu, jeżeli podpis jest jednoakapitowy jest równoważny wartości `indention`
`position` | deklaruje położenie podpisu
`bottom` | deklaruje, że podpis będzie na dole obiektu
`top` | deklaruje, że podpis będzie na górze obiektu (odwraca znaczenie parametrów `belowskip` i `aboveskip`
`labelformat` | sposób formatowania etykiety. Do definiowania nowych sposobów formatowania służy polecenie `\DeclareCaptionLabelFormat{nazwa}{ciąg poleceń}` Do wnęrza drugiego parametru (zawierającego kod formatujący) są przekazywane: jako `#1` -- nazwa etykiety, `#2` -- numer obiektu; np.:
    \DeclareCaptionLabelFormat{simple}{\bothIfFirst{#1}{\nobreakspace}#2}
`default` | pojawia się etykieta (nazwa obiektu) i numer
`empty` | etykieta jest pusta (pojawi się tylko opis); w tym wypadku należy parametrowi `labelsep` przypisać wartość `none`
`simple` | pojawia się etykieta (nazwa obiektu) i numer
`parens` | pojawia się etykieta (nazwa obiektu) i numer ujęty w nawaisy `()`
`labelsep` | obiekt wstawiany po etykiecie. Do definiowania nowych separatorów służy polecenie `\DeclareCaptionLabelSeparator{nazwa}{ciąg poleceń}`, np.:
    \DeclareCaptionLabelSeparator{default}{: }
`default` | wstawiany jest `:` i spacja
`none` | nic nie jest wstawiane
`colon` | wstawiany jest `:` i spacja
`period` | wstawiana jest `.` i spacja
`space` | wstawiana tylko spacja
`quad` | wstawiane jest polecenie `\quad`
`widespace` | wstawiane `\hspace{1em plus .3em}`
`newline` | wstawiane jest polecenie `\newline`
`justification` | sposób formatowania opisu. Do definiowania nowych sposobów formatowania służy polecenie `\DeclareCaptionJustification{nazwa}{ciąg poleceń}`; np.:
    \DeclareCaptionJustification{centering}{\centering}
`default` | skład z wyrównaniem do lewego i prawego marginesu
`justified` | skład z wyrównaniem do lewego i prawego marginesu
`centering` | wszystkie linie podpisu centrowane
`centerfirst` | pierwsza linia wycentrowana
`centerlast` | ostatnia linia wycentrowana
`raggedleft` | wyrównanie do prawego marginesu
`raggedright` | wyrównanie do lewego marginesu
`Centering` | wszystkie linie centrowane, ale używane jest polecenie `\Centering` z pakietu `ragged2e` (m.in. włączane jest przenoszenie wyrazów)
`RaggedLeft` | wyrównanie do prawego marginesu, ale używane jest polecenie `\RaggedLeft` z pakietu `ragged2e` (m.in. włączane jest przenoszenie wyrazów)
`RaggedRight` | wyrównanie do lewego marginesu, ale używane jest polecenie `\RaggedRight` z pakietu `ragged2e` (m.in. włączane jest przenoszenie wyrazów
`singlelinecheck` | nadanie wartości `true` (wystarczy użycie parametru bez nadawania wartości) powoduje, że jeśli podpis jest jenolinijkowy, będzie on wycentrowany, bez względu na ustawiony sposób formatowania
`on` | nadanie wartości `true`
`1` | nadanie wartości `true`
`true` | nadanie wartości `true`
`0` | nadanie wartości `false`
`off` | nadanie wartości `false`
`false` | nadanie wartości `false`
`style` | sposób formatowania opisu, służy do nadania różnych cech składu podpisu. Do definiowania nowych stylów służy polecenie `\DeclareCaptionStyle{nazwa}{opcje}` lub `\DeclareCaptionStyle{nazwa}[dodatkowe opcje]{opcje}`; np.:
    \DeclareCaptionStyle{default}[justification=centering]{}
`opcje` ustawiają parametry dla całego opisu, a `opcje dodatkowe` dla opisów jednolinijkowych, jeśli została ustawiona flaga `singlelinecheck`
`default` | ustawia centrowanie podpisu dla opisów jednolinijkowych, jeśli została ustawiona flaga `singlelinechech`
`default` | jest równoważne `style=default, position=default, aboveskip=10pt, belowskip=0pt`

Zostały również zdefiniowane polecenia `\clearcaptionsetup{typ obiektu}`, służące do przywrócenia domyślnych wartości i `\showcaptionsetup{typ obiektu}`, służące do wyświetlenia (w zbiorze `*.log`) wartości ustawianych poleceniem `\captionsetup`.

#### Parametry i polecenia pozostawione dla kompatybilnością z poprzenimi wersjami

Poniżej wymienione polecenia odniosą skutek, jeśli nie będą używane ich nowozdefiniowane odpowiedniki.

Polecenie | opis
--- | ---
`\captionsize` | Określa wielkość czcionki, używanej do składu podpisu; np: `\renewcommand{\captionsize}{\scriptsize}`
`\captionlabelfont` | określa rodzaj czcionki; można używać wszystkich poleceń zmiany atrybutów przyjętych w LaTeX2e; np: `\renewcommand{\captionlabelfont}{\bfseries}`
`\captionmargin` | określa wielkość lewego i prawego marginesu w tekście opisu; np: `\setlength{\captionmargin}{2cm}`

Poniższe parametry mogą być używane wyłącznie przy wywołaniu pakietu `caption`.

Parametr | opis
--- | ---
`normal` | Jeśli podpis składa się z jodnej linii to jest centrowany w przeciwnym wypadku, składany jest w pudełko o pełnej szerokości (bez wyróżniania nazwy obiektu) -- jest to domyślny sposób składu.
`hang` |
`isu` | podpis składany jest tak jak środowisko `description`; kolejne linie są ,,wcięte'' na szerokość nazwy obiektu
`center` | tekst opisu jest centrowany
`centerlast` | ostatnia linia opisu jest centrowana
`anne`
Ustalenie standardowej wielkości czcionki1
`scriptsize` | czcionka `scriptsize`
`footnotesize` | czcionka `footnotesize`
`small` | czcionka `small`
`normalsize` | czcionka `normalsize`
`large` | czcionka `large`
`Large` | czcionka `Large`
Ustalenie atrybutów czcionki
`up` | `upshape`
`it` | `itshape`
`sl` | `slshape`
`sc` | `scshape`
`md` | `mdseries`
`bf` | `bfseries`
`rm` | `rmfamily`
`sf` | `sffamily`
`tt` | `ttfamily`
`ruled` | jeśli używany jest pakiet `float` (patrz. float) i użyte było polecenie `\floatstyle{ruled}` to opcja `ruled` spowoduje że nazwa obiektu będzie składana czcionką określoną w opcji lub poleceniem `\captionlabelfont`, a nie taką jaka wynika z definicji pakietu `float`

1 Jeżeli był wywołany pakiet `subfigure` to podpis rysunku podrzędnego składany jest czcionką o jeden skok mniejszą

Pakiet jest dostępny pod adresem:
ftp://ftp.gust.org.pl/TeX/macros/latex/contrib/caption/caption.tar

Włodzimierz Macewicz

Ostatnie zmiany: 05.05.2014.