summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/figbib/figbib_doc.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/figbib/figbib_doc.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/figbib/figbib_doc.tex')
-rw-r--r--macros/latex/contrib/figbib/figbib_doc.tex433
1 files changed, 433 insertions, 0 deletions
diff --git a/macros/latex/contrib/figbib/figbib_doc.tex b/macros/latex/contrib/figbib/figbib_doc.tex
new file mode 100644
index 0000000000..36e4840760
--- /dev/null
+++ b/macros/latex/contrib/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}