path: root/Master/texmf-dist/source/latex/ncctools/nccrules.dtx

% \iffalse
%%
%% File: nccrules.dtx Copyright (C) 2005 by Alexander I. Rozhenko
%%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{nccrules}
%<package>      [2005/05/13 v1.0 More rules (NCC)]
%
% \changes{v1.0}{2005/05/13}{This version was uploaded to CTAN}
%
%<*driver>
\let\makeindex\relax
\documentclass{ltxdoc}
\usepackage{nccrules}
\newfootnoterule{starred}{\mboxfill[1.5\width][s]{$*$}}
\newfootnoterule{dotted}{\mboxfill[2\width][s]{.}}
\newfootnotedashrule{double}{}{.4 1 .4}
\newfootnotedashrule{dashed}{3 3}{.4}
\newfootnotedashrule{dotdashed}{4 2 1 2 4 -4}{.6}
\newfootnotedashrule{ddotdashed}{6 2 1 2 1 2 6 -6}{.6}
\GetFileInfo{nccrules.sty}
\begin{document}
\title{The \textsf{nccrules} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{Alexander I. Rozhenko\\rozhenko@oapmg.sscc.ru}
\date{\filedate}
\maketitle
\DocInput{nccrules.dtx}
\end{document}
%</driver>
% \fi
% This package implements
% |\dashrule| and |\dashrulefill| commands,
% that simplify composing of dashed
% lines and dashed multilines. Two kinds of footnote rule generation
% commands are also introduced: |\newfootnoterule| creates a footnote
% rule with an arbitrary contents and |\newfootnotedashrule| creates
% a footnote rule based on dash rule.
%
% \tableofcontents
%
% \section{User Interface}
%
% \subsection{Dash Rules}
%
% \DescribeMacro\dashrule
% The command
% \begin{quote}
% |\dashrule|\oarg{raise}\marg{h-pattern}\marg{v-pattern}
% \end{quote}
% prepares a dash rule. Its syntax is quite similar to the |\rule| command
% except that \meta{h-pattern} and \meta{v-pattern} can contain a list of
% sizes delimited with spaces. List sizes are interpreted as follows:
% size, space, size, space, etc. In other words, every odd size is a
% size of rule part and every even size is a space between neighbour parts.
% If the last size in the list is even
% (means a space), its space value is divided by two and
% is added before the first rule part and after the last rule part.
% Units in sizes can be omitted. In this case, pt-units are supposed.
% Examples:
% \begin{center}
% \begin{tabular}{@{}l@{\qquad\qquad}l@{}}
% x\dashrule[.5ex]{10mm}{1pt}x &
% |x\dashrule[.5ex]{10mm}{1pt}x| \\
% x\dashrule{5mm 3 3 3 5mm}{.4}x &
% |x\dashrule{5mm 3 3 3 5mm}{.4}x| \\
% x\dashrule{1}{3 2 3}x&
% |x\dashrule{1}{3 2 3}x|\\
% x\dashrule{2 2}{2 2}x &
% |x\dashrule{2 2}{2 2}x|\\
% x\dashrule{5 3 1 3 5 10}{1 1 0.4 1 1}x &
% |x\dashrule{5 3 1 3 5 10}{1 1 0.4 1 1}x|
% \end{tabular}
% \end{center}
%
% \DescribeMacro\dashrulefill
% The command
% \begin{quote}
% |\dashrulefill|\oarg{raise}\oarg{leader-type}\marg{h-pattern}\marg{v-pattern}
% \end{quote}
% fills a free space with a dash rule. The rule is composed from the 1st,
% 3rd, and 4th arguments of the command and is repeated as more times as
% necessary to fill a free horizontal space. The rest of space after filling is
% stored depending on \meta{leader-type} used. Default leader type
% is ``aligned leaders'': every rule is aligned to the multiple of its width
% counted from the left boundary of filled box. Other cases are: |c| means
% centered leaders (all extra spaces are collected at both ends of fill
% area), |x| means distributed leaders (extra spaces are uniformly
% distributed between every dash rule), and |s| means stretched leaders
% (the space in h-pattern going after the last rule size is considered as
% stretchable space and rules are stretched to the whole width of the
% fill area).
%
% Example:
% \begin{flushleft}
% |\noindent x\dashrulefill{2 2}{2}\mbox{}\\|\\
% |xxxxx\dashrulefill[.4ex]{2 2}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][c]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][x]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][s]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][s]{4 2 1 2 4 -4}{1}\mbox{}\\[1ex]|\\
% |\mbox{}\dashrulefill[0mm][c]{2 3}{2 3 2 3 2}\mbox{}\\|\\
% |\mbox{}\dashrulefill{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\|\\
% |\mbox{}\dashrulefill[0mm][c]{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\[-2ex]|\\
% |\mbox{}\hrulefill|
% \end{flushleft}
%
% It produces the following:
%
% \noindent x\dashrulefill{2 2}{2}\mbox{}\\
% xxxxx\dashrulefill[.4ex]{2 2}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][c]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][x]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][s]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][s]{4 2 1 2 4 -4}{1}\mbox{}\\[1ex]
% \mbox{}\dashrulefill[0mm][c]{2 3}{2 3 2 3 2}\mbox{}\\
% \mbox{}\dashrulefill{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\
% \mbox{}\dashrulefill[0mm][c]{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\[-2ex]
% \mbox{}\hrulefill
%
% \subsection{Custom Footnote Rules}
%
% In |manyfoot| package, you can separate footnote levels
% with custom footnote rules. In this package we provide two ways for
% creation such rules. All footnote rules should follow the following
% contract: they must be prepared as |\hrule| or |\hbox|; the total height
% of rule or box must be compensated with kerns. Usually a negative
% kern is inserted before a footnote rule and a nonnegative kern is
% inserted after the rule. The sum of both kerns and of total height of
% rule must be equal to zero. We follow this contract in footnote rules
% created with this package.
%
% In |manyfoot| package, every footnote rule must have a name
% |\|\meta{prefix}|footnoterule|. So, we need to specify the prefix only
% when a new footnote rule is constructed. Next that we need to specify is
% a rule width. If width is omitted, the default width of |0.4\columnwidth|
% is used. The footnote rule generation commands described below
% are used in the preamble only.
%
% \DescribeMacro\newfootnoterule
% The command
% \begin{quote}
% |\newfootnoterule|\marg{prefix}\oarg{width}\marg{rule code}
% \end{quote}
% produces a custom user-defined rule.
% The \meta{rule code} must be stretchable to the given width.
% The |\mboxfill| command from the |mboxfill| package is useful in it.
% Examples:
% \begin{quote}
% |\newfootnoterule{starred}{\mboxfill[1.5\width][s]{$*$}}|\\
% |\newfootnoterule{dotted}{\mboxfill[2\width][s]{.}}|
% \end{quote}
% The |\starredfootnoterule| and |\dottedfootnoterule| commands
% are created here. They produce the following rules:
%
% \vspace{3mm}
% \starredfootnoterule
% \dottedfootnoterule
%
% \DescribeMacro\newfootnotedashrule
% The command
% \begin{quote}
% |\newfootnotedashrule|\marg{prefix}\oarg{width}\marg{h-pattern}\marg{v-pattern}
% \end{quote}
% produces a dash footnote rule. The special case, when \meta{h-pattern}
% is empty means the solid rule. Examples:
% \begin{quote}
% |\newfootnotedashrule{double}{}{.4 1 .4}|\\
% |\newfootnotedashrule{dashed}{3 3}{.4}|\\
% |\newfootnotedashrule{dotdashed}{4 2 1 2 4 -4}{.6}|\\
% |\newfootnotedashrule{ddotdashed}{6 2 1 2 1 2 6 -6}{.6}|
% \end{quote}
% The following rules are created here:
% |\doublefootnoterule|, |\dashedfootnoterule|,
% |\dotdashedfootnoterule|, and |\ddotdashedfootnoterule|.
% They produce the following rules:
%
% \vspace{2mm}%
% \doublefootnoterule
% \dashedfootnoterule
% \dotdashedfootnoterule
% \ddotdashedfootnoterule
%
% \StopEventually{}
%
% \section{The Implementation}
%
% The |mboxfill| package is required here:
%    \begin{macrocode}
%<*package>
\RequirePackage{mboxfill}
%    \end{macrocode}
%
% \begin{macro}{\dashrule}
% |\dashrule|\oarg{raise}\marg{h-pattern}\marg{v-pattern}
%    \begin{macrocode}
\newcommand\dashrule{}
\DeclareRobustCommand*\dashrule[3][\z@]{%
  \setbox\@tempboxa\vbox{}%
  \NCC@composedash{\NCC@vdash{#2}}{#3}%
  \setlength\@tempdima{#1}\leavevmode
  \raise\@tempdima\hbox{%
    \vbox to\@tempdimc{\vss\unvbox\@tempboxa\vss}}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\dashrulefill}
% |\dashrulefill|\oarg{raise}\oarg{leader-type}\marg{h-pattern}\marg{v-pattern}\\
% This command is a composition of the |\mboxfill| and
% |\dashrule| commands. A trick is applied here:
% we decrease dash rule width on the value of last space
% in it and then apply |\mboxfill|.
%    \begin{macrocode}
\newcommand*\dashrulefill[1][\z@]{%
  \@ifnextchar[{\NCC@dashfill{#1}}{\NCC@dashfill{#1}[]}%
}
\def\NCC@dashfill#1[#2]#3#4{%
  \NCC@composedash{}{#3}%
  \advance\@tempdimb-\@tempdimc
  \setbox\@tempboxa\hb@xt@-\@tempdimb
    {\hss\dashrule[#1]{#3}{#4}\hss}%
  \mboxfill[\@tempdimc][#2]{\box\@tempboxa}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@composedash}
% |\NCC@composedash|\marg{action}\marg{pattern} parses the pattern
% and calls the action when a rule size is parsed. At this point,
% the |\@tempdima| contains a size parsed and |\@tempdimb| contains
% the previous space. In |\@tempdimc|, the whole rule size is calculated.
%    \begin{macrocode}
\def\NCC@composedash#1#2{%
  \@tempdimb\z@ % Last space
  \@tempdimc\z@ % Accumulator
  \@tempswatrue % True value means producing an entry
  \NCC@parsedash#2 ! !\@nil{%
    \advance\@tempdimc\@tempdima
    \if@tempswa #1\@tempswafalse \else
      \@tempdimb\@tempdima \@tempswatrue
    \fi
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@parsedash}
% Pattern parser:
%    \begin{macrocode}
\def\NCC@parsedash#1 #2\@nil#3{%
  \if/#1/\else % Empty arg. ignored
    \ifx#1!\else % Exclamation mark ends the list
      \@defaultunits\@tempdima#1pt\relax\@nnil
      #3\NCC@parsedash#2\@nil{#3}%
    \fi
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@vdash}
% |\NCC@vdash|\marg{h-pattern} is
% applied when a vertical dash is composed.
% |\@tempdimb| contains the required skip,
% |\@tempdima| contains the rule height.
%    \begin{macrocode}
\def\NCC@vdash#1{%
  \setbox\@tempboxa\vbox{%
    \unvbox\@tempboxa \vskip\@tempdimb
    \setbox\@tempboxa\hbox{}%
    \@tempskipa\@tempdima % Save rule height in \@tempskipa
    \NCC@composedash{\NCC@hdash}{#1}%
    \hb@xt@\@tempdimc{\hss\unhbox\@tempboxa\hss}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@hdash}
% This action is applied when a horizontal dash is composed.
% |\@tempdimb| contains the required skip,
% |\@tempdima| contains the rule width,
% |\@tempskipa| contains the rule height.
%    \begin{macrocode}
\def\NCC@hdash{%
  \setbox\@tempboxa\hbox{%
    \unhbox\@tempboxa \kern\@tempdimb
    \vrule \@width\@tempdima \@height\@tempskipa
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnoterule}
% |\NCC@fnoterule|\marg{width}\marg{rule code}\\
% This is the footnote rule producing command.
% As usual, two kerns must be inserted surround the rule: a negative
% kern before the rule and a nonnegative kern after the rule.
% The sum of kern values and of the total rule height must
% vanish. Kerns are calculated in such a way to vertically center
% the rule relative to 2.8pt distance top to the current position.
% If the total height of rule is greater than 5.6pt, the rule is moved
% up on the total rule height (the kern after the rule is zero in this case).
%    \begin{macrocode}
\def\NCC@fnoterule#1#2{%
  \setlength\@tempdima{#1}%
  \setbox\@tempboxa\hb@xt@\@tempdima{#2}%
  \@tempdima\ht\@tempboxa \advance\@tempdima\dp\@tempboxa
  \@tempdimb 2.8\p@ \@tempdimc .5\@tempdima
  \ifdim\@tempdimc>\@tempdimb \@tempdimb\@tempdimc \fi
  \advance\@tempdimb\@tempdimc
  \kern-\@tempdimb
  \box\@tempboxa
  \advance\@tempdimb -\@tempdima
  \kern\@tempdimb
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnotedashrule}
% |\NCC@fnotedashrule|\marg{width}\marg{h-pattern}\marg{v-pattern}\\
% Produces the rule based on |\dashrulefill|. A special case of empty
% \meta{h-pattern} means the solid (maybe multi-line) rule.
%    \begin{macrocode}
\def\NCC@fnotedashrule#1#2#3{%
  \NCC@fnoterule{#1}{\def\@tempa{#2}%
    \ifx\@tempa\@empty
      \@tempskipb\@tempdima \dashrule{\@tempskipb}{#3}%
    \else
      \dashrulefill[\z@][s]{#2}{#3}%
    \fi
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnotecreate}
% |\NCC@fnotecreate|\marg{prefix}\marg{body}\\
% Creates a footnote rule whose name is composed from the
% given \meta{prefix} and |footnoterule|. For example if the prefix
% is |dashed|, the |\dashedfootnoterule| command will be created.
%    \begin{macrocode}
\def\NCC@fnotecreate#1{%
  \edef\@tempa{\noexpand\newcommand*%
    \expandafter\noexpand\csname #1footnoterule\endcsname}%
  \@tempa
}
\@onlypreamble\NCC@fnotecreate
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnoteprepare}
% |\NCC@fnoteprepare|\marg{driver}\marg{prefix}\oarg{width}\\
% Prepares a footnote rule command. The \meta{driver} is a command
% that will be called for collecting rule code (it gets more arguments
% from the input). When a driver prepares the code, it calls the
% |\NCC@fnotecreate| command. If \meta{width} is omitted, the standard
% width of |0.4\columnwidth| is used.
%    \begin{macrocode}
\def\NCC@fnoteprepare#1#2{%
  \@ifnextchar[{#1{#2}}{#1{#2}[.4\columnwidth]}%
}
\@onlypreamble\NCC@fnoteprepare
%    \end{macrocode}
% \end{macro}
%
% Footnote rule creation driver has the following syntax:
% \begin{quote}
% |\|\meta{driver}\marg{prefix}\oarg{width}\meta{more arguments}
% \end{quote}
%
% \begin{macro}{\newfootnoterule}
% |\newfootnoterule|\marg{prefix}\oarg{width}\marg{rule code}
%    \begin{macrocode}
\newcommand\newfootnoterule{\NCC@fnoteprepare\NCC@fnotedriver}
\def\NCC@fnotedriver#1[#2]#3{%
  \NCC@fnotecreate{#1}{\NCC@fnoterule{#2}{#3}}%
}
\@onlypreamble\newfootnoterule
\@onlypreamble\NCC@fnotedriver
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newfootnotedashrule}
% |\newfootnotedashrule|\marg{prefix}\oarg{width}\marg{h-pattern}\marg{v-pattern}
%    \begin{macrocode}
\newcommand\newfootnotedashrule{\NCC@fnoteprepare\NCC@fnotedashdriver}
\def\NCC@fnotedashdriver#1[#2]#3#4{%
  \NCC@fnotecreate{#1}{\NCC@fnotedashrule{#2}{#3}{#4}}%
}
\@onlypreamble\newfootnotedashrule
\@onlypreamble\NCC@fnotedashdriver
%</package>
%    \end{macrocode}
% \end{macro}
\endinput