From 913673f8f33d20657d1550634367f88adcc7aa50 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 7 Mar 2010 16:57:06 +0000 Subject: captdef doc update (6mar10) git-svn-id: svn://tug.org/texlive/trunk@17353 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/captdef/captdef.pdf | Bin 0 -> 222665 bytes Master/texmf-dist/doc/latex/captdef/captdef.tex | 102 ++++++++++++++++++++++ Master/texmf-dist/doc/latex/captdef/miscdoc.sty | 111 ++++++++++++++++++++++++ Master/texmf-dist/tex/latex/captdef/captdef.sty | 32 +++++++ Master/texmf-dist/tex/latex/ltxmisc/captdef.sty | 32 ------- 5 files changed, 245 insertions(+), 32 deletions(-) create mode 100644 Master/texmf-dist/doc/latex/captdef/captdef.pdf create mode 100644 Master/texmf-dist/doc/latex/captdef/captdef.tex create mode 100644 Master/texmf-dist/doc/latex/captdef/miscdoc.sty create mode 100644 Master/texmf-dist/tex/latex/captdef/captdef.sty delete mode 100644 Master/texmf-dist/tex/latex/ltxmisc/captdef.sty (limited to 'Master/texmf-dist') 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 Binary files /dev/null and b/Master/texmf-dist/doc/latex/captdef/captdef.pdf 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} + +\begin{figure} +
+ \caption{...} +\end{figure} +... + +... + +\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 +% \cs typeset as above +% 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}} diff --git a/Master/texmf-dist/tex/latex/captdef/captdef.sty b/Master/texmf-dist/tex/latex/captdef/captdef.sty new file mode 100644 index 00000000000..b4dbcb546aa --- /dev/null +++ b/Master/texmf-dist/tex/latex/captdef/captdef.sty @@ -0,0 +1,32 @@ +% +% captdef.sty: a trivial package to define captions that don't have +% to be in floats. +% +% Author: Robin Fairbairns +% Conceived ages ago, but written 1998/12/17 +% +% This program can redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt; either +% version 1 of the License, or (at your option) any later version. +% +% Usage: \DeclareCaption{command}{counter} +% +% declare `command' to produce a caption which uses `counter' for its +% numbering. +% +% The package then goes on to use this command to declare the most +% commonly required pair of non-float captions, \figcaption and +% \tabcaption + +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{captdef}[1998/12/17 non-floating captions] + +\newcommand{\DeclareCaption}[2]{% + \def#1{\def\@captype{#2}\caption}% +} + +\DeclareCaption{\figcaption}{figure} +\DeclareCaption{\tabcaption}{table} + +\endinput diff --git a/Master/texmf-dist/tex/latex/ltxmisc/captdef.sty b/Master/texmf-dist/tex/latex/ltxmisc/captdef.sty deleted file mode 100644 index b4dbcb546aa..00000000000 --- a/Master/texmf-dist/tex/latex/ltxmisc/captdef.sty +++ /dev/null @@ -1,32 +0,0 @@ -% -% captdef.sty: a trivial package to define captions that don't have -% to be in floats. -% -% Author: Robin Fairbairns -% Conceived ages ago, but written 1998/12/17 -% -% This program can redistributed and/or modified under the terms -% of the LaTeX Project Public License Distributed from CTAN -% archives in directory macros/latex/base/lppl.txt; either -% version 1 of the License, or (at your option) any later version. -% -% Usage: \DeclareCaption{command}{counter} -% -% declare `command' to produce a caption which uses `counter' for its -% numbering. -% -% The package then goes on to use this command to declare the most -% commonly required pair of non-float captions, \figcaption and -% \tabcaption - -\NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{captdef}[1998/12/17 non-floating captions] - -\newcommand{\DeclareCaption}[2]{% - \def#1{\def\@captype{#2}\caption}% -} - -\DeclareCaption{\figcaption}{figure} -\DeclareCaption{\tabcaption}{table} - -\endinput -- cgit v1.2.3