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

% \iffalse
%%
%% File: nccboxes.dtx Copyright (C) 2002--2005 by Alexander I. Rozhenko
%%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{nccboxes}
%<package>         [2005/02/07 v1.2 Additional Boxes (NCC)]
%
% \changes{v1.03}{2002/01/29}{This version is uploaded to CTAN}
% \changes{v1.04}{2002/03/20}{Internal changes in |\jvbox|}
% \changes{v1.04}{2002/03/20}{The |\jparbox| command introduced}
% \changes{v1.05}{2002/05/24}{Bug in |\jparbox| (incorrect width) fixed}
% \changes{v1.1}{2004/11/28}{Documentation was prepared}
% \changes{v1.2}{2005/02/07}{Add |\tc| command}
% \changes{v1.2}{2005/02/07}{Allow lengthes in the Strut parameter}
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{nccboxes}
\GetFileInfo{nccboxes.sty}
\begin{document}
\title{The \textsf{nccboxes} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{Alexander I. Rozhenko\\rozhenko@oapmg.sscc.ru}
\date{\filedate}
\maketitle
\DocInput{nccboxes.dtx}
\end{document}
%</driver>
% \fi
%
% The package implement special boxes and struts from NCC-\LaTeX.
%
% \section{User Interface}
%
% \DescribeMacro{\jhbox}
% This macro specifies a horizontal box whose width is calculate
% using a prototype and alignment position is specified in the same manner
% as in the |\makebox| command. The syntax:
% \begin{quote}
% |\jhbox|\marg{prototype}\oarg{pos}\marg{text}
% \end{quote}
% Here \meta{prototype} is a text whose width will be the width of generated
% box, \meta{pos} is an alignment parameter (|l|, |c|, |r|, or |s|;
% default is |c|).
%
% \DescribeMacro{\jvbox}
% This macro specifies a horizontal box whose height, depth, and vertical
% alignment is calculated using a prototype. The syntax:
% \begin{quote}
% |\jvbox|\marg{prototype}\oarg{pos}\marg{text}
% \end{quote}
% The \meta{text} argument is vertically aligned with respect to the
% strut defined by the \meta{prototype} parameter. The optional
% \meta{pos} parameter defines an alignment position
% (|t|, |c|, or |b|; default is |c|). If |t| is used, the \meta{text} is
% raised in such a way that its height will be equal to the height of
% the prototype's strut. For the |b| case, the depths will be equal, and,
% for the |c| case, the \meta{text} is vertically centered with respect to
% the prototype's strut. The height and depth of the prepared box are
% calculated as a maximum between the corresponding parameters of the
% \meta{prototype} and the vertically adjusted \meta{text}.
%
% \DescribeMacro{\jparbox}
% This macro prepares a paragraph box of the required width and
% vertically aligns it with respect to the prototype just in the same manner
% as the |\jvbox|. The syntax:
% \begin{quote}
% |\jparbox|\marg{prototype}\oarg{pos}\marg{width}\marg{text}
% \end{quote}
% The \meta{prototype} and \meta{pos} parameters have the same meaning
% as described for |\jvbox|. The \meta{width} is the width
% of the paragraph box and the \meta{text} is the box content.\pagebreak
%
% \DescribeMacro{\addbox}
% This macro specifies a horizontal box whose height and depth are
% adjusted using the given values. The syntax:
% \begin{quote}
% |\addbox|\marg{height-adjust}\marg{depth-adjust}\marg{text}
% \end{quote}
% For example, |\addbox{.5ex}{.5ex}{text}| increases the height
% and depth of produced box on |0.5ex|.
%
% \DescribeMacro{\pbox}
% This macro implements a simple one-column table. The syntax:
% \begin{quote}
% |\pbox|\oarg{pos}\marg{body}
% \end{quote}
% The \meta{pos} parameter may consist of two letters defining
% a relative alignment of the table rows in the column
% (|l|, |c|, or |r|) and the vertical alignment of the whole table
% with respect to surrounding text (|t|, |c|, or |b|).
% Centering is the default alignment. The distance between
% table rows does not depend on the |\arraystretch| value.
%
% \DescribeMacro{\picbox}
% The |\picbox|\marg{body} macro is equivalent to
% \begin{quote}
% |\begin{picture}(0,0)(0,0)|\meta{body}|\end{picture}|.
% \end{quote}
%
% To prepare fancy tables, the following commands can be used:
%
% \DescribeMacro{\Strut}
% \DescribeMacro{\Strutletter}
% The |\Strut/|\meta{value}|/| command is a special strut whose
% height and depth are calculated from the strut prototype
% command |\Strutletter| (letter |A| by default) as follows:
% if \meta{value} is positive, the full height of the current
% |\strutbox| multiplied by the \meta{value} is added to the
% height of strut prototype, otherwise the depth of strut prototype
% increases with the modulus of \meta{value} multiplied
% by the full height of |\strutbox|. For example,
% |\Strut/1/| inserts a strut which height exceeds the height
% of the letter |A| from the current font on the interline distance.
% A natural length is also possible as a value of |\Strut|'s
% parameter. So, the |\Strut/2mm/| means a strut with the height
% exceeding the height of strut letter over 2~mm.
% The |\Strut| without parameter is equal to |\Strut/0/|.
% Spaces after the |\Strut| are ignored.
%
% \DescribeMacro{\tstrut}
% \DescribeMacro{\bstrut}
% \DescribeMacro{\tbstrut}
% \DescribeMacro{\Strutstretch}
% The |\tstrut|, |\bstrut|, and |\tbstrut| commands insert
% struts exceeding the height, depth, and both height and depth
% of the strut prototype |\Strutletter| by a special small amount.
% This amount is calculated in such a way that the full height
% of |\tbstrut| will be equal to 1.5 of full height of the
% current |\strutbox|. The stretch factor 1.5 is specified in
% the |\Strutstretch| command. These commands are used in tables
% to insert a space between a horizontal line and a table row.
% But if the height and depth of row contents exceeds the
% height and depth of inserted strut, the inserted strut will
% take no effect.
%
% \DescribeMacro{\cbox}
% The |\cbox/|\meta{value}|/|\oarg{pos}\marg{body} command
% prepares a box whose body is a one-column table. Its height and
% depth are enlarged using |\tstrut| at the beginning and
% |\bstrut| at the end of body. The horizontal alignment
% (|l|, |c|, or |r|) in the column and the vertical
% alignment (|t|, |c|, or |b|) are defined in the
% \meta{pos} parameter. Centered alignment is used by
% default. The resulting box is vertically aligned with
% respect to the |\Strut/|\meta{value}|/| using the
% |\jvbox| command. The |\cbox*| command does the same
% but vanishes the height and depth of the resulting box.
% The |\cbox| command is used in the headers of tables.
% Its star form is useful in cells having vertical spans.
%
% \DescribeMacro{\cboxstyle}
% The |\cboxstyle| specifies a style applied to all
% |\cbox| commands. It can set a font size, shape, color,
% etc. The default value of |\cboxstyle| is empty.
%
% We demonstrate the usage of struts and |\cbox| on the
% following example:
% \begin{center}\catcode`|=12
% \renewcommand\cboxstyle{\small\bf}
% \setlength{\tabcolsep}{10pt}
% \begin{tabular}{|l|c|c|c|}\hline
%  \cbox*/-1.5/{Vertically\\spanned head} & \cbox{Simple head}
%  &\multicolumn2{c|}{\cbox{Very long head\\of two lines}}\\\cline{2-4}
%  &\cbox{subhead} &\cbox{subhead} &\cbox{subhead}\\\hline
%  \Strut/1/ Text & field & field & field \\
%            Text & field & field & field \\
%  \bstrut   Text & field & field & field \\\hline
% \end{tabular}
% \end{center}
% It was produced as follows:
% \begin{quote}
% |\begin{center}|\\
% |  \renewcommand\cboxstyle{\small\bf}|\\
% |  \setlength{\tabcolsep}{10pt}|\\
% \verb+  \begin{tabular}{|l|c|c|c|}\hline+\\
% |    \cbox*/-1.5/{Vertically\\spanned head} & \cbox{Simple head}|\\
% \verb+    &\multicolumn2{c|}{\cbox{Very long head\\of two lines}}\\+\\
% |    \cline{2-4}|\\
% |    &\cbox{subhead} &\cbox{subhead} &\cbox{subhead}\\\hline|\\
% |    \Strut/1/ Text & field & field & field \\|\\
% |              Text & field & field & field \\|\\
% |    \bstrut   Text & field & field & field \\\hline|\\
% |  \end{tabular}|\\
% |\end{center}|
% \end{quote}
%
% \DescribeMacro{\tc}
% To center a table field, the |\tc|\marg{field} command is introduced
% since version 1.2 of the package. It inserts |\hspace*{\fill}|
% before and after the \meta{field}.
%
% \StopEventually{}
%
% \section{The Implementation}
%
% \begin{macro}{\addbox}
% The implementation of
% |\addbox|\marg{height-adjust}\marg{depth-adjust}\marg{text}.
% We use the |\setlength| in calculations
% of box's height and depth for compatibility with the |calc|
% package.
%    \begin{macrocode}
%<*package>
\newcommand*{\addbox}[3]{%
  \@begin@tempboxa\hbox{#3}%
    \setlength\@tempdima{#1}%
    \advance\@tempdima \ht\@tempboxa
    \ht\@tempboxa \@tempdima
    \setlength\@tempdima{#2}%
    \advance\@tempdima \dp\@tempboxa
    \dp\@tempboxa \@tempdima
    \leavevmode\box\@tempboxa
  \@end@tempboxa
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\jhbox}
% The implementation of |\jhbox|\marg{prototype}\oarg{pos}\marg{text}
% is very simple:
%    \begin{macrocode}
\newcommand*{\jhbox}[1]{\settowidth\@tempdima{#1}\makebox[\@tempdima]}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\jvbox}
% The |\jvbox|\marg{prototype}\oarg{pos}\marg{text} is implemented
% as follows. We prepare a vertical strut
% in zero box using the \meta{prototype}. Then we vertically adjust the
% content of the |\jvbox| and put the strut and the adjusted box.
%    \begin{macrocode}
\newcommand*{\jvbox}[1]{%
  \setbox\z@\hbox{\color@begingroup#1\color@endgroup}%
  \setbox\z@\hbox{\vrule \@width\z@ \@height\ht\z@ \@depth\dp\z@}%
  \NCC@jvbox
}
\newcommand*{\NCC@jvbox}[2][]{%
  \setbox\@tempboxa\hbox{\color@begingroup#2\color@endgroup}%
  \let\m@t\vss \let\m@b\vss
  \@tfor\@tempa :=#1\do {%
    \expandafter\let\csname m@\@tempa\endcsname\relax}%
  \@tempdima\ht\z@ \advance\@tempdima -\ht\@tempboxa
  \ifx\m@t\relax \else
    \@tempdimb\dp\@tempboxa \advance\@tempdimb -\dp\z@
    \ifx\m@b\relax \@tempdima \@tempdimb \else
      \advance\@tempdimb \@tempdima \@tempdima .5\@tempdimb
    \fi
  \fi
  \leavevmode \box\z@ \raise\@tempdima\box\@tempboxa
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\jparbox}
% The implementation of
% |\jparbox|\marg{prototype}\oarg{pos}\marg{width}\marg{body}
% is based on |\jvbox|, but we prepare the
% \meta{body} in the vertical box.
%    \begin{macrocode}
\newcommand*{\jparbox}[1]{%
  \@ifnextchar[{\NCC@jparbox{#1}}{\NCC@jparbox{#1}[]}%
}
\long\def\NCC@jparbox#1[#2]#3#4{%
  \@begin@tempboxa\vtop{\setlength\@tempdima{#3}%
    \hsize\@tempdima\@parboxrestore#4\@@par}%
    \setlength\@tempdima{#3}% vbox containing only display equations can
    \wd\@tempboxa\@tempdima % have lesser width. We correct it here
    \jvbox{#1}[#2]{\box\@tempboxa}%
  \@end@tempboxa
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pbox}
% Now we implement the |\pbox|\oarg{pos}\marg{body} command.
% It is a simple one-column table. The |\arraystretch|
% has no effect on it. The \meta{pos} is a combination of
% vertical (tbc) and horizontal (lcr) positions. For example,
% |lt| means left adjusted table with first line on the base line.
%    \begin{macrocode}
\newcommand*{\pbox}[2][]{%
  \let\m@l\hss \let\m@r\hss \let\m@t\vss \let\m@b\vss
  \@tfor\@tempa:=#1\do{%
    \expandafter\let\csname m@\@tempa\endcsname\relax%
  }%
  \leavevmode\hbox{\color@begingroup
    $\ifx\m@t\relax \vtop  \else\ifx\m@b\relax \vbox\else \vcenter\fi\fi
    \bgroup \baselineskip\z@\lineskip\z@
      \def\\{\strut\@stackcr}%
      \halign{\m@l\ignorespaces ##\unskip\m@r\cr #2\strut\crcr}%
    \egroup$\color@endgroup
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\picbox}
% The |\picbox|\marg{body} command:
%    \begin{macrocode}
\newcommand*{\picbox}[1]{%
  \setbox\@tempboxa\hb@xt@\z@{\ignorespaces#1\hss}%
  \ht\@tempboxa\z@\dp\@tempboxa\z@
  \leavevmode\box\@tempboxa
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Strutletter}
% \begin{macro}{\Strutstretch}
% Here we specify macros for preparing special struts.
% The |\Strutletter| is the prototype for special struts.
% The |\Strutstretch| is a stretch of line height in |\cbox|
% with respect to |\strut|. We prepare special struts in
% the |\NCC@strutbox|. The |\NCC@strutsep| is a half
% of difference between stretched |\strut| and the full height
% of the |\Strutletter|.
%    \begin{macrocode}
\newcommand{\Strutletter}{A}
\newcommand{\Strutstretch}{1.5}
\newsavebox\NCC@strutbox
\newdimen\NCC@strutsep
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\NCC@setstrut}
% The |\NCC@setstrut|\marg{command}|/|\meta{value}|/|
% tests the sequence |/|\meta{value}|/|, prepares the specified
% strut in the |\NCC@strutbox|, calculates the |\NCC@strutsep|,
% and then calls the \meta{command}.
% The |/|\meta{value}|/| sequence is optional. If it is omitted,
% |/0/| is supposed.
%    \begin{macrocode}
\def\NCC@setstrut#1{%
  \setbox\NCC@strutbox\hbox{\vphantom{\Strutletter}}%
  \@tempdima\ht\strutbox \advance\@tempdima\dp\strutbox
  \NCC@strutsep \Strutstretch\@tempdima
  \advance\NCC@strutsep -\ht\NCC@strutbox
  \advance\NCC@strutsep -\dp\NCC@strutbox
  \NCC@strutsep .5\NCC@strutsep
  \@ifnextchar/{\NCC@setstrutn{#1}}{\NCC@setstrutl{#1}\z@}%
}
\def\NCC@setstrutn#1/#2/{\NCC@setstrutl{#1}{#2\@tempdima}}
\def\NCC@setstrutl#1#2{%
  \@defaultunits\@tempdima#2\relax\@nnil
  \ifdim\@tempdima>\z@
    \advance\@tempdima \ht\NCC@strutbox
    \ht\NCC@strutbox \@tempdima
  \else
    \@tempdima -\@tempdima
    \advance\@tempdima \dp\NCC@strutbox
    \dp\NCC@strutbox \@tempdima
  \fi
  #1%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Strut}
% Now we define the |\Strut/|\meta{value}|/|.
% It is quite simple:
%    \begin{macrocode}
\newcommand{\Strut}{%
  \NCC@setstrut{\leavevmode\copy\NCC@strutbox\ignorespaces}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tstrut}
% \begin{macro}{\bstrut}
% \begin{macro}{\tbstrut}
% Next we define |\tstrut|, |\bstrut|, and |\tbstrut| via the |\addbox|
% command. All these struts use the |\NCC@setstrut| to calculate
% special strut parameters.
%    \begin{macrocode}
\newcommand{\tstrut}{%
  \NCC@setstrut{}\addbox\NCC@strutsep\z@{\copy\NCC@strutbox}%
}
\newcommand{\bstrut}{%
  \NCC@setstrut{}\addbox\z@\NCC@strutsep{\copy\NCC@strutbox}%
}
\newcommand{\tbstrut}{%
  \NCC@setstrut{}\addbox\NCC@strutsep\NCC@strutsep{\copy\NCC@strutbox}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\cbox}
% \begin{macro}{\cboxstyle}
% Now, we define the
% |\cbox/|\meta{value}|/|\oarg{pos}\marg{body} command and its
% star-form. It is useful in headers of tables. The |\cboxstyle| is
% a styling command applied to every |\cbox|.
%    \begin{macrocode}
\newcommand{\cboxstyle}{}
\newcommand{\cbox}{%
  \@ifstar{\def\@tempa{\ht\@tempboxa\z@ \dp\@tempboxa\z@}\NCC@xcbox}%
          {\let\@tempa\relax\NCC@xcbox}%
}
\def\NCC@xcbox{%
  \leavevmode \hbox\bgroup\color@begingroup
  \cboxstyle\NCC@setstrut{\NCC@ycbox}%
}
\newcommand*{\NCC@ycbox}[2][]{%
  \setbox\@tempboxa\hbox{%
    \jvbox{\addbox\NCC@strutsep\NCC@strutsep{\copy\NCC@strutbox}}[#1]%
      {\pbox[#1t]{\tstrut\ignorespaces #2\unskip\bstrut}}}%
  \@tempa \box\@tempboxa
  \color@endgroup\egroup
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\tc}
% And finally, we define the |\tc|\marg{field} command.
%    \begin{macrocode}
\newcommand{\tc}[1]{\hspace*{\fill}#1\hspace*{\fill}}
%</package>
%    \end{macrocode}
% \end{macro}
\endinput