path: root/macros/latex/contrib/figbib/figbib_doc.tex

%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}