summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/figbib/figbib_doc.tex
blob: 36e48407600e3586c7c9fe262c6455f529dabc2b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433

%version 2004-8-12

\documentclass{ltxdoc}

\def\FigBib{{\rmfamily F\kern-.05em\lower-.35ex\hbox{\textsc{i\kern-.025em g}}\kern-.05em%
    B\kern-.05em\textsc{i\kern-.025em b}}}

\title{The \FigBib\ - Package}
\author{Jan Poland}

\setlength{\parindent}{0mm}
\setlength{\parskip}{1mm}

\begin{document}
\maketitle

\begin{abstract}
\noindent This document describes how to manage figure databases, using
\BibTeX\ together with the \FigBib\ - Package. Some \FigBib\ features
are:
\begin{itemize}
\item Store and manage figures in a \BibTeX\ database
\item Include figures in your \LaTeX\ document with one short
command
\item Generate a List of Figures containing more/other
information than the figure captions
\item Control with one switch where to output the figures, either
as usual float objects or in a separate part at the end of your
document
\end{itemize}
\end{abstract}

\section{Introduction and Quick Start}

The \FigBib\ is designed for \LaTeX\ authors who have to organize
many figures. In this case, it may not be convenient to manage all
information in a ``low level" manner directly in the documents.
Instead, it would be desirable to have a database which contains
the images, corresponding captions and additional information in a
bundled form. Then, a ``high-level" command is issued each time a
figure needs to be included.

\FigBib\ provides such a mechanism. If the user wants to include a
figure with the label ``MyFigure:1" as a float object on the top
of the page with a width of 5cm, then he writes
\begin{verbatim}
\fbEpsfig{MyFigure:1}{5cm}{t}
\end{verbatim}
The corresponding data for the figure, such as caption, name of
the eps file etc., is stored in a \BibTeX\ data base. There, the
entry could be for example
\begin{verbatim}
@fig{MyFigure:1,
  main = {This is the description/caption},
  file = {myfigure1}
}
\end{verbatim}
In order to process the information, the latex document must
contain a
\begin{verbatim}
\usepackage{figbib}
\end{verbatim}
in the document header and a
\begin{verbatim}
\fbList{<figure-bibfile>}
\end{verbatim}
at the end, which also generates a List of Figures. Then, the
document is compiled with the command sequence
\begin{verbatim}
latex <latex-file>
bibtex <latex-file>.figbib
latex <latex-file>
latex <latex-file>
latex <latex-file>
\end{verbatim}
(The \texttt{latex} command is repeated until all cross-references
have been updated correctly, for \FigBib\ this is the case after
at most three runs.)

\subsection{The Example File}
Try the example file \texttt{figbib\_sample} provided with this
package with the above command sequence.

\section{Reference}

\FigBib\ processes information on two levels: (1) the
\emph{contents} of the figures, and (2) the \emph{float objects} containing
the figures. For the latter, \FigBib\ gives the user the choice
between usual float objects and a separate part at the end of the
document. All commands and options for the \FigBib\ package are
described in the following.

\subsection{The \BibTeX\ Style}

\DescribeMacro{@fig}
\DescribeMacro{main}
\DescribeMacro{add}
\DescribeMacro{source}
\DescribeMacro{caption}
\DescribeMacro{file}
There is only one entry type for the \FigBib-database, namely
\texttt{@fig}. It has five fields:

\begin{tabular}{l l l}
\texttt{main} &  (mandatory) &  the main description/caption\\
\texttt{add} &  (optional) &  an additional description\\
\texttt{source} & (optional) &  the source of the figure\\
\texttt{caption} & (optional) &  a caption which (if it is
defined) supersedes \texttt{main}\\
\texttt{file} & (mandatory) &  the eps-file containing the
figure
\end{tabular}

The user has options to control how these fields are used in the
captions and the List of Figures. This is described in Section
\ref{options}. An example entry for your database would be
\begin{verbatim}
@fig{Beatles:1968,
  main = {The Beatles on stage},
  add = {Picture was probably taken at some performance in 1968},
  source = {A nice book of mine},
  file = {beatles1}
}
\end{verbatim}

