% \iffalse
%%
%% File: desclist.dtx Copyright (C) 2002--2004 by Alexander I. Rozhenko
%%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{desclist}
%<package>         [2004/11/23 v1.1 Desclist Package (NCC)]
%
% \changes{v1.0}{2002/01/09}{This version was uploaded to CTAN}
% \changes{v1.1}{2004/11/21}{Desclist suffix was enclosed in braces}
% \changes{v1.1}{2004/11/23}{Documentation was prepared}
%
%<*driver>
\let\makeindex\relax
\documentclass{ltxdoc}
\usepackage{desclist}
\GetFileInfo{desclist.sty}
\begin{document}
\title{The \textsf{desclist} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{Alexander I. Rozhenko\\rozhenko@oapmg.sscc.ru}
\date{\filedate}
\maketitle
\DocInput{desclist.dtx}
\end{document}
%</driver>
% \fi
% The package implements the |desclist| environment and redefines
% the |description| environment to provide an optional parameter
% as a prototype for calculation the hang indent of the list.
%
% \tableofcontents
%
% \section{User Interface}
%
% \DescribeMacro{desclist}
% The |desclist| environment is similar to the |description|
% environment but adds more control for typesetting list labels.
% The usage:
% \begin{quote}
% |\begin{desclist}|\marg{prefix}\marg{suffix}\oarg{prototype}\\
% |\item|\oarg{label} \meta{text}\\
% \ldots\\
% |\end{desclist}|
% \end{quote}
% The \meta{prefix} is inserted before the label and the suffix
% is inserted after the label. The optional \meta{prototype} parameter
% specifies a prototype for calculation the minimum width of a list label
% and for calculation the hang indent of a list text.
% If this parameter is omitted, the standard hang indent value is used
% and the minimum width of list labels is equal to zero.
%
% A list label is generated in the |\item|\oarg{label} command
% as follows:
% \begin{quote}
% \meta{prefix}\meta{label}\marg{suffix}|\hfil|
% \end{quote}
% Therefore, you can finish the \meta{label} with a command having a parameter
% to replace a suffix with something else. The |\hfil| command at the end of
% label adds necessary horizontal space if the label width is less than the
% minimum width of list label. Using a \meta{prototype} together with the
% |\hfill| command in \meta{prefix} and/or \meta{suffix}
% parameters, you can align left, align right, or center narrow list labels.
%
% The following example shows the benefits of the |desclist| environment:
%      \begin{desclist}{\sf}{ \rm\hfill---}[Mark]
%      \newcommand*\Skip[1]{}
%      \item[M] an item with a narrow label;
%      \item[MM] an item with a narrow label;
%      \item[Mark] an item with a normal label;
%      \item[Long mark] an item with too wide label; and
%      \item[A mark without dash.\Skip] Here we skip the desclist suffix.
%      \end{desclist}
% It was prepared as follows:
% \begin{quote}
%      |\begin{desclist}{\sf}{ \rm\hfill---}[Mark]|\\
%      |\newcommand*\Skip[1]{}|\\
%      |\item[M] an item with a narrow label;|\\
%      |\item[MM] an item with a narrow label;|\\
%      |\item[Mark] an item with a normal label;|\\
%      |\item[Long mark] an item with too wide label; and|\\
%      |\item[A mark without dash.\Skip] Here we skip|\\
%      |the desclist suffix.|\\
%      |\end{desclist}|
% \end{quote}
%
% \DescribeMacro{description}
% The package also redefines the |description| environment to allow
% an optional parameter. In fact, the new implementation of |description|
% is equivalent to
% \begin{quote}
% |\begin{desclist}{\normalfont\bfseries}{}|\oarg{prototype}\\
% \ldots\\
% |\end{desclist}|
% \end{quote}
% \StopEventually{}
%
% \section{The Implementation}
% \begin{macro}{desclist}
% The definition of the |desclist| environment is quite simple.
% If an optional parameter is omitted, pass an empty one
% to the internal command.
%    \begin{macrocode}
%<*package>
\newenvironment*{desclist}[2]{%
  \@ifnextchar[{\NCC@dlist{#1}{#2}}{\NCC@dlist{#1}{#2}[]}%
}{%
  \endlist
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@dlist}
% The internal definition of the |desclist| is based on the |\list|:
%    \begin{macrocode}
\def\NCC@dlist#1#2[#3]{%
  \list{}{%
%    \end{macrocode}
% Specify just the same list parameters as in the |description|
% if the optional parameter is empty:
%    \begin{macrocode}
    \def\@tempa{#3}\ifx\@tempa\@empty
      \labelwidth\z@ \itemindent-\leftmargin
%    \end{macrocode}
% In other case, use the prototype to calculate the label width
% and margins:
%    \begin{macrocode}
    \else
      \settowidth\leftmargin{#1#3{#2}}%
      \advance\leftmargin\labelsep
      \labelwidth=\leftmargin
      \itemindent\z@
    \fi
%    \end{macrocode}
% Finally, define the |\makelabel| command adding the desclist
% prefix and suffix and finishing it with |\hfil| to allow left
% alignment for narrow labels. The suffix is enclosed in braces,
% to allow a trick with ignoring it in the label mark if necessary
% (see the example above):
%    \begin{macrocode}
    \def\makelabel##1{\hspace\labelsep #1##1{#2}\hfil}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{description}
% Now we redefine the |description| environment. We do not test
% is it defined or not.
%    \begin{macrocode}
\def\description{\desclist{\normalfont\bfseries}{}}
\let\enddescription=\enddesclist
%</package>
%    \end{macrocode}
% \end{macro}
\endinput