2
%<package>\NeedsTeXFormat{LaTeX2e}
5
\def\filedate{2004/12/10}
6
\ProvidesFile{glifaq.drv}
8
%<package>\ProvidesPackage{glifaq}
9
[2004/12/10 Style for PyX FAQ (gli) v0.3]
11
\documentclass{ltxdoc}
16
\newcommand\PyX{P\kern-.3em\lower.5ex\hbox{Y}\kern-.18em X}
17
\newcommand{\acro}[1]{\textsc{#1}}
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 \~}
43
% \title{The \texttt{glifaq} package}
45
% \author{Gert-Ludwig Ingold\\\small\url{<gert.ingold@physik.uni-augsburg.de>}}
46
% \date{(v.\fileversion\ -- \filedate)}
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.
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.
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:
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)
70
% The following options are recognized by the package:
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
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
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
91
% |\question{|\meta{status}|}{|\meta{title}|}{|\meta{comment}|}{|^^A
94
% to handle the typesetting of questions and their answers. As indicated, this
95
% command takes four arguments:
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
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.
120
% The macro |\toc| replaces the usual |\tableofcontents| to allow for control
121
% via the |notoc| option.
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
133
% |\tipagraph{|\meta{tipa code}|}{|\meta{graphics filename}|}|
137
% In some places, a backslash cannot be used verbatim, in particular in an
138
% argument of the |\question| macro. Using
140
% \verb*+\cs +\meta{command name}
142
% will result in a backslash followed directly by the command name.
145
% The macro |\us| can be used to produce an underscore if there is no more
146
% direct way to do so.
149
% Sometimes it may also be difficult to produce a hat character. In such cases,
150
% |\hat| can be useful.
153
% The last macro of this type is |\cb| which allows to enclose an argument in
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
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
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}
174
% We first define a few new switches:
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
185
% By default, we print all questions and the table of contents but no comments.
191
\newif\ifc@mments \c@mmentsfalse
192
\newif\ift@c \t@ctrue
194
% Now we define the various options and set the switches according to the
195
% options' definition given in section~\ref{sec:usage}.
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
207
% Next, we load some needed packages if they have not been loaded before.
209
\RequirePackage{ifthen}
210
\RequirePackage{remreset}
211
\RequirePackage{pifont}
213
% The following macro will put a large cross in the margin to mark comments or
214
% questions with ``to do'' status.
216
\newcommand{\put@ding}{\mbox{}\marginpar{\Huge\ding{56}}}
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
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.
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.
247
\newcounter{question}[section]
248
\setcounter{question}{0}
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}
257
\let\save@sizesubsection\size@subsection
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|.
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}{}%
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|.
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}%
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
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
318
\ifthenelse{\equal{}{#3}}{}
319
{\put@ding{\sffamily\small#3}\par}%
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.
333
\newenvironment{progcode}
334
{\list{}{\leftmargin\parindent\rightmargin\z@}%
341
% To facilitate references preceded by a $\uparrow$ we define |\uaref| which
342
% works like the standard |\ref|.
344
\DeclareRobustCommand\uaref[1]{$\uparrow$\ref{#1}}
346
% The option \texttt{notoc} only works if instead of |\tableofcontents| the
347
% command |\toc| defined here is used.
349
\DeclareRobustCommand\toc[0]{\ift@c\tableofcontents\else\fi}
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.
355
\DeclareRobustCommand\PyX[0]{\texorpdfstring%
356
{P\kern-.3em\lower.5ex\hbox{Y}\kern-.18em X}{PyX}%
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.
367
\IfFileExists{tipa.sty}%
369
\newcommand{\tipagraph}[2]{\textipa{##1}}}%
370
{\usepackage{graphicx}%
371
\newcommand{\tipagraph}[2]{\raisebox{-0.8ex}{\includegraphics{##2}}}}
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.
377
\DeclareRobustCommand\cs[1]{%
378
\texorpdfstring{\texttt{\char`\\}}{\textbackslash}#1%
381
% In order to avoid problems with verbatim code, we define |\us| and |\hat|
382
% to produce an underscore and a hat, respectively.
384
\DeclareRobustCommand\us[0]{\texttt{\char`\_}}
385
\DeclareRobustCommand\hat[0]{\texttt{\char`\^}}
387
% The macro |\cb| encloses its argument in curly braces and should be used
388
% when verbatim code does not work.
390
\DeclareRobustCommand\cb[1]{\texttt{\char`\{#1\char`\}}}
392
% For files on \acro{ctan}, we define the macro |\ctan| which is used as follows
394
% |\ctan{|\meta{file location relative to CTAN root}|}|
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.
402
\def\ftpCTAN{ftp://ctan.tug.org/tex-archive/}
403
\DeclareRobustCommand\ctan[1]{%
404
\href{\ftpCTAN#1}{\path{CTAN:#1}}%
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.
412
\DeclareRobustCommand\new[0]{\texorpdfstring%
413
{\quad\raisebox{0.3ex}{\fbox{\tiny\normalfont NEW}}}{}
415
\DeclareRobustCommand\changed[0]{\texorpdfstring%
416
{\quad\raisebox{0.3ex}{\fbox{\tiny\normalfont CHANGED}}}{}
419
% Outdated questions should be marked also in the \acro{pdf} bookmarks.
421
\DeclareRobustCommand\outd@ted[0]{\texorpdfstring%
422
{\quad\colorbox{black}{\color{white}\small OUTDATED}}
added
removed
faq/glifaq.dtx