\DescribeMacro{\fbDirectory}
If you store your figure files at a central place on your file
system, you may set \verb+\fbDirectory+ to point there. This
should be defined in the document header of your
\LaTeX-document. For example, in a windows system, the command could
read
\begin{verbatim}
\def\fbDirectory{c:/EPSpics/}
\end{verbatim}

\DescribeMacro{\figbibBst}
You may change the default \BibTeX\ style file, which is
\texttt{figbib.bst}, by redefining \verb+\figbibBst+. This should
be done in the \LaTeX document header. One alternative \BibTeX\
style file, \texttt{figbib1.bst}, is already included in \FigBib.
Put
\begin{verbatim}
\def\figbibBst{figbib1}
\end{verbatim}
in your document header in order to apply it. Then the fields
\texttt{main1}, \texttt{add1}, \texttt{source1}, and \texttt{caption1}
are used instead of \texttt{main}, \texttt{add}, \texttt{source},
and \texttt{caption}. Thus you can maintain your database in two
\emph{different languages}, e.g.\ the default fields \texttt{main}
etc.\ containing English and the alternative fields \texttt{main1}
etc.\ containing German entries.

\subsection{Including a Figure}\label{include}

There are two ways to include a figure from the database to your
document: (1) with a single command defining the figure and the
surrounding (float) environment simultaneously, and (2) including
the figure without defining the environment. The former method is
clearly shorter. On the other hand, the latter allows you to have
more than one figure in a float environment.

\DescribeMacro{\fbEpsfig}
\DescribeMacro{\fbEpsfigM}
In order to include a figure and at the same time define the
environment, use e.g.
\begin{verbatim}
\fbEpsfig{Beatles:1968}{8cm}{t!}
\end{verbatim}
Then the figure with the label \texttt{Beatles:1968} is included,
the width of the figure is set to 8cm, and (as default) a float
environment is generated and placed at the top of the current page
(\texttt{t!}). The width of the caption would be the whole text
width. Use \verb+\fbEpsfigM+ instead of
\verb+\fbEpsfig+ to restrict the caption width to the figure
width (\texttt{M} stands for \emph{minipage}).

\DescribeMacro{\fbEps}
\DescribeMacro{\fbEpsM}
\DescribeMacro{\fbhspace}
\DescribeMacro{\fbhfill}
If you want to include more than one figure in an environment, you
can use for example the following command sequence:
\begin{verbatim}
\begin{fbFloat}[b]
\fbEpsM{Beatles:1968}{5cm}
\fbhspace{2cm}
\fbEpsM{Beatles:1969}{5cm}
\end{fbFloat}
\end{verbatim}
There, \verb+\fbEpsM+ includes the figure and sets the caption
width to the figure width -- \verb+\fbEps+ would set the caption
width to the text width instead. \verb+\fbhspace+ inserts a
horizontal space, you could also use \verb+\fbhfill+ (without
argument) for a horizontal fill.

\DescribeMacro{fbFloat}
The environment is here defined by
\begin{verbatim}
\begin{fbFloat}[b] ... \end{fbFloat}
\end{verbatim}
where the positioning parameter \texttt{[b]} is optional. This
\FigBib-environment is \emph{flexible}: As default, it causes the
generation as a usual float object. However, if you set the option
\texttt{xpart} (see Sections \ref{xpart} and \ref{options}), then
the figure is generated in an extra part (usually) at the end of
the document. If the usual \texttt{figure} environment is used
instead of \texttt{fbFloat}, i.e.
\begin{verbatim}
\begin{figure} ... \end{figure}
\end{verbatim}
then a float object is \emph{always} created. This may be useful
if you want to have usual float objects and extra figure parts
simultaneously in a document. Note that \verb+\fbEpsfig+ and
\verb+\fbEpsfigM+ also internally generate an
\texttt{fbFloat}-environment.

\DescribeMacro{\fbCaptionStyle}
You may set the caption style by redefining
\verb+\fbCaptionStyle+, e.g.
\begin{verbatim}
\def\fbCaptionStyle{\small\itshape}
\end{verbatim}
The default style is empty, i.e.\ the same as the text style.

\subsection{Extra Figure Parts}\label{xpart}

