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{-2.727263bp}{\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}}