diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/figbib/figbib_doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/figbib/figbib_doc.tex | 433 |
1 files changed, 433 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/figbib/figbib_doc.tex b/Master/texmf-dist/doc/latex/figbib/figbib_doc.tex new file mode 100644 index 00000000000..36e48407600 --- /dev/null +++ b/Master/texmf-dist/doc/latex/figbib/figbib_doc.tex @@ -0,0 +1,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} |