\DescribeMacro{option xpart}
\DescribeMacro{\fbTheFigs}
If you pass the option \texttt{xpart} to \FigBib\ (compare
Sections \ref{include} and \ref{options}), then all figures in
\texttt{fbFloat}-environments are moved to one or more \emph{extra
figure parts}. Note that also \verb+\fbEpsfig+ and
\verb+\fbEpsfigM+ implicitly generate \texttt{fbFloat} environments. An
extra figure part is invoked by
\begin{verbatim}
\fbTheFigs
\end{verbatim}
and causes the output of all figures which were defined up to this
command. You can give \verb+\fbTheFigs+ multiple times, creating
several figure parts in your document.

\DescribeMacro{\fbvspace}
In the figure part, figures are created in the order they appear
in the document. You may include a \verb+\fbvspace+ command before
or after a figure inside the \texttt{fbFloat} environment, e.g.\
\verb+\fbvspace{1cm}+. This causes a vertical space before/after
the respective figure. The command is ignored if the option
\texttt{xpart} is not given.

\DescribeMacro{\figbibskip}
\DescribeMacro{\figbibcskip}
In the figure parts, you may redefine the space
\verb+\figbibskip+ between subsequent figures, e.g.\
\verb+\setlength{\figbibskip}{1cm}+. Similarly, you can
redefine the space \verb+\figbibcskip+  between the figures and
the corresponding captions.

\DescribeMacro{option xplate}
If you are using floats \emph{and} figure parts together in one
document, they should not be referred to as the same type, e.g.\
both as a ``figure". In this case, you should declare the option
\texttt{xplate}, causing that the figures in the extra part are
referred to as ``plates" rather than ``figures".

\DescribeMacro{fbMinipage}
If you want to create a \emph{minipage} inside an \texttt{fbFloat}
environment, you should use the \texttt{fbMinipage} environment
instead of the usual \texttt{minipage}. It takes one argument,
namely the width of the minipage, e.g.
\begin{verbatim}
\begin{fbMinipage}{\textwidth}...\end{fbMinipage}
\end{verbatim}
If the \texttt{xpart} option is set, then the fbMinipages are
correctly moved to the figure parts. (The only use of a minipage I
can think of in this context is for having two or more figures in
one row, when you want to avoid the constraint that some caption
width equals the figure width.)

\subsection{The List of Figures}

\DescribeMacro{\fbList}
At any point of the document, you can output the List of Figures
by giving the command
\begin{verbatim}
\fbList{<figure-bibfile>}
\end{verbatim}
where \texttt{<figure-bibfile>} is your figure \BibTeX-database
(without the .bib extension). You \emph{must} include this command
\emph{exactly once} in your document.

\DescribeMacro{\figbibListHeader}
Usually, \verb+\fbList+ generates a starred (i.e.\ without
numbering) chapter or section ``List of Figures", depending on
your document type. However, if you define
\verb+\figbibListHeader+ to be empty by including \verb+\def\figbibListHeader{}+
in your document, then no chapter/section is generated (while the
list is still generated).

\DescribeMacro{\fbListStyle}
\DescribeMacro{\figbibhang}
\DescribeMacro{\figbibsep}
The layout of the List of Figures can be adjusted by redefining
the style, the hang, and the separation space, e.g.\
\verb+\def\fbListStyle{\footnotesize}+, \verb+\setlength{\figbibhang}{5mm}+ and
\verb+\setlength{\figbibsep}{1ex}+.

\subsection{References}

\DescribeMacro{\fbref}
\DescribeMacro{\fbpageref}
Use the commands \verb+\fbref+ and \verb+\fbrefpage+ to refer to
figures. They generate complete references, not only numbers. For
example, \verb+\fbref{Beatles:68}+ might create ``Fig.~14", and
\verb+\fbpageref{Beatles:68}+ might generate ``p.~33".

\subsection{Strings and Languages}\label{strings}

\DescribeMacro{\figbibListHeader}
\DescribeMacro{\figbibPage}
\DescribeMacro{\figbibFig}
\DescribeMacro{\figbibPlate}
\DescribeMacro{\figbibFrom}
\FigBib\ defines the following strings.

