make metric optional explicitly for T1font
[PyX/mjg.git] / faq / glifaq.dtx
blobeb6b2830d2be1af7cac456cfe57ca02eb5757742
1 % \iffalse
2 %<package>\NeedsTeXFormat{LaTeX2e}
3 %<*driver>
4 \def\fileversion{0.3}
5 \def\filedate{2004/12/10}
6 \ProvidesFile{glifaq.drv}
7 %</driver>
8 %<package>\ProvidesPackage{glifaq}
9            [2004/12/10 Style for PyX FAQ (gli) v0.3]
10 %<*driver>
11 \documentclass{ltxdoc}
12 \usepackage{url}
13 \EnableCrossrefs
14 \CodelineIndex
15 \RecordChanges
16 \newcommand\PyX{P\kern-.3em\lower.5ex\hbox{Y}\kern-.18em X}
17 \newcommand{\acro}[1]{\textsc{#1}}
18 \begin{document}
19    \DocInput{glifaq.dtx}
20 \end{document}
21 %</driver>
22 % \fi
24 % \CharacterTable
25 %  {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
26 %   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
27 %   Digits        \0\1\2\3\4\5\6\7\8\9
28 %   Exclamation   \!     Double quote  \"     Hash (number) \#
29 %   Dollar        \$     Percent       \%     Ampersand     \&
30 %   Acute accent  \'     Left paren    \(     Right paren   \)
31 %   Asterisk      \*     Plus          \+     Comma         \,
32 %   Minus         \-     Point         \.     Solidus       \/
33 %   Colon         \:     Semicolon     \;     Less than     \<
34 %   Equals        \=     Greater than  \>     Question mark \?
35 %   Commercial at \@     Left bracket  \[     Backslash     \\
36 %   Right bracket \]     Circumflex    \^     Underscore    \_
37 %   Grave accent  \`     Left brace    \{     Vertical bar  \|
38 %   Right brace   \}     Tilde         \~}
40 % \CheckSum{239}
43 % \title{The \texttt{glifaq} package}
45 % \author{Gert-Ludwig Ingold\\\small\url{<gert.ingold@physik.uni-augsburg.de>}}
46 % \date{(v.\fileversion\ -- \filedate)}
47 % \maketitle
49 % \section{Introduction}
50 % The \texttt{glifaq} package has been developed to typeset the \acro{faq} of 
51 % the \PyX{} graphics package for \acro{Python}. It might contain a few
52 % commands which are useful for other \acro{faq}s as well.
54 % \section{Usage}
55 % \label{sec:usage}
56 % The package \texttt{glifaq} is intended for use with the \texttt{scrartcl}
57 % class which is part of \acro{KOMA-Script}. \texttt{scrartcl} should therefore
58 % be chosen as document class. 
59 %  
60 % The options of the package \texttt{glifaq} mostly control the kind of 
61 % questions which will be typeset. There are four kinds of questions:
62 % \begin{center}
63 % \begin{tabular}{ll}
64 % |a| & answered question\\
65 % |c| & question where the answer has been checked by an expert\\
66 % |o| & outdated question\\
67 % |t| & question not fully answered yet (= to do)
68 % \end{tabular}
69 % \end{center}
70 % The following options are recognized by the package:
71 % \begin{description}
72 % \item[all] prints all questions
73 % \item[answered] prints only questions which have no ``to do'' status, i.e.
74 %            they have a satisfying answer and might even have been checked
75 % \item[checked] prints only questions where the answers have been checked
76 % \item[outdated] prints only questions and answers which are outdated
77 % \item[todo] prints all questions where no satisfying answer has been 
78 %            formulated yet
79 % \item[unchecked] prints all questions which have not been checked yet
80 % \item[comments] if comments exist, they will be printed as well and a 
81 %            special mark will be put in the margin
82 % \item[notoc] the table of contents will not be printed
83 % \end{description}
84 % By default, all questions and the table of contents but no comments will be
85 % printed. If questions with ``to do'' status are printed, a special mark will
86 % be put in the margin.
88 % \DescribeMacro\question
89 % The most important task of the package \texttt{glifaq} is to define a command
90 % \begin{quote}
91 % |\question{|\meta{status}|}{|\meta{title}|}{|\meta{comment}|}{|^^A
92 %    \meta{answer}|}|
93 % \end{quote}
94 % to handle the typesetting of questions and their answers. As indicated, this 
95 % command takes four arguments:
96 % \begin{center}
97 % \begin{tabular}{ll}
98 % 1: & class of the question according to the table given above\\
99 %    & allowed values: |a|, |c|, |o|, |t|\\
100 % 2: & title of the question\\
101 % 3: & comments related to this question\\
102 % 4: & the answer to the question
103 % \end{tabular}
104 % \end{center}
106 % \DescribeEnv{progcode}
107 % For the typesetting of code snippets, an environment |progcode| has been
108 % defined which will use a fixed space font. Unfortunately, verbatim code
109 % cannot be used in arguments as is the case here in macro |\question|.
110 % To guarantee proper spaces and in particular indenting, a tilde has to
111 % used instead of a space.
113 % In addition, there exist a few simple definitions which may be useful:
115 % \DescribeMacro\uaref
116 % The macro |\uaref| acts like the usual |\ref| command but puts an $\uparrow$
117 % (|\uparrow|) in front of the reference.
119 % \DescribeMacro\toc
120 % The macro |\toc| replaces the usual |\tableofcontents| to allow for control
121 % via the |notoc| option.
123 % \DescribeMacro\PyX
124 % The macro |\PyX| defines the \PyX{} logo as employed by the developers of 
125 % \PyX{} in their manual.
127 % \DescribeMacro\tipagraph
128 % In order to explain the pronunciation of \PyX, the |tipa| package is
129 % needed which cannot be expected to be present in every installation. 
130 % Therefore, we provide via the |\tipagraph| command a way to alternatively
131 % include a graphics file. The command is used as follows
132 % \begin{quote}
133 % |\tipagraph{|\meta{tipa code}|}{|\meta{graphics filename}|}|
134 % \end{quote}
136 % \DescribeMacro\cs
137 % In some places, a backslash cannot be used verbatim, in particular in an
138 % argument of the |\question| macro. Using
139 % \begin{quote}
140 % \verb*+\cs +\meta{command name}
141 % \end{quote}
142 % will result in a backslash followed directly by the command name.
144 % \DescribeMacro\us
145 % The macro |\us| can be used to produce an underscore if there is no more
146 % direct way to do so.
148 % \DescribeMacro\hat
149 % Sometimes it may also be difficult to produce a hat character. In such cases, 
150 % |\hat| can be useful.
152 % \DescribeMacro\cb
153 % The last macro of this type is |\cb| which allows to enclose an argument in
154 % curly braces.
156 % \DescribeMacro\ctan
157 % For references to files on \acro{ctan}, the macro |\ctan| can be used where 
158 % the single argument should be the location of the file relative to the 
159 % \acro{ctan} root.
160 % \DescribeMacro\ftpCTAN
161 % One of the \acro{ctan} ftp servers is coded into the package via the 
162 % |\ftpCTAN| macro for direct reference from the \acro{pdf} version of the 
163 % \acro{faq}.
165 % \DescribeMacro\new\DescribeMacro\changed
166 % Finally, the two macros |\new| and |\changed| allow to mark questions as
167 % new or changed with respect to an earlier version of the \acro{faq}. These 
168 % macros should be used in the second argument of |\question| just behind the 
169 % text defining the title of a question.
171 % \section{The Description of the Package Code}
172 % \StopEventually
174 % We first define a few new switches:
175 % \begin{center} 
176 % \begin{tabular}{ll}
177 % |\if@a|& print answered questions if true\\
178 % |\if@c|& print corrected questions if true\\
179 % |\if@o|& print outdated questions if true\\
180 % |\if@t|& print unanswered or not fully answered questions if true\\
181 % |\ifc@mments|& print comments if true\\
182 % |\ift@c|& insert table of contents if true
183 % \end{tabular}
184 % \end{center}
185 % By default, we print all questions and the table of contents but no comments.
186 %    \begin{macrocode}
187 \newif\if@a \@atrue
188 \newif\if@c \@ctrue
189 \newif\if@o \@otrue
190 \newif\if@t \@ttrue
191 \newif\ifc@mments \c@mmentsfalse
192 \newif\ift@c \t@ctrue
193 %    \end{macrocode}
194 % Now we define the various options and set the switches according to the
195 % options' definition given in section~\ref{sec:usage}.
196 %    \begin{macrocode}
197 \DeclareOption{all}{\@atrue \@ctrue \@otrue \@ttrue}
198 \DeclareOption{answered}{\@atrue \@ctrue \@ofalse \@tfalse}
199 \DeclareOption{checked}{\@afalse \@ctrue \@ofalse \@tfalse}
200 \DeclareOption{outdated}{\@afalse \@cfalse \@otrue \@tfalse}
201 \DeclareOption{todo}{\@afalse \@cfalse \@ofalse \@ttrue}
202 \DeclareOption{unchecked}{\@atrue \@cfalse \@ofalse \@ttrue}
203 \DeclareOption{comments}{\c@mmentstrue}
204 \DeclareOption{notoc}{\t@cfalse}
205 \ProcessOptions\relax
206 %    \end{macrocode}
207 % Next, we load some needed packages if they have not been loaded before. 
208 %    \begin{macrocode}
209 \RequirePackage{ifthen}
210 \RequirePackage{remreset}
211 \RequirePackage{pifont}
212 %    \end{macrocode}
213 % The following macro will put a large cross in the margin to mark comments or
214 % questions with ``to do'' status.
215 %    \begin{macrocode}
216 \newcommand{\put@ding}{\mbox{}\marginpar{\Huge\ding{56}}}
217 %    \end{macrocode}
219 % Now comes the most important part of this package, the macro |\question|.
220 % This macro has to decide on the basis of the first argument and the
221 % options used with the package whether the current question is to be printed
222 % or not.
224 % It is assumed that in the section hierarchy, the question can take the role
225 % of a subsection or a subsubsection. Therefore, a mechanism has to be 
226 % provided which tells the question its place in the hierarchy. Independent
227 % of whether the question acts like a subsection or subsubsection, the layout
228 % of the question title should be the one of a subsubsection.
230 % We introduce three switches: |\@printtrue| indicates that the question has
231 % to be printed while |\@margtrue| requests a mark to be put into the margin
232 % to indicate a question with ``to do'' status and |\@outdatedtrue| will mark a
233 % question as outdated. 
234 %    \begin{macrocode}
235 \newif\if@print
236 \newif\if@marg 
237 \newif\if@outdated
238 %    \end{macrocode}
239 % Below we will need to find out which level a question corresponds to. If the
240 % value of the counter \texttt{question} is not equal to 0, the level is
241 % already known. A value of 1 indicates that the questions are on the level
242 % of a \texttt{subsection} while a value of 2 implies that the questions are
243 % on the \texttt{subsubsection} level. Whenever a new section is started, we
244 % will need to find out the level of the questions in this section. Therefore,
245 % we reset the counter \texttt{question} whenever a new section is started.
246 %    \begin{macrocode}
247 \newcounter{question}[section]
248 \setcounter{question}{0}
249 %    \end{macrocode}
250 % Since we want to set the title of a question always in the fontsize of a 
251 % \texttt{subsubsection}, we might need to temporarily change the fontsize 
252 % of the \texttt{subsection} title. In order to be able to restore the original
253 % value, we save the value of |\size@subsection| which is used in the 
254 % \acro{KOMA-Script} classes to define the fontsize of the \texttt{subsection} 
255 % title.
256 %    \begin{macrocode}
257 \let\save@sizesubsection\size@subsection
258 %    \end{macrocode}
260 % Now we are ready to define the |\question| macro. First, defaults are set
261 % not to print the question and not to print a mark in the margin. If the status
262 % of the question corresponds to one asked for by the option passed to the
263 % package, we change the print switch to |\@printtrue|. A ``to do'' question
264 % will in addition ask to print a mark in the margin by setting |\@margtrue|.
265 %    \begin{macrocode}
266 \newcommand{\question}[4]%
267 {\@printfalse\@margfalse\@outdatedfalse%
268  \ifthenelse{\equal{a}{#1}\and\boolean{@a}}{\@printtrue}{}%
269  \ifthenelse{\equal{c}{#1}\and\boolean{@c}}{\@printtrue}{}%
270  \ifthenelse{\equal{o}{#1}\and\boolean{@o}}{\@printtrue\@outdatedtrue}{}%
271  \ifthenelse{\equal{t}{#1}\and\boolean{@t}}{\@printtrue\@margtrue}{}%
272 %    \end{macrocode}
273 % If the \texttt{question} counter has the value 0, we need to determine the
274 % level of the question. The question should at least be on 
275 % \texttt{subsubsection} level if not higher. So we first assume it to be
276 % of this level and make corrections later on if necessary. The counter
277 % \texttt{question} is set to a level different from 0 (in this case to a
278 % value of 2 although this is nowhere exploited in the code). This counter
279 % will now be reset not only by a |\section| but also by a |\subsection|.
280 % Finally, we set the command |\questi@n| which will typeset the question title
281 % as \texttt{subsubsection}.
283 % In a second step, we check whether the question is on |\subsection| level
284 % instead of |\subsubsection| level as was assumed before. In this case,
285 % the counter \texttt{question} is set to 1 (again it is only important that
286 % the value is different from 0). This counter should no longer be reset
287 % by a |\subsection| so we remove the corresponding entry from the reset list.
288 % Finally, the command |\questi@n| typesetting the title of the question is
289 % set to |\subsection|.
290 %    \begin{macrocode}
291  \ifthenelse{\value{question} = 0}{%
292    \setcounter{question}{2}%
293    \@addtoreset{question}{subsection}%
294    \let\questi@n\subsubsection%
295    \ifthenelse{\value{subsection} = 0}%
296       {\setcounter{question}{1}%
297        \@removefromreset{question}{subsection}%
298        \let\questi@n\subsection}%
299       {}%
300   }{}
301 %    \end{macrocode}
302 % Now we are ready to typeset the question if this is what the options passed
303 % to the package ask for. Before typesetting the question title, we temporarily
304 % set the fontsize of the |\subsection| title to the fontsize of the 
305 % |\subsubsection| just in case we are on the |\subsection| level. |\questi@n|
306 % does the typesetting of the title and a mark is put into the margin if
307 % requested by |\@margtrue|. 
309 % After the title, a comment, if present and asked for, is typeset in sans 
310 % serif and small fontsize. Finally, the answer, i.e. the contents of argument 
311 % 4, is typeset.
312 %    \begin{macrocode}
313   \if@print%
314     \let\size@subsection\size@subsubsection
315      \questi@n{#2 \if@outdated\outd@ted\fi}\if@marg\put@ding\else\fi%
316     \let\size@subsection\save@sizesubsection
317    \ifc@mments
318     \ifthenelse{\equal{}{#3}}{}
319     {\put@ding{\sffamily\small#3}\par}%
320    \else\fi
321     #4
322   \else\fi}
323 %    \end{macrocode}  
325 % Since it is not possible to use verbatim code in macro arguments, we cannot
326 % typeset code snippets in an answer by using a \texttt{verbatim} environment.
327 % We therefore define the environment \texttt{progcode}. In order to ensure
328 % proper indentation, we make the tilde an active character and define
329 % it as space preceded by a |\strut| so that the space is not ignored.
330 % In addition, several layout parameters are set like a global indentation
331 % of the code and the use of a small fixed space font.
332 %    \begin{macrocode}
333 \newenvironment{progcode}
334   {\list{}{\leftmargin\parindent\rightmargin\z@}%
335          \ttfamily\small%
336          \catcode`\~=13%
337          \def~{\strut\ }%
338          \item\relax}
339         {\endlist}
340 %    \end{macrocode}
341 % To facilitate references preceded by a $\uparrow$ we define |\uaref| which
342 % works like the standard |\ref|.
343 %    \begin{macrocode}
344 \DeclareRobustCommand\uaref[1]{$\uparrow$\ref{#1}}
345 %    \end{macrocode}
346 % The option \texttt{notoc} only works if instead of |\tableofcontents| the
347 % command |\toc| defined here is used.
348 %    \begin{macrocode}
349 \DeclareRobustCommand\toc[0]{\ift@c\tableofcontents\else\fi}
350 %    \end{macrocode}
351 % The definition of the \PyX{} logo is copied from the code used by the \PyX{}
352 % developers in their manual. Here, we also provide the simple string ``PyX''
353 % for use in the \acro{pdf} bookmarks.
354 %    \begin{macrocode}
355 \DeclareRobustCommand\PyX[0]{\texorpdfstring%
356            {P\kern-.3em\lower.5ex\hbox{Y}\kern-.18em X}{PyX}%
357           }
358 %    \end{macrocode}  
359 % We now check for the presence of the |tipa| package. If present, it
360 % will be loaded and the command |\tipagraph| will hand over its first
361 % argument to the command |\textipa|. Otherwise, the |graphicx| package
362 % is loaded and |\tipagraph| will lead to the inclusion of the graphics file
363 % given in the second argument. The vertical shift of the box has been chosen 
364 % by trial and error. The horizontal spacing is slightly different in the two 
365 % alternatives but this should not give to rise to major problems. 
366 %    \begin{macrocode}
367 \IfFileExists{tipa.sty}%
368   {\usepackage{tipa}%
369    \newcommand{\tipagraph}[2]{\textipa{##1}}}%
370   {\usepackage{graphicx}%
371    \newcommand{\tipagraph}[2]{\raisebox{-2.727263bp}{\includegraphics{##2}}}}
372 %    \end{macrocode}
373 % When a backslash character is needed as part of a verbatim command name,
374 % but verbatim code cannot be used, the macro |\cs| can be employed.
375 % Again, we take care of the requirements of the \acro{pdf} bookmarks.
376 %    \begin{macrocode}
377 \DeclareRobustCommand\cs[1]{%
378     \texorpdfstring{\texttt{\char`\\}}{\textbackslash}#1%
379     }
380 %    \end{macrocode}
381 % In order to avoid problems with verbatim code, we define |\us| and |\hat|
382 % to produce an underscore and a hat, respectively.
383 %    \begin{macrocode}
384 \DeclareRobustCommand\us[0]{\texttt{\char`\_}}
385 \DeclareRobustCommand\hat[0]{\texttt{\char`\^}}
386 %    \end{macrocode}
387 % The macro |\cb| encloses its argument in curly braces and should be used
388 % when verbatim code does not work.
389 %    \begin{macrocode}
390 \DeclareRobustCommand\cb[1]{\texttt{\char`\{#1\char`\}}}
391 %    \end{macrocode}
392 % For files on \acro{ctan}, we define the macro |\ctan| which is used as follows
393 % \begin{quote}
394 % |\ctan{|\meta{file location relative to CTAN root}|}|
395 % \end{quote}
396 % In order for the link to connect to a \acro{ctan} server, |\ftpCTAN| contains
397 % the URL of one of the \acro{ctan} servers which is chosen quite arbitrarily 
398 % and could be replaced by another \acro{ctan} server. Note that we use
399 % |\path| instead of |\url| to avoid that a link is created to the second
400 % argument instead of the first one.
401 %    \begin{macrocode}
402 \def\ftpCTAN{ftp://ctan.tug.org/tex-archive/}
403 \DeclareRobustCommand\ctan[1]{%
404     \href{\ftpCTAN#1}{\path{CTAN:#1}}%
406 %    \end{macrocode}
407 % In order to mark questions as new or changed with respect to a previous
408 % release of the \acro{faq}, we define the macros |\new| and |\changed| which 
409 % are intended to be used at the end of the second argument of |\question|.
410 % No output is generated for \acro{pdf} bookmarks.
411 %    \begin{macrocode}
412 \DeclareRobustCommand\new[0]{\texorpdfstring%
413            {\quad\raisebox{0.3ex}{\fbox{\tiny\normalfont NEW}}}{}
414           }
415 \DeclareRobustCommand\changed[0]{\texorpdfstring%
416            {\quad\raisebox{0.3ex}{\fbox{\tiny\normalfont CHANGED}}}{}
417           }
418 %    \end{macrocode}
419 % Outdated questions should be marked also in the \acro{pdf} bookmarks. 
420 %    \begin{macrocode}
421 \DeclareRobustCommand\outd@ted[0]{\texorpdfstring%
422            {\quad\colorbox{black}{\color{white}\small OUTDATED}}
423                       {~(outdated)}
424           }
425 %    \end{macrocode}
426 % \Finale
427 \endinput