2 %<package>\NeedsTeXFormat{LaTeX2e}
5 \def\filedate{2003/10/16}
6 \ProvidesFile{glifaq.drv}
8 %<package>\ProvidesPackage{glifaq}
9 [2003/10/16 Style for PyX FAQ (gli) v0.1b]
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 three kinds of questions:
64 % |a| & answered question\\
65 % |c| & question where the answer has been checked by an expert\\
66 % |t| & question not fully answered yet (= to do)
69 % The following options are recognized by the package:
71 % \item[all] prints all questions
72 % \item[answered] prints only questions which have no ``to do'' status, i.e.
73 % they have a satisfying answer and might even have been checked
74 % \item[checked] prints only questions where the answers have been checked
75 % \item[todo] prints all questions where no satisfying answer has been
77 % \item[unchecked] prints all questions which have not been checked yet
78 % \item[comments] if comments exist, they will be printed as well and a
79 % special mark will be put in the margin
80 % \item[notoc] the table of contents will not be printed
82 % By default, all questions and the table of contents but no comments will be
83 % printed. If questions with ``to do'' status are printed, a special mark will
84 % be put in the margin.
86 % \DescribeMacro\question
87 % The most important task of the package \texttt{glifaq} is to define a command
89 % |\question{|\meta{status}|}{|\meta{title}|}{|\meta{comment}|}{|^^A
92 % to handle the typesetting of questions and their answers. As indicated, this
93 % command takes four arguments:
96 % 1: & class of the question according to the table given above\\
97 % & allowed values: |a|, |c|, |t|\\
98 % 2: & title of the question\\
99 % 3: & comments related to this question\\
100 % 4: & the answer to the question
104 % \DescribeEnv{progcode}
105 % For the typesetting of code snippets, an environment |progcode| has been
106 % defined which will use a fixed space font. Unfortunately, verbatim code
107 % cannot be used in arguments as is the case here in macro |\question|.
108 % To guarantee proper spaces and in particular indenting, a tilde has to
109 % used instead of a space.
111 % In addition, there exist a few simple definitions which may be useful:
113 % \DescribeMacro\uaref
114 % The macro |\uaref| acts like the usual |\ref| command but puts an $\uparrow$
115 % (|\uparrow|) in front of the reference.
118 % The macro |\toc| replaces the usual |\tableofcontents| to allow for control
119 % via the |notoc| option.
122 % The macro |\PyX| defines the \PyX{} logo as employed by the developers of
123 % \PyX{} in their manual.
126 % In some places, a backslash cannot be used verbatim, in particular in an
127 % argument of the |\question| macro. Using
129 % \verb*+\cs +\meta{command name}
131 % will result in a backslash followed directly by the command name.
134 % The macro |\us| can be used to produce an underscore if there is no more
135 % direct way to do so.
138 % Sometimes it may also be difficult to produce a hat character. In such cases,
139 % |\hat| can be useful.
142 % The last macro of this type is |\cb| which allows to enclose an argument in
145 % \DescribeMacro\ctan
146 % For references to files on \acro{ctan}, the macro |\ctan| can be used where
147 % the single argument should be the location of the file relative to the
149 % \DescribeMacro\ftpCTAN
150 % One of the \acro{ctan} ftp servers is coded into the package via the
151 % |\ftpCTAN| macro for direct reference from the \acro{pdf} version of the
154 % \DescribeMacro\new\DescribeMacro\changed
155 % Finally, the two macros |\new| and |\changed| allow to mark questions as
156 % new or changed with respect to an earlier version of the \acro{faq}. These
157 % macros should be used in the second argument of |\question| just behind the
158 % text defining the title of a question.
160 % \section{The Description of the Package Code}
163 % We first define a few new switches:
165 % \begin{tabular}{ll}
166 % |\if@a|& print answered questions if true\\
167 % |\if@c|& print corrected questions if true\\
168 % |\if@t|& print unanswered or not fully answered questions if true\\
169 % |\ifc@mments|& print comments if true\\
170 % |\ift@c|& insert table of contents if true
173 % By default, we print all questions and the table of contents but no comments.
178 \newif\ifc@mments \c@mmentsfalse
179 \newif\ift@c \t@ctrue
181 % Now we define the various options and set the switches according to the
182 % options' definition given in section~\ref{sec:usage}.
184 \DeclareOption{all}{\@atrue \@ctrue \@ttrue}
185 \DeclareOption{answered}{\@atrue \@ctrue \@tfalse}
186 \DeclareOption{checked}{\@afalse \@ctrue \@tfalse}
187 \DeclareOption{todo}{\@afalse \@cfalse \@ttrue}
188 \DeclareOption{unchecked}{\@atrue \@cfalse \@ttrue}
189 \DeclareOption{comments}{\c@mmentstrue}
190 \DeclareOption{notoc}{\t@cfalse}
191 \ProcessOptions\relax
193 % Next, we load some needed packages if they have not been loaded before.
195 \RequirePackage{ifthen}
196 \RequirePackage{remreset}
197 \RequirePackage{pifont}
199 % The following macro will put a large cross in the margin to mark comments or
200 % questions with ``to do'' status.
202 \newcommand{\put@ding}{\mbox{}\marginpar{\Huge\ding{56}}}
205 % Now comes the most important part of this package, the macro |\question|.
206 % This macro has to decide on the basis of the first argument and the
207 % options used with the package whether the current question is to be printed
210 % It is assumed that in the section hierarchy, the question can take the role
211 % of a subsection or a subsubsection. Therefore, a mechanism has to be
212 % provided which tells the question its place in the hierarchy. Independent
213 % of whether the question acts like a subsection or subsubsection, the layout
214 % of the question title should be the one of a subsubsection.
216 % We introduce two switches: |\@printtrue| indicates that the question has
217 % to be printed while |\@margtrue| request a mark to be put into the margin
218 % to indicate a question with ``to do'' status.
223 % Below we will need to find out which level a question corresponds to. If the
224 % value of the counter \texttt{question} is not equal to 0, the level is
225 % already known. A value of 1 indicates that the questions are on the level
226 % of a \texttt{subsection} while a value of 2 implies that the questions are
227 % on the \texttt{subsubsection} level. Whenever a new section is started, we
228 % will need to find out the level of the questions in this section. Therefore,
229 % we reset the counter \texttt{question} whenever a new section is started.
231 \newcounter{question}[section]
232 \setcounter{question}{0}
234 % Since we want to set the title of a question always in the fontsize of a
235 % \texttt{subsubsection}, we might need to temporarily change the fontsize
236 % of the \texttt{subsection} title. In order to be able to restore the original
237 % value, we save the value of |\size@subsection| which is used in the
238 % \acro{KOMA-Script} classes to define the fontsize of the \texttt{subsection}
241 \let\save@sizesubsection\size@subsection
244 % Now we are ready to define the |\question| macro. First, defaults are set
245 % not to print the question and not to print a mark in the margin. If the status
246 % of the question corresponds to one asked for by the option passed to the
247 % package, we change the print switch to |\@printtrue|. A ``to do'' question
248 % will in addition ask to print a mark in the margin by setting |\@margtrue|.
250 \newcommand{\question}[4]%
251 {\@printfalse\@margfalse%
252 \ifthenelse{\equal{a}{#1}\and\boolean{@a}}{\@printtrue}{}%
253 \ifthenelse{\equal{c}{#1}\and\boolean{@c}}{\@printtrue}{}%
254 \ifthenelse{\equal{t}{#1}\and\boolean{@t}}{\@printtrue\@margtrue}{}%
256 % If the \texttt{question} counter has the value 0, we need to determine the
257 % level of the question. The question should at least be on
258 % \texttt{subsubsection} level if not higher. So we first assume it to be
259 % of this level and make corrections later on if necessary. The counter
260 % \texttt{question} is set to a level different from 0 (in this case to a
261 % value of 2 although this is nowhere exploited in the code). This counter
262 % will now be reset not only by a |\section| but also by a |\subsection|.
263 % Finally, we set the command |\questi@n| which will typeset the question title
264 % as \texttt{subsubsection}.
266 % In a second step, we check whether the question is on |\subsection| level
267 % instead of |\subsubsection| level as was assumed before. In this case,
268 % the counter \texttt{question} is set to 1 (again it is only important that
269 % the value is different from 0). This counter should no longer be reset
270 % by a |\subsection| so we remove the corresponding entry from the reset list.
271 % Finally, the command |\questi@n| typesetting the title of the question is
272 % set to |\subsection|.
274 \ifthenelse{\value{question} = 0}{%
275 \setcounter{question}{2}%
276 \@addtoreset{question}{subsection}%
277 \let\questi@n\subsubsection%
278 \ifthenelse{\value{subsection} = 0}%
279 {\setcounter{question}{1}%
280 \@removefromreset{question}{subsection}%
281 \let\questi@n\subsection}%
285 % Now we are ready to typeset the question if this is what the options passed
286 % to the package ask for. Before typesetting the question title, we temporarily
287 % set the fontsize of the |\subsection| title to the fontsize of the
288 % |\subsubsection| just in case we are on the |\subsection| level. |\questi@n|
289 % does the typesetting of the title and a mark is put into the margin if
290 % requested by |\@margtrue|.
292 % After the title, a comment, if present, is typeset in sans serif and small
293 % fontsize. Finally, the answer, i.e. the contents of argument 4, is typeset.
296 \let\size@subsection\size@subsubsection
297 \questi@n{#2}\if@marg\put@ding\else\fi%
298 \let\size@subsection\save@sizesubsection
300 \ifthenelse{\equal{}{#3}}{}
301 {\putding{\sffamily\small#3}\par}%
307 % Since it is not possible to use verbatim code in macro arguments, we cannot
308 % typeset code snippets in an answer by using a \texttt{verbatim} environment.
309 % We therefore define the environment \texttt{progcode}. In order to ensure
310 % proper indentation, we make the tilde an active character and define
311 % it as space preceded by a |\strut| so that the space is not ignored.
312 % In addition, several layout parameters are set like a global indentation
313 % of the code and the use of a small fixed space font.
315 \newenvironment{progcode}
316 {\list{}{\leftmargin\parindent\rightmargin\z@}%
323 % To facilitate references preceded by a $\uparrow$ we define |\uaref| which
324 % works like the standard |\ref|.
326 \DeclareRobustCommand\uaref[1]{$\uparrow$\ref{#1}}
328 % The option \texttt{notoc} only works if instead of |\tableofcontents| the
329 % command |\toc| defined here is used.
331 \DeclareRobustCommand\toc[0]{\ift@c\tableofcontents\else\fi}
333 % The definition of the \PyX{} logo is copied from the code used by the \PyX{}
334 % developers in their manual. Here, we also provide the simple string ``PyX''
335 % for use in the \acro{pdf} bookmarks.
337 \DeclareRobustCommand\PyX[0]{\texorpdfstring%
338 {P\kern-.3em\lower.5ex\hbox{Y}\kern-.18em X}{PyX}%
341 % When a backslash character is needed as part of a verbatim command name,
342 % but verbatim code cannot be used, the macro |\cs| can be employed.
343 % Again, we take care of the requirements of the \acro{pdf} bookmarks.
345 \DeclareRobustCommand\cs[1]{%
346 \texorpdfstring{\texttt{\char`\\}}{\textbackslash}#1%
349 % In order to avoid problems with verbatim code, we define |\us| and |\hat|
350 % to produce an underscore and a hat, respectively.
352 \DeclareRobustCommand\us[0]{\texttt{\char`\_}}
353 \DeclareRobustCommand\hat[0]{\texttt{\char`\^}}
355 % The macro |\cb| encloses its argument in curly braces and should be used
356 % when verbatim code does not work.
358 \DeclareRobustCommand\cb[1]{\texttt{\char`\{#1\char`\}}}
360 % For files on \acro{ctan}, we define the macro |\ctan| which is used as follows
362 % |\ctan{|\meta{file location relative to CTAN root}|}|
364 % In order for the link to connect to a \acro{ctan} server, |\ftpCTAN| contains
365 % the URL of one of the \acro{ctan} servers which is chosen quite arbitrarily
366 % and could be replaced by another \acro{ctan} server. Note that we use
367 % |\path| instead of |\url| to avoid that a link is created to the second
368 % argument instead of the first one.
370 \def\ftpCTAN{ftp://ctan.tug.org/tex-archive/}
371 \DeclareRobustCommand\ctan[1]{%
372 \href{\ftpCTAN#1}{\path{CTAN:#1}}%
375 % In order to mark questions as new or changed with respect to a previous
376 % release of the \acro{faq}, we define the macros |\new| and |\changed| which
377 % are intended to be used at the end of the second argument of |\question|.
378 % No output is generated for \acro{pdf} bookmarks.
380 \DeclareRobustCommand\new[0]{\texorpdfstring%
381 {\quad\raisebox{0.3ex}{\fbox{\tiny\normalfont NEW}}}{}
383 \DeclareRobustCommand\changed[0]{\texorpdfstring%
384 {\quad\raisebox{0.3ex}{\fbox{\tiny\normalfont CHANGED}}}{}