summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ncctools/source/desclist.dtx
blob: de6a911f2d92f4415b91d2f6ecd570594ef20991 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
% \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