% \iffalse meta-comment
%
%% decorule.dtx
%% Copyright © 2010-2011 by Peter Flynn <peter@silmaril.ie>
%
% 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 Peter Flynn <peter@silmaril.ie>
%
% This work consists of the files decorule.dtx and decorule.ins
% and the derived file decorule.sty.
%
% \fi
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[2009/09/24]
%<package>\ProvidesPackage{decorule}[2011/06/13 v0.22 The decorule LaTeX2e package]
%<package>\RequirePackage{graphicx}
%<package>\RequirePackage{fix-cm}
%<*driver>
\documentclass[12pt]{ltxdoc}
\usepackage{decorule}
\usepackage{fancyvrb}
\usepackage{mflogo}
\usepackage{chicago}
\usepackage{url}
\usepackage{nicefrac}
\makeatletter
\newcommand{\classorpackage}{package}
\newcommand{\ConTeXt}{%
	C\kern-.0333emon\-\kern-.0667em\TeX\kern-.0333emt}
\makeatother
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{decorule.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{133}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
% 
% \changes{v0.22}{2011/06/13}{Bugs fixed on first release: 1) Added missing packages (graphicx and fix-cm); 2) Removed bogus change record from .sty file.}
% \changes{v0.21}{2011/06/11}{Revised for .dtx file: 1) Rewrote documentation; 2) Generated .dtx.}
% \changes{v0.20}{2010/07/14}{Updated to package format: Wrote .dtx file by hand.}
% \changes{v0.11}{2010/03/20}{Written for TUGboat: Developed by hand.}
%
% \GetFileInfo{decorule.sty}
%
% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
% \DoNotIndex{\@flushglue,\@gobble,\@input}
% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
% \DoNotIndex{\mathcal,\csname,\def,\documentstyle,\dospecials,\edef}
% \DoNotIndex{\egroup}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
% \DoNotIndex{\ifcase}
% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
% \DoNotIndex{\strutbox}
% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
% \DoNotIndex{\nopagebreak}
% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
% \DoNotIndex{\[,\{,\},\]}
% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
% \DoNotIndex{\baselineskip,\begin,\tw@}
% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
% \DoNotIndex{\bfdefault}
%
% \title{The \textsf{decorule} LaTeX2e package\thanks{This document corresponds to \textsf{decorule}~\fileversion, dated \filedate.}}
% \author{Peter Flynn\\\normalsize Silmaril Consultants\\[-4pt]\normalsize Textual Therapy Division\\\normalsize(\texttt{peter@silmaril.ie})}
% \maketitle
% \renewcommand{\abstractname}{Summary}\thispagestyle{empty}
% \begin{abstract}\noindent
% This package implements a decorative swelled rule using
% only a symbol from a font installed with all distributions of
% \TeX{}, so it works independently, without the need to install
% any additional software or fonts.\par
% This is the packaged version of the macro which was
% originally published in the `Typographers' Inn'
% column in TUGboat \cite{tb97}.\par
% \end{abstract}
% \clearpage
% \tableofcontents
% \clearpage
% \section{Swelled rules}
% Swelled rules were a popular device in 19th century
% typesetting, and were usually done as special sorts from a
% typefounder, or in some cases fabricated from combinations of
% decorative brass rule cut to calculated lengths.\par
% In digital systems, they can be implemented as images or
% as glyphs in fonts, but are not usually extensible except by
% distortion. This example is constructed programmatically so
% that it could be adapted to the width it is required for (that
% feature is not implemented in this version and is left as an
% exercise to the user).\par
% \subsection{Other work}
% As discussed in the original article \cite{tb97} there is an \textsf{swrule} package
%   by Tobias Dussa \cite{dussa} which builds a
%   geometric lozenge from very fine lines, and there is a paper
%   by Steve Peter \cite{peter} which describes
%   a more extensible method using \MP{} for
%   \ConTeXt{}.\par
% \subsection{This solution}
% However, it is also possible to produce one using just a
%   character from a font, combined with some looping in a macro
%   with careful positioning and kerning. This example was
%   constructed from the swung dash (\verb`\sim`)
%   character in math mode, rotated and scaled to fit in an
%   asending and then descending series.\par
% The example is available at
%   \url{http://latex.silmaril.ie/packages/decorule}, and
%   any suggestions for improving and extending it are welcome.
%   When this packaging is complete, it will be resubmitted to
%   CTAN.\par
% {\bigskip\centering{}\decorule{}\par}
% \clearpage
% \section{License}
% This is free software under the terms of the \LaTeX{}
% Project Public License (LPPL).\par
% This software is copyright but you are granted a license
% which gives you, the `user' of the
% software, legal permission to copy, distribute, and/or modify
% the software.\par
% However, if you modify the software and then distribute it
% (even just locally) you \emph{must} change the
% name of the software, or use other technical means to avoid
% confusion.\par
% Details of the license version, date, and maintainer are
% in the headers of the \url{.dtx} and
% \url{.ins} files in this package.\par
% For full details of the LPPL, please see
% \url{http://www.latex-project.org/lppl/}.\par
% \clearpage
% \raggedright
% \addtocontents{toc}{\medskip}
% \addcontentsline{toc}{section}{\refname}
% \bibliography{decorule}
% \bibliographystyle{chicago}
% \begin{VerbatimOut}{decorule.bib}
%<*ignore>
@article{tb97,
author 	 = {Peter Flynn},
shortauthor 	 = {Flynn},
title 	 = {{Typographers' Inn: Where have all the flowers gone?}},
pages 	 = {21-22},
journal 	 = {{TUGboat}},
volume 	 = {31},
number 	 = {1},
year 	 = {2010}
}
@article{peter,
author 	 = {Steve Peter},
shortauthor 	 = {Peter},
title 	 = {{Swelled rules and \MP{}}},
pages 	 = {193-195},
journal 	 = {{TUGboat}},
volume 	 = {26},
number 	 = {3},
year 	 = {2005}
}
@misc{dussa,
author 	 = {Tobias Dussa},
shortauthor 	 = {Dussa},
title 	 = {{swrule.sty}},
year 	 = {2001},
month 	 = {Oct},
howpublished 	 = {CTAN: \TeX{} Users Group},
url 	 = {http://mirror.ctan.org/macros/generic/misc/swrule.sty}
}
%</ignore>
% \end{VerbatimOut}
% \StopEventually{%
%   \clearpage
%   \PrintChanges
%   \clearpage
%   \PrintIndex}
% \clearpage
% \section{Implementation}
% The package consists of a single main macro \verb`\decorule`\DescribeMacro{\decorule}, which cycles through sizes
% of the symbol from minimum to maximum, rotating and scaling
% according to values preset here; and then from the maximum
% back down to the minimum.\par
% \subsection{Preliminary declarations}
% \begin{macro}{\sym@min}
% Define a counter and a minimum point size to start and
%     end with. This value is an integer, hence a counter is
%     used.\par
%    \begin{macrocode}
\newcounter{sym@min}
\setcounter{sym@min}{1}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sym@max}
% Do the same for the maximum point size that the rule
%     will get to in the middle.\par
%    \begin{macrocode}
\newcounter{sym@max}
\setcounter{sym@max}{20}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sym@step}
% Set the step size or the increments of the glyph in
%     whole points.\par
%    \begin{macrocode}
\newcounter{sym@step}
\setcounter{sym@step}{1}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sym@rotate}
% Specify the amount in (whole) degrees by which we will
%     need to rotate the symbol to make eah glyph mesh with the
%     previous one.\par
%    \begin{macrocode}
\newcounter{sym@rotate}
\setcounter{sym@rotate}{45}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sym@size}
% Define a counter to hold the current (calculated) size
%     as we loop through the sizes.\par
%    \begin{macrocode}
\newcounter{sym@size}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sym@raise}
% Define a length to hold the amount calculated at each
%     step to raise/lower each glyph by (because we rotate them as
%     we go).\par
%    \begin{macrocode}
\newlength{\sym@raise}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sym@skip}
% Define another length to hold the amount calculated to
%     backspace between successive glyphs to make sure they
%     touch.\par
%    \begin{macrocode}
\newlength{\sym@skip}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sym@symbol}
% Lastly, define the font character to use as the glyph.
%     For the swelled rule we use the swung dash.\par
%    \begin{macrocode}
\newcommand{\sym@symbol}{$\sim$}
%    \end{macrocode}
% \end{macro}
% \subsection{The main macro}
% \begin{macro}{\decorule}
% Now we can define the macro that does the actual
%     work.\par
% \changes{v0.21}{2011/06/06}{Rearranged spacing to suit the .dtx layout}
%    \begin{macrocode}
\newcommand{\decorule}{%
%    \end{macrocode}
% Start by setting the initial size to the minimum size
%     declared above:\par
%    \begin{macrocode}
\setcounter{sym@size}{\c@sym@min}
%    \end{macrocode}
% Go through the steps up to, but not including, the
%     maximum size:\par
%    \begin{macrocode}
\loop
%    \end{macrocode}
% Raise each glyph above the baseline by half the
%     point size that we will use:\par
%    \begin{macrocode}
\setlength{\sym@raise}{\c@sym@size pt}%
    \divide\sym@raise by2
%    \end{macrocode}
% Raise, rotate, and (in this case of
%     \verb`\sim`) reflect the glyph in a
%     \verb`\hbox` of its own point size, using
%     \verb`\hss` to prevent \TeX{} squawking:\par
%    \begin{macrocode}
\raisebox{-\sym@raise}{%
      \fontsize{\c@sym@size}{0}\selectfont
      \rotatebox{\c@sym@rotate}{\reflectbox{\hbox
          to\c@sym@size pt{\hss\sym@symbol\hss}}}}%
%    \end{macrocode}
% Calculate the amount to backspace as \nicefrac23 of the
%     current size:\par
%    \begin{macrocode}
\setlength{\sym@skip}{\c@sym@size pt}%
    \divide\sym@skip by3
    \multiply\sym@skip by2
    \kern-\sym@skip
%    \end{macrocode}
% Increment the counter and repeat:\par
%    \begin{macrocode}
\addtocounter{sym@size}{\c@sym@step}%
    \ifnum\c@sym@size<\c@sym@max
  \repeat
%    \end{macrocode}
% Now do the same for the sole occurrence of the maximum
%     size:\par
%    \begin{macrocode}
\setlength{\sym@raise}{\c@sym@max pt}%
  \divide\sym@raise by2
  \raisebox{-\sym@raise}{%
    \fontsize{\c@sym@max}{0}\selectfont
    \rotatebox{\c@sym@rotate}{\reflectbox{\hbox
        to\c@sym@max pt{\hss\sym@symbol\hss}}}}%
%    \end{macrocode}
% Start back down following the exact same pattern in
%     reverse, using the current size (one step less than the
%     maximum just used). The value has been left undisturbed
%     from the last loop of the outward journey. This time,
%     however, do the kerning \emph{before} the
%     glyph.\par
%    \begin{macrocode}
\loop
    \setlength{\sym@skip}{\c@sym@size pt}%
    \divide\sym@skip by3
    \multiply\sym@skip by2
    \kern-\sym@skip
    \setlength{\sym@raise}{\c@sym@size pt}%
    \divide\sym@raise by2
    \raisebox{-\sym@raise}{%
    \fontsize{\c@sym@size}{0}\selectfont
    \rotatebox{\c@sym@rotate}{\reflectbox{\hbox
        to\c@sym@size pt{\hss\sym@symbol\hss}}}}%
    \addtocounter{sym@size}{-\c@sym@step}%
    \ifnum\c@sym@size>\c@sym@min
  \repeat
%    \end{macrocode}
% Finally, do the minimum size:\par
%    \begin{macrocode}
\setlength{\sym@skip}{\c@sym@min pt}%
  \divide\sym@skip by3
  \multiply\sym@skip by2
  \kern-\sym@skip
  \setlength{\sym@raise}{\c@sym@min pt}%
  \divide\sym@raise by2
  \raisebox{-\sym@raise}{%
  \fontsize{\c@sym@min}{0}\selectfont
  \rotatebox{\c@sym@rotate}{\reflectbox{\hbox
        to\c@sym@min pt{\hss\sym@symbol\hss}}}}%
}
%    \end{macrocode}
% \end{macro}
% \Finale
\endinput
