summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/dashrule
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:52:15 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:52:15 +0000
commitf65d3ae037bad940d29268c5e616cf59cd851baa (patch)
tree88104f0798e480bdbde1c7752445be29dd2a039f /Master/texmf-dist/source/latex/dashrule
parent8dabcb313cc9fdc492ceba59e8982ababe51f0a5 (diff)
trunk/Master/texmf-dist/source/latex/dashrule
git-svn-id: svn://tug.org/texlive/trunk@219 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/dashrule')
-rw-r--r--Master/texmf-dist/source/latex/dashrule/dashrule.dtx400
-rw-r--r--Master/texmf-dist/source/latex/dashrule/dashrule.ins55
2 files changed, 455 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/dashrule/dashrule.dtx b/Master/texmf-dist/source/latex/dashrule/dashrule.dtx
new file mode 100644
index 00000000000..a29bed1652b
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dashrule/dashrule.dtx
@@ -0,0 +1,400 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2001 Scott Pakin <pakin@uiuc.edu>
+% -------------------------------------------------------
+%
+% This package may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.2
+% 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.2 or later is part of all distributions of LaTeX
+% version 1999/12/01 or later.
+%
+% \fi
+% \iffalse
+%% File: dashrule.dtx Copyright (C) 2001 Scott Pakin <pakin@uiuc.edu>
+%
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{dashrule}
+%<package> [2001/04/23 v1.00 Dashed rules (SDP)]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{dashrule}
+\EnableCrossrefs
+\CodelineIndex
+
+% Uncomment the following line if you don't want to include a
+% source-code listing.
+%\OnlyDescription
+
+\begin{document}
+\DocInput{dashrule.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \CheckSum{61}
+% \GetFileInfo{dashrule.sty}
+%
+% \title{The \textsf{dashrule} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{Scott Pakin\\pakin@uiuc.edu}
+% \date{\filedate}
+% \maketitle
+%
+% \changes{v1.00}{2001/04/23}{Initial version}
+%
+% \DoNotIndex{\csname,\DeclareRobustCommand,\def,\else,\endcsname}
+% \DoNotIndex{\expandafter,\fi,\ifodd,\ifx,\let,\newcounter,\relax}
+%
+% \StopEventually{^^A
+% \bigskip\noindent\hdashrule[0pt][x]{\fill}{1pt}{5pt}\rule{5pt}{1pt}
+% \section{Future Work}
+%
+% \textsf{dashrule} \fileversion{} supports only horizontally dashed
+% rules. Future versions (if any) may support vertically dashed
+% rules, as well. For the time being, the \textsf{graphicx}
+% package's \texttt{\string\rotatebox} can be used to define a
+% \texttt{\string\vdashrule} in terms of a rotated
+% \texttt{\string\hdashrule}.
+%
+% The next logical step after adding a \texttt{\string\vdashrule} is
+% to support dashed rectangles, which would be composed of
+% \texttt{\string\hdashrule}s and \texttt{\string\vdashrule}s. Other
+% possible enhancements would be a way of drawing dotted lines,
+% presumably composed from the limited set of circle characters
+% available in \LaTeX's fonts.
+%
+% \bigskip\noindent\hdashrule[0pt][x]{\fill}{1pt}{5pt}\rule{5pt}{1pt}
+% \PrintIndex
+% }
+%
+% \begin{abstract}
+% The \textsf{dashrule} package makes it easy to draw a huge variety
+% of dashed rules (i.e., lines) in \LaTeX. \textsf{dashrule} provides a
+% command, |\hdashrule|, which is a cross between \LaTeX's |\rule| and
+% PostScript's |setdash| command. |\hdashrule| draws horizontally
+% dashed rules using the same syntax as |\rule|, but with an
+% additional, |setdash|-like parameter that specifies the pattern of
+% dash segments and the space between those segments. Because
+% \textsf{dashrule}'s rules are constructed internally using |\rule|
+% (as opposed to, e.g., PostScript |\special|s) they are fully
+% compatible with every \LaTeX{} back-end processor.
+% \end{abstract}
+%
+% \medskip\noindent\hdashrule[0pt][x]{\fill}{1pt}{5pt}\rule{5pt}{1pt}
+% \section{Usage}
+%
+% \DescribeMacro{\hdashrule}
+% \LaTeX's |\rule| command draws a rectangular blob of ink with a given
+% width, height, and distance above the baseline. The
+% \textsf{dashrule} package introduces an analogous command,
+% |\hdashrule|, which draws the same blob of ink, but horizontally
+% dashed. |\hdashrule| takes five parameters, two of which are
+% optional:
+%
+% \bigskip
+% \noindent\hspace{-\leftmargini}%
+% \fbox{\texttt{\string\hdashrule}
+% \oarg{raise} \oarg{leader} \marg{width} \marg{height} \marg{dash}}
+% \bigskip
+%
+% The \meta{raise}, \meta{width}, and \meta{height} parameters have the
+% same meaning as in \LaTeX's |\rule| macro: the distance to raise the rule
+% above the baseline and the width and height of the rule.
+%
+% \meta{leader} determines how the dash pattern should fill \meta{width}
+% amount of space. Because |\hdashrule| is implemented in terms of \TeX's
+% leader commands, the dash pattern must be repeated an integral number of
+% times. \meta{leader} determines what to do with the extra whitespace
+% (always less than the width of the dash pattern) that this requirement
+% introduces. The default, which corresponds to \TeX's |\leaders|
+% command, adds space to both ends of the rule such that the dash patterns
+% from multiple |\hdashrule|s line up. If \meta{leader} is~|c|, which
+% corresponds to \TeX's |\cleaders| command, an equal amount of whitespace
+% will be added to both ends of the rule. If \meta{leader} is~|x|, which
+% corresponds to \TeX's |\xleaders| command, the whitespace will be
+% divided up, and the same amount of whitespace will separate each
+% repetition of the dash pattern.
+%
+% The \meta{dash} argument determines the dash pattern and is analogous
+% to the \textit{array} argument to PostScript's |setdash| function.
+% That is, it is a list of space-separated \meta{dimen}s that alternate
+% ``on'' and ``off'' distances. For instance, ``|2pt 1pt|'' means a
+% 2\,pt.\ rule, followed by a 1\,pt.\ gap, followed by a 2\,pt.\ rule,
+% followed by a 1\,pt.\ gap, and so forth. An odd number of
+% \meta{dimen}s is no different; ``|2pt|'' alternates 2\,pt.\ rules and
+% 2\,pt.\ gaps, and ``|1pt 2pt 3pt|'' repeats ``1\,pt.\ rule, 2\,pt.\
+% gap, 3\,pt.\ rule, 1\,pt.\ gap, 2\,pt.\ rule, 3\,pt.\ gap.''
+%
+%
+% \bigskip\noindent\hdashrule[0pt][x]{\fill}{1pt}{5pt}\rule{5pt}{1pt}
+% \section{Examples}
+%
+% The following are some typical ways to use |\hdashrule|. Each example
+% changes from the previous in only one parameter. For clarity,
+% underlines are used to indicate modified text.
+%
+% \begin{center}
+% \renewcommand{\arraystretch}{1.5}
+% \newcommand{\chg}[1]{\underbar{\texttt{#1}}}
+% \begin{tabular}{l@{\qquad}l}
+% |\hdashrule{2cm}{1pt}{1pt}| &
+% X\hdashrule{2cm}{1pt}{1pt}x \\
+%
+% |\hdashrule{|\chg{4cm}|}{1pt}{1pt}| &
+% X\hdashrule{4cm}{1pt}{1pt}x \\
+%
+% |\hdashrule|\chg{[0.5ex]}|{4cm}{1pt}{1pt}| &
+% X\hdashrule[0.5ex]{4cm}{1pt}{1pt}x \\
+%
+% |\hdashrule[0.5ex]{4cm}{1pt}{|\chg{3mm}|}| &
+% X\hdashrule[0.5ex]{4cm}{1pt}{3mm}x \\
+%
+% |\hdashrule[0.5ex]{4cm}{|\chg{1mm}|}{3mm}| &
+% X\hdashrule[0.5ex]{4cm}{1mm}{3mm}x \\
+%
+% |\hdashrule[0.5ex]{4cm}{1mm}{3mm |\chg{3pt}|}| &
+% X\hdashrule[0.5ex]{4cm}{1mm}{3mm 3pt}x \\
+%
+% |\hdashrule[0.5ex]{4cm}{1mm}{%| \\[-1.5ex]
+% | 3mm 3pt |\chg{1mm 2pt}|}| &
+% X\hdashrule[0.5ex]{4cm}{1mm}{3mm 3pt 1mm 2pt}x \\
+% \end{tabular}
+% \end{center}
+%
+% \bigskip
+% \noindent
+% These next examples show the effect of using different leader types.
+% Each leader is used in both a 4\,cm~wide rule and a 3\,cm~wide rule.
+%
+% \begin{center}
+% \renewcommand{\arraystretch}{1.25}
+% \begin{tabular}{l@{\qquad}l}
+% |\hdashrule[0.5ex]{4cm}{1mm}{8mm 2pt}| &
+% X\hdashrule[0.5ex]{4cm}{1mm}{8mm 2pt}x \\
+%
+% |\hdashrule[0.5ex]{3cm}{1mm}{8mm 2pt}| &
+% X\hdashrule[0.5ex]{3cm}{1mm}{8mm 2pt}x \\[2ex]
+%
+% |\hdashrule[0.5ex][c]{4cm}{1mm}{8mm 2pt}| &
+% X\hdashrule[0.5ex][c]{4cm}{1mm}{8mm 2pt}x \\
+%
+% |\hdashrule[0.5ex][c]{3cm}{1mm}{8mm 2pt}| &
+% X\hdashrule[0.5ex][c]{3cm}{1mm}{8mm 2pt}x \\[2ex]
+%
+% |\hdashrule[0.5ex][x]{4cm}{1mm}{8mm 2pt}| &
+% X\hdashrule[0.5ex][x]{4cm}{1mm}{8mm 2pt}x \\
+%
+% |\hdashrule[0.5ex][x]{3cm}{1mm}{8mm 2pt}| &
+% X\hdashrule[0.5ex][x]{3cm}{1mm}{8mm 2pt}x \\
+% \end{tabular}
+% \end{center}
+%
+% \noindent
+% Notice how the dashes in the first pair of |\hdashrule|s line up; the
+% rules in the second pair each have an equal amount of whitespace on
+% either side of the rule; and the rules in the third pair have extra
+% spaces within the dash pattern itself instead of around it. The
+% |x|~qualifier is rarely useful for dashed rules, because it alters the
+% pattern itself. (I included |x| for completeness, not practicality.)
+% However, |x| does enable rules with long dashes to better fill a
+% comparatively small width, as in the following example:
+%
+% \begin{center}
+% \renewcommand{\arraystretch}{1.25}
+% \begin{tabular}{l@{\qquad}l}
+% |\hdashrule[0.5ex][x]{3in}{2pt}{2cm 0pt}| \\
+% X\hdashrule[0.5ex][x]{3in}{2pt}{2cm 0pt}x
+% \end{tabular}
+% \end{center}
+%
+% \noindent
+% The gaps in the above are clearly wider than~|0pt|, but they \emph{are}
+% evenly spaced.
+%
+% \bigskip\noindent\hdashrule[0pt][x]{\fill}{1pt}{5pt}\rule{5pt}{1pt}
+% \section{Differences from \texttt{setdash}}
+%
+% |\hdashrule| is different from PostScript's |setdash| command in the
+% following ways:
+%
+% \begin{itemize}
+% \item |setdash| takes on/off values in terms of PostScript points
+% (\TeX{} ``big points'' or~``|bp|''), while |\hdashrule| requires
+% explicit units.
+%
+% \item There is no equivalent of |setdash|'s \textit{offset}
+% parameter, to specify a starting offset into the pattern. If you're
+% desperate, you can fake \textit{offset} with a leading |\rule| and
+% |\hspace|.
+%
+% \item Unlike |setdash|, |\hdashrule| can't draw a solid line. Use
+% |\rule| for solid lines.
+% \end{itemize}
+%
+%
+% \noindent\hdashrule[0pt][x]{\fill}{1pt}{5pt}\rule{5pt}{1pt}
+% \section{Implementation}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macro}{\hdr@do@rule}
+% This macro is exactly like \LaTeX's |\rule|, except that the optional
+% argument is required, and it has the side effect of pointing
+% |\hdr@do@something| to |\hdr@do@skip|.
+% \begin{macrocode}
+\def\hdr@do@rule[#1]#2#3{%
+ \rule[#1]{#2}{#3}%
+ \let\hdr@do@something=\hdr@do@skip
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hdr@do@skip}
+% This macro takes the same arguments as |\hdr@do@rule|, but instead of
+% drawing a rule, it inserts an equivalent amount of horizontal
+% whitespace. Additionally, it points |\hdr@do@something| to
+% |\hdr@do@rule| as a side effect.
+% \begin{macrocode}
+\def\hdr@do@skip[#1]#2#3{%
+ \hspace*{#2}%
+ \let\hdr@do@something=\hdr@do@rule
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\c@hdr@segments}
+% \begin{macro}{\hdr@tally@segments}
+% Dash patterns containing an odd number of segments are treated
+% differently from dash patterns containing an even number of segments.
+% We therefore define a macro, |\hdr@tally@segments|, which counts the
+% number of space-separated segments in a dash pattern and stores the
+% tally in the |hdr@segments| counter. Note that |hdr@segments| should
+% be initialized to~|0| before invoking |\hdr@tally@segments|.
+% \begin{macrocode}
+\newcounter{hdr@segments}
+\def\hdr@tally@segments#1 {%
+ \ifx#1!%
+ \else
+ \addtocounter{hdr@segments}{1}%
+ \expandafter\hdr@tally@segments%
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\hdashrule}
+% This is the only macro in \textsf{dashrule}'s external interface.
+% |\hdashrule@ii| does all the work for |\hdashrule|, though. All
+% |\hdashrule| itself does is invoke |\hdashrule@i| with its first
+% optional argument, or~|0.0pt| if none was provided. |\hdashrule@i|,
+% in turn, invokes |\hdashrule@ii| with the two optional arguments,
+% supplying |\empty| as the default value of the second optional
+% argument.
+% \begin{macrocode}
+\DeclareRobustCommand{\hdashrule}{\@testopt{\hdashrule@i}{0pt}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hdashrule@i}
+% Supply |\empty| as the default second argument and call
+% |\hdashrule@ii|.
+% \begin{macrocode}
+\def\hdashrule@i[#1]{\@testopt{\hdashrule@ii[#1]}\empty}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hdashrule@ii}
+% Now we can do the real work for |\hdashrule|. |\hdashrule@ii| takes
+% the following parameters:
+%
+% \begin{center}
+% \begin{tabular}{ccccc}
+% |#1| & |#2| & |#3| & |#4| & |#5| \\
+% \oarg{raise} & \oarg{leader} & \marg{width} & \marg{height} & \marg{dash}
+% \end{tabular}
+% \end{center}
+%
+% The \meta{raise}, \meta{width}, and \meta{height} parameters have the
+% same meaning as in \LaTeX's |\rule| macro. \meta{leader} specifies
+% which \TeX{} leader function to use to fill \meta{width} amount of
+% space. It should be |c| for |\cleaders|, |x| for |\xleaders|, or
+% nothing for ordinary |\leaders|. The \meta{dash} argument determines
+% the dash pattern and is analogous to the \textit{array} argument to
+% PostScript's |setdash| function. That is, it is a list of
+% space-separated \meta{dimen}s that alternate ``on'' and ``off''
+% distances.
+% \begin{macrocode}
+\def\hdashrule@ii[#1][#2]#3#4#5{%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hdr@do@something}
+% The |\hdr@do@something| alias alternates between |\hdr@do@rule|
+% and |\hdr@do@skip|, starting with |\hdr@do@rule|.
+% \begin{macrocode}
+ \let\hdr@do@something=\hdr@do@rule
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hdr@parse@dash}
+% For every space-separated \meta{dimen} in \meta{dash}, we invoke
+% |\hdr@do@something| to draw a rule or a space, as appropriate. We
+% define |\hdr@parse@dash| within |\hdashrule@ii| so we don't have to
+% pass in |\hdashrule@ii|'s~|#1| and~|#4| on every invocation.
+% \begin{macrocode}
+ \def\hdr@parse@dash##1 {%
+ \ifx##1!%
+ \else
+ \hdr@do@something[#1]{##1}{#4}%
+ \expandafter\hdr@parse@dash%
+ \fi
+ }%
+% \end{macrocode}
+% We now count the number of segments in the dash pattern, so we can
+% determine if we have an even or odd number of them.
+% \begin{macrocode}
+ \setcounter{hdr@segments}{0}%
+ \hdr@tally@segments#5 !
+% \end{macrocode}
+% Finally, we invoke |\leaders|, |\cleaders|, or |\xleaders| to draw the
+% dashed line, repeating the pattern until \meta{width} space is filled.
+% The trick here is that odd-lengthed pattern descriptions must be
+% repeated to yield the complete pattern. For instance, the pattern
+% ``|1pt|'' is actually short for ``1\,pt.\ rule, 1\,pt.\ space,'' and
+% ``|2pt 4pt 6pt|'' is an abridged version of ``2\,pt.\ rule, 4\,pt.\
+% space, 6\,pt.\ rule, 2\,pt.\ space, 4\,pt.\ rule, 6\,pt.\ space.''
+% Although it is valid to repeat even-length patterns, as well---an
+% earlier draft of |\hdashrule@ii| did just that---this produces
+% inferior results, because \TeX's various leader commands do not split
+% boxes. The longer the pattern, the less likely it will fit
+% snugly into the given width.
+% \begin{macrocode}
+ \ifodd\c@hdr@segments
+ \csname#2leaders\endcsname%
+ \hbox{\hdr@parse@dash#5 #5 ! }%
+ \hskip#3\relax
+ \else
+ \csname#2leaders\endcsname%
+ \hbox{\hdr@parse@dash#5 ! }%
+ \hskip#3\relax
+ \fi%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
diff --git a/Master/texmf-dist/source/latex/dashrule/dashrule.ins b/Master/texmf-dist/source/latex/dashrule/dashrule.ins
new file mode 100644
index 00000000000..21ddf0c4bf5
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dashrule/dashrule.ins
@@ -0,0 +1,55 @@
+%%
+%% This file will generate fast loadable files and documentation
+%% driver files from the doc files in this package when run through
+%% LaTeX or TeX.
+%%
+%% Copyright (C) 2001 Scott Pakin <pakin@uiuc.edu>
+%% -------------------------------------------------------
+%%
+%% This package may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.2
+%% 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.2 or later is part of all distributions of LaTeX
+%% version 1999/12/01 or later.
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\input docstrip
+
+\keepsilent
+
+\usedir{tex/latex/dashrule}
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2001 Scott Pakin <pakin@uiuc.edu>
+-------------------------------------------------------
+
+This package may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.2
+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.2 or later is part of all distributions of LaTeX
+version 1999/12/01 or later.
+
+\endpreamble
+
+\generate{\file{dashrule.sty}{\from{dashrule.dtx}{package}}}
+
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation, you have to move}
+\Msg{* dashrule.sty into a directory searched by TeX.}
+\Msg{*}
+\Msg{* To produce the documentation, run dashrule.dtx}
+\Msg{* through LaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{***********************************************************}
+
+\endbatchfile