\begin{tabular}{l l l}
\emph{command} & \emph{description} & \emph{default}\\
\verb+\figbibListHeader+ & Header of the L.o.F. chapter/section & List of Figures\\
\verb+\figbibPage+ & string/abbreviation for ``page" & p.\\
\verb+\figbibFig+ & string/abbreviation for ``figure" & Fig.\\
\verb+\figbibPlate+ & string/abbreviation for ``plate" & Plate\\
\verb+\figbibFrom+ & string/abbreviation for ``from" & From\\
\end{tabular}

You may redefine these strings, e.g.\ by
\verb+\def\figbibFig{Abb.}+. Thus \FigBib\ can be adjusted to
different \emph{languages}. As already mentioned, set
\verb+\figbibListHeader+ to empty in order to prevent the List of Figures
chapter/section from being generated (the list is still
generated).

\subsection{Options}\label{options}

\FigBib can be controlled with a number of options. They are given
at the \verb+\usepackage{figbib}+ command, e.g.\ by
\begin{verbatim}
\usepackage[center,nopages,xpart]{figbib}
\end{verbatim}

\DescribeMacro{center}
\DescribeMacro{nopics}
There are options controlling the \emph{figures}:

\begin{tabular}{l l}
\texttt{center} & Figures and captions are centered instead of left-aligned.\\
\texttt{nopics} & Pictures are \emph{not} included. This is for
faster draft viewing.
\end{tabular}

\DescribeMacro{nopages}
\DescribeMacro{nosource}
\DescribeMacro{addcaption}
\DescribeMacro{nocaption}
\DescribeMacro{maincaption}
There are options controlling the \emph{captions} and \emph{List
of Figure entries}. If no options are given, the following default
is used. The caption is set to the field \texttt{caption} if
defined and \texttt{main} otherwise. The List of Figures entry is
set to ``Fig.~[number] (p.~[page number])", followed by
\texttt{main}, followed by \texttt{add} (if defined), followed by
``From: \texttt{source}" (if defined).

\begin{tabular}{l l}
\texttt{nopages} & Page numbers are suppressed in the List of Figures.\\
\texttt{nosource} & Source is not given in List of Figures.\\
\texttt{addcaption} & \texttt{add} field is included to caption.\\
\texttt{nocaption} & No caption is generated at all, only figure number.\\
\texttt{maincaption} & \texttt{caption} field is not used.
\end{tabular}

\DescribeMacro{xpart}
\DescribeMacro{xplate}
There are options controlling the \emph{extra figure parts}:

\begin{tabular}{l l}
\texttt{xpart} & \texttt{fbFloat} environments are moved to extra figure part(s), see Sec. \ref{xpart}.\\
\texttt{xplate} & Figures in \texttt{fbFloat} environments are
referred to as ``plates"\\
& instead of ``figures".
\end{tabular}

\DescribeMacro{german}
The option \texttt{german} sets the strings defined in Section
\ref{strings} to German language counterparts. Support of other
languages is planned in the future.

\subsection{\LaTeX-Macros in the figure database}

Using \LaTeX-macros in the figure database entries (e.g.\ in the
\texttt{main} field) generally causes problems. However, you can
use the following macros:
\begin{itemize}
\item\verb+\"+, e.g.\ for German Umlaut characters
\item\verb+~+ for spaces without line break
\item\verb+\emph+ and \verb+\em+ for emphasized text
\item\verb+\textit+ and \verb+\it+ for italics
\item\verb+\textbf+ and \verb+\bf+ for bold face
\item\verb+\textsc+ and \verb+\sc+ for small caps
\item\verb+\texttt+ and \verb+\tt+ for typewriter font
\end{itemize}
If required, you can include further admissible macros by
extending the definition of \verb+\figbib@noexpands+ in the
\FigBib\ style file.

\subsection{Extras}

\DescribeMacro{fbForce}
If you suppress pictures using the option \texttt{nopics}, you can
still force \FigBib\ to include certain pictures. All you have to
do is to surround the picture(s) by an \texttt{fbForce}
environment, i.e.
\begin{verbatim}
\begin{fbForce}
...
\fbEpsfig{...}
...
\end{fbForce}
\end{verbatim}

\DescribeMacro{\FigBib}
\verb+\FigBib+ produces the output \FigBib.

\end{document}