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
floatwspółpraca z pakietem float
longtablewspółpraca z pakietem longtable
rotatingwspółpraca z pakietem rotating
sidecapwspółpraca z pakietem sidecap
supertabularwspółpraca z pakietem supertabular

Pozostałe parametry

Parametr Wartości Opis
fontzmiana cech pisma całego podpisu (również etykiety)
defaultnic nie zmienia -- cechy pisma pozostają bez zmian, takie jak określono poprzednio
scriptsizezmiana wielkości na scriptsize
footnotesizezmiana wielkości na footnotesize
smallzmiana wielkości na small
normalsizezmiana wielkości na normalsize
largezmiana wielkości na large
Largezmiana wielkości na Large
upzmiana kroju na upshape
itzmiana kroju na itshape
slzmiana kroju na slshape
sczmiana kroju na scshape
mdzmiana kroju na mdseries
bfzmiana kroju na bfseries
rmzmiana kroju na rmfamily
sfzmiana kroju na sffamily
ttzmiana 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 dimenwielkość lewego i prawego marginesu podpisu
width dimenszerokość pola przeznaczonego na podpis
parskip dimenodległ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
formatsposó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''
hangefekt 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 dimendodatkowa odległość pod podpisem (patrz parametr position)
aboveskip dimendodatkowa odległość nad podpisem (patrz parametr position)
indention dimendodatkowy 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 dimendodatkowy 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
positiondeklaruje położenie podpisu
bottomdeklaruje, że podpis będzie na dole obiektu
topdeklaruje, że podpis będzie na górze obiektu (odwraca znaczenie parametrów belowskip i aboveskip
labelformatsposó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}
defaultpojawia się etykieta (nazwa obiektu) i numer
emptyetykieta jest pusta (pojawi się tylko opis); w tym wypadku należy parametrowi labelsep przypisać wartość none
simplepojawia się etykieta (nazwa obiektu) i numer
parenspojawia się etykieta (nazwa obiektu) i numer ujęty w nawaisy ()
labelsepobiekt wstawiany po etykiecie. Do definiowania nowych separatorów służy polecenie
\DeclareCaptionLabelSeparator{nazwa}{ciąg poleceń}, np.:
\DeclareCaptionLabelSeparator{default}{: }
defaultwstawiany jest : i spacja
nonenic nie jest wstawiane
colonwstawiany jest : i spacja
periodwstawiana jest . i spacja
spacewstawiana tylko spacja
quadwstawiane jest polecenie \quad
widespacewstawiane \hspace{1em plus .3em}
newlinewstawiane jest polecenie \newline
justificationsposób formatowania opisu. Do definiowania nowych sposobów formatowania służy polecenie
\DeclareCaptionJustification{nazwa}{ciąg poleceń}; np.:
\DeclareCaptionJustification{centering}{\centering}
defaultskład z wyrównaniem do lewego i prawego marginesu
justifiedskład z wyrównaniem do lewego i prawego marginesu
centeringwszystkie linie podpisu centrowane
centerfirstpierwsza linia wycentrowana
centerlastostatnia linia wycentrowana
raggedleftwyrównanie do prawego marginesu
raggedrightwyrównanie do lewego marginesu
Centeringwszystkie linie centrowane, ale używane jest polecenie \Centering z pakietu ragged2e (m.in. włączane jest przenoszenie wyrazów)
RaggedLeftwyrównanie do prawego marginesu, ale używane jest polecenie \RaggedLeft z pakietu ragged2e (m.in. włączane jest przenoszenie wyrazów)
RaggedRightwyrównanie do lewego marginesu, ale używane jest polecenie \RaggedRight z pakietu ragged2e (m.in. włączane jest przenoszenie wyrazów
singlelinechecknadanie 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
onnadanie wartości true
1nadanie wartości true
truenadanie wartości true
0nadanie wartości false
offnadanie wartości false
falsenadanie wartości false
stylesposó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
defaultustawia centrowanie podpisu dla opisów jednolinijkowych, jeśli została ustawiona flaga singlelinechech
defaultjest 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.