summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/captdef
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-03-07 16:57:06 +0000
committerKarl Berry <karl@freefriends.org>2010-03-07 16:57:06 +0000
commit913673f8f33d20657d1550634367f88adcc7aa50 (patch)
treef1413a662c99e66cf81dc1151d0101b794114ca9 /Master/texmf-dist/doc/latex/captdef
parent0a55dde58294ff3b56499456a092a4e47d7f5e32 (diff)
captdef doc update (6mar10)
git-svn-id: svn://tug.org/texlive/trunk@17353 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/captdef')
-rw-r--r--Master/texmf-dist/doc/latex/captdef/captdef.pdfbin0 -> 222665 bytes
-rw-r--r--Master/texmf-dist/doc/latex/captdef/captdef.tex102
-rw-r--r--Master/texmf-dist/doc/latex/captdef/miscdoc.sty111
3 files changed, 213 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/captdef/captdef.pdf b/Master/texmf-dist/doc/latex/captdef/captdef.pdf
new file mode 100644
index 00000000000..936dfabfd4b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/captdef/captdef.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/captdef/captdef.tex b/Master/texmf-dist/doc/latex/captdef/captdef.tex
new file mode 100644
index 00000000000..afa928a4b53
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/captdef/captdef.tex
@@ -0,0 +1,102 @@
+\documentclass[a4paper]{article}
+\usepackage[a4paper]{geometry}
+\usepackage{miscdoc}
+\usepackage[scaled=0.85]{luximono}
+\begin{document}
+\title{The \Package{captdef} package}
+\author{Robin Fairbairns\thanks{Email: \emph{rf10@cam.ac.uk}}}
+\maketitle
+
+\section{Why this package?}
+
+\LaTeX{} provides a command (\cs{caption}) for adding a caption to a
+float environment (that is to say, a \texttt{figure} or a
+\texttt{table}, ``out of the box'').
+
+The command is a good one, and many users want to use it. Often,
+they end up using a float environment, in a case where it's not
+strictly necessary, and get entangled in the positioning problems
+that floats pose for the innocent user. Using this package, the
+user can have standard-looking captions without the need of a float
+environment.
+
+This package defines a means of defining caption commands, which
+creates things that look as if they were created by \cs{caption}, and
+which work outside of a float.
+
+The \textsf{float} package provides an alternative to
+\cs{captdef}-defined commands, in the float \texttt{[H]} option
+(``place the environment \emph{here} without doing any of this
+floating stuff''). So why use \Package{captdef}?\,---\,its great
+advantage is simplicity; you load it, and it defines just \emph{three}
+macros, while \textsf{float} defines lots and lots. (Of course, if
+you need others of \textsf{float}'s capabilities, \textsf{captdef}
+loses its advantage\dots).
+
+\section{How the package works}
+
+The package defines a command
+\begin{quote}
+ \cmdinvoke*{DeclareCaption}{command}{counter}
+\end{quote}
+which creates a `caption'-like command, which uses \texttt{counter}
+for its numbering.
+
+The package then goes on to declare the commonly-needed caption
+commands \cs{figcaption} and \cs{tabcaption}:
+\begin{quote}
+ \cmdinvoke{captdef}{\cs{figcaption}}{figure}\\
+ \cmdinvoke{captdef}{\cs{tabcaption}}{table}
+\end{quote}
+
+\section{The potential problem}
+
+Commands defined by \cs{captdef} place a caption in text, and also step the
+\environment{figure} (or \environment{table} or whatever) counter. The float
+environments do the same.
+
+Now, consider the sequence:
+\begin{quote}
+\begin{verbatim}
+<earlier text>
+\begin{figure}
+ <figure stuff>
+ \caption{...}
+\end{figure}
+...
+<intervening text>
+...
+<inline figure stuff>
+\figcaption{...}
+\end{verbatim}
+\end{quote}
+and suppose the \environment{figure} environment doesn't fit anywhere
+between where it's specified and the inline figure (so that it will
+float to somewhere later).
+
+We will then see a document with
+\begin{quote}
+\meta{earlier text}\\
+\dots\\
+\meta{intervening text}\\
+\dots\\
+\meta{inline figure stuff}\\
+Figure \meta{n+1}: \dots\\
+\dots\\
+\meta{yet more text}\\
+\dots\\
+\meta{figure stuff}\\
+Figure \meta{n}: \dots
+\end{quote}
+That is, the figure numbers have got out of order, because the
+floating figure was specified before the inline figure.
+
+\LaTeX{} won't do this when everything is specified as a float: it
+keeps floats of the same type in order (which is why floats stack up
+if a single one won't fit).
+
+The moral of that little tale is to say: don't use
+\cs{captdef}-defined commands with floats of the same type in the same
+document. (Or be extra-specially careful about what's happening if
+you must.)
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/captdef/miscdoc.sty b/Master/texmf-dist/doc/latex/captdef/miscdoc.sty
new file mode 100644
index 00000000000..878ff148692
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/captdef/miscdoc.sty
@@ -0,0 +1,111 @@
+\ProvidesPackage{miscdoc}[2010/01/20 v1.2 documentation macros misc latex pkgs]
+
+% miscdoc.sty
+% Copyright 2010 Robin Fairbairns
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Robin Fairbairns.
+%
+% This work consists of the file miscdoc.sty (only)
+
+\setcounter{errorcontextlines}{1274}
+
+% The package arose from a small exercise to document packages whose
+% previous documentation consisted solely of comments in the package files.
+% The macros here defined are lifted from the author's faq.sty
+% (written for the UK TeX FAQ, CTAN:help/uk-tex-faq) or are inspired
+% by others' work (credited where the author is known) ... except
+% where they came as a flash of inspiration while actually writing the
+% documentation.
+
+% this option suggested by Heiko Oberdiek, 2010-01-29
+\DeclareOption{hyper}{%
+ \AtEndOfPackage{%
+ \RequirePackage[pdfusetitle]{hyperref}
+ \RequirePackage{bookmark}
+ \bookmarksetup{numbered,open,openlevel=1}
+ }
+}
+\ProcessOptions\relax
+
+% note: T1 encoding assumed
+\usepackage{lmodern}
+\usepackage[T1]{fontenc}
+\usepackage{booktabs}
+
+% from faq.sty
+\newcommand\cs[1]{\texttt{\char`\\#1}}
+\let\csx\cs
+\def\bsbs{\cs{\char`\\}}
+
+% \cmdinvoke\cs<argument sequence>
+% \cs typeset as above
+% <argument sequence> may consist of optional or mandatory arguments;
+%
+% the `arguments' are simply typesett \texttt, as yet -- if something
+% fancier is needed, there's a bunch of code needs rewriting here...
+\DeclareRobustCommand\cmdinvoke{\@ifstar
+ {\let\@tempa\emph\@scmdinvoke}%
+ {\let\@tempa\relax\@scmdinvoke}%
+}
+\def\@scmdinvoke#1{\texttt{\symbol{92}#1}%
+ \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke{\ifx\@let@token\bgroup
+ \let\@tempb\@cmdinvoke@lbrace
+ \else
+ \ifx\@let@token[% ]
+ \let\@tempb\@cmdinvoke@lbrack
+ \else
+ \ifx\@let@token(% )
+ \let\@tempb\@cmdinvoke@lparen
+ \else
+ \let\@tempb\@empty
+ \fi
+ \fi
+ \fi
+ \@tempb
+}
+\def\@cmdinvoke@lbrace#1{\penalty0\hskip0pt\relax
+ \texttt{\symbol{123}\@tempa{#1}\symbol{125}}%
+ \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke@lbrack[#1]{\penalty-150\hskip0pt\relax
+ \texttt{[\@tempa{#1}]}%
+ \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke@lparen(#1){\penalty-150\hskip0pt\relax
+ \texttt{(\@tempa{#1})}%
+ \futurelet\@let@token\@cmdinvoke
+}
+% and extension -- versions that take a single extra (delimiter)
+% argument, such as \delcmdinvoke{lscrunge}( ... awful syntax, but...
+\DeclareRobustCommand\delcmdinvoke{\@ifstar
+ {\let\@tempa\emph\@sdelcmdinvoke}%
+ {\let\@tempa\relax\@sdelcmdinvoke}%
+}
+\def\@sdelcmdinvoke#1#2{\texttt{\symbol{92}#1#2}%
+ \futurelet\@let@token\@cmdinvoke
+}
+
+% sui generis
+\newcommand\newitem{\par\addvspace{1ex}\noindent}
+
+% inspired by doc.sty in latex distribution
+\newcommand\meta[1]{\ensuremath{\langle}\emph{#1}\ensuremath{\rangle}}
+
+% meaningful names, as in faq.sty
+\let\environment\texttt
+\let\Package\textsf
+\def\option{\@ifnextchar[\@optionb\@option}% ]
+\def\@optionb[#1]{[{\normalfont\ttfamily#1}]}
+\def\@option#1{\texttt{#1}}