Debian Codegraph @

texmf-dist/source/latex/catechis/catechis.dtx

raw
1 % \iffalse
2 % +AMDG This document was begun on E January 1202, and it
3 % is humbly dedicated to her Immaculate Heart for
4 % her prayers, and to the Sacred Heart of Jesus for His
5 % mercy.
6 %
7 % This document is copyright 2017 by Donald P. Goodman, and is
8 % released publicly under the LaTeX Project Public License. The
9 % distribution and modification of this work is constrained by the
10 % conditions of that license. See
11 % http://www.latex-project.org/lppl.txt
12 % for the text of the license. This document is released
13 % under version 1.3 of that license, and this work may be distributed
14 % or modified under the terms of that license or, at your option, any
15 % later version.
16 %
17 % This work has the LPPL maintenance status 'maintained'.
18 %
19 % The Current Maintainer of this work is Donald P. Goodman
20 % ([email protected]).
21 %
22 % This work consists of catechis.dtx, catechis.ins, and
23 % derived files catechis.sty and catechis.pdf.
24 % \fi
25
26 % \iffalse
27 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
28 %<package>\ProvidesPackage{catechis}[2021/07/17 v2.6 Support for writing catechism questions and answers]
29 %<*driver>
30 \documentclass{ltxdoc}
31
32 \usepackage{doc}
33 \usepackage{array}
34 \usepackage{lettrine}
35 \setcounter{DefaultLines}{3}
36 \setlength{\DefaultFindent}{2pt}
37 \renewcommand{\LettrineFontHook}{\color{red}}
38 \usepackage{url}
39 \usepackage{spverbatim}
40 \usepackage{fancyvrb}
41 \newcommand\vitem[1][]{\SaveVerb[%
42 aftersave={\item[\textnormal{\bfseries\UseVerb[#1]{vsave}}]}]{vsave}}
43 \usepackage[typeone]{dozenal}
44 \usepackage{lmodern}
45 \usepackage[]{catechis}
46 \usepackage[colorlinks]{hyperref}
47 \usepackage{makeidx}
48 \EnableCrossrefs
49 \PageIndex
50 \CodelineNumbered
51 \RecordChanges
52 \makeindex
53
54 \def\exline{\bigskip\hrule\bigskip}
55
56 \tracingmacros=3 \begin{document} \DocInput{catechis.dtx}
57 \end{document}
58 %</driver> \fi
59 %
60 % \title{The |catechis| Package, v2.6} \author{Donald P.\
61 % Goodman III} \date{\today}
62 %
63 % \maketitle
64 %
65 % \begin{abstract}
66 % \noindent
67 % The catechism (a text consisting of explicitly-stated and
68 % usually numbered questions and answers) has long been an
69 % important vehicle for teaching the basics of concepts.
70 % \LaTeX, however, does not by default have much facility
71 % for producing such texts. The |catechis| package provides
72 % a number of highly customizable macros for writing
73 % catechisms, including a numbered question-and-answer
74 % environment; comments on answers; and citations.
75 % \end{abstract}
76 %
77 % \tableofcontents
78 %
79 % \section{Introduction}
80 %
81 % Catechisms are largely known for basic religious
82 % instruction, and this has indeed been their primary use.
83 % For this reason alone, \LaTeX\ ought to have some
84 % facilities for authoring them. Furthermore, the form is
85 % useful for other topics, as well; it provides an easy way
86 % to give basic information on a topic, making it easily
87 % extractable by eye from the full text, while still
88 % allowing more advanced discussion for those who wish to
89 % plunge more deeply into a given question.
90 %
91 % |catechis| is packaged according to the \LaTeX\
92 % \textsc{docstrip} utility, which allows automatic
93 % extraction of code and documentation from the same files.
94 %
95 % This is version 2.0 of |catechis|; it represents a mostly
96 % complete rewrite of the package, which is therefore much
97 % simpler and more robust.
98 %
99 % \section{The State of the \TeX\ for Catechisms}
100 % \label{sect:state}
101 %
102 % \LaTeX\ has basically no provision for producing
103 % well-formed catechisms. It's easy enough to fake it, of
104 % course; for example:
105 %
106 % \begin{verbatim}
107 % \begin{enumerate}
108 % \item\textbf{Who made us?} \\ God made us.
109 % \item\textbf{Why did God make us?} \\ God made us to
110 % know Him, love Him, and serve Him, and by so doing
111 % to gain everlasting life with Him in Heaven.
112 % \end{enumerate}
113 % \end{verbatim}
114 %
115 % This gives the following result:
116 %
117 % \exline
118 %\begin{enumerate}
119 % \item\textbf{Who made us?} \\ God made us.
120 % \item\textbf{Why did God make us?} \\ God made us to
121 % know Him, love Him, and serve Him, and by so doing
122 % to gain everlasting life with Him in Heaven.
123 %\end{enumerate}
124 % \exline
125 %
126 % However, this solution is far from satisfactory. It's
127 % unportable, fit really only for this one document;
128 % uncustomizable, because it's hard-wired to do only this
129 % one thing; unmodifiable, at least automatically, because
130 % it uses explicit visual formatting in the text; and far
131 % too wordy. What is desired is something more along the
132 % lines of the following:
133 %
134 % \begin{verbatim}
135 % \catques{Who made us?}{God made us.}
136 % \catques{Why did God make us?}{God made us to
137 % know Him, love Him, and serve Him, and by so doing
138 % to gain everlasting life with Him in Heaven.}
139 % \end{verbatim}
140 %
141 % Which, with the |catechis| package, produces this:
142 %
143 % \exline
144 % \catques{Who made us?}{God made us.}
145 % \catques{Why did God make us?}{God made us to
146 % know Him, love Him, and serve Him, and by so doing
147 % to gain everlasting life with Him in Heaven.}
148 % \catques{What will happen if the question is really long,
149 % so that it wraps to the next line?}{It will work properly,
150 % with the wrapped line appropriately indented. The answer,
151 % as you have already seen, will behave likewise.}
152 % \exline
153 %
154 % |catechis| provides these facilities and more to produce
155 % high-quality, useful catechisms.
156 %
157 % \section{Basic Usage}
158 % \label{sect:basics}
159 %
160 % The most basic usage of |catechis| is encompassed by the
161 % \DescribeMacro{\catques}|\catques| macro:
162 %
163 % \begin{center}
164 % \cmd{\catques} \marg{question} \marg{answer}
165 % \end{center}
166 %
167 % There is no more to this than meets the eye. Both
168 % arguments are mandatory, though either may be empty; the
169 % first is the question, and the second is the answer. It
170 % is often helpful to indent sensibly to keep these more
171 % readable in the source:
172 %
173 % \begin{verbatim}
174 % \catques{What is the question?}{%
175 % The question is, ``What is the question?''}%
176 % \end{verbatim}
177 %
178 % This produces the following:
179 %
180 % \exline
181 % \catques{What is the question?}{The question is, ``What is the question?''}%
182 % \exline
183 %
184 % Our next macro, \DescribeMacro{\catcomment}|\catcomment|,
185 % really shows the genius of the catechism concept. The
186 % question and answer are the \emph{basic} information; it's
187 % easily followed up by a comment, which is visually
188 % separate and can be skipped by those interested in, or
189 % only ready for, the basics, but is still sensibly placed
190 % and ready for those who wish it.
191 %
192 % \exline
193 % \catques{What is the question?}{The question is, ``What is the question?''}%
194 % \catcomment{This is a comment. It's very interesting, it
195 % wraps and indents correctly, and the package's default
196 % comment style is demonstrated here.}
197 % \catques{How are the questions numbered? Are they
198 % numbered sequentially, throughout the text?}{Yes, the
199 % questions are numbered sequentially throughout the text.
200 % You can reset the numbers manually, which we'll talk about
201 % later; but by default, there is one question stream which
202 % is numbered from 1 on up.}
203 % \catcomment{We're numbering questions sequentially to show
204 % that you can have catechism questions scattered throughout
205 % a text, or your text can be entirely in the form of a
206 % catechism. |catechis| works either way.}
207 % \exline
208 %
209 % There is also the \DescribeMacro{\catexplic}|\catexplic|
210 % command, which works essentially identically to
211 % |\catcomment| but can include paragraph breaks and is
212 % intended for much lengthier commentary on the answer.
213 %
214 % \begin{verbatim}
215 % \catques{What is the question?}{The question is, ``What is the question?''}%
216 % \catcomment{This is a comment. It's very interesting, it
217 % wraps and indents correctly, and the package's default
218 % comment style is demonstrated here.}
219 % \catexplic{We can make some really impressive things
220 % happen with this command. While comments allow
221 % short explanatory comments on an answer, explics
222 % give us field to go on for a long time, if we want.
223 %
224 % We can put in paragraph breaks, and we can even do the
225 % following:
226 % \begin{compactenum}
227 % \item We can put lists in them!
228 % \item Isn't that cool? This can provide a great way to
229 % give advanced information on a topic that people can read
230 % if they want, or just skip on to the next question!
231 % \end{compactenum}\restoreindents
232 %
233 % You can really produce beautiful catechetical works using
234 % this facility, which will do a great job of instructing
235 % people at all levels of expertise.
236 % }%
237 % \end{verbatim}
238 %
239 % \exline
240 % \catques{What is the question?}{The question is, ``What is the question?''}%
241 % \catcomment{This is a comment. It's very interesting, it
242 % wraps and indents correctly, and the package's default
243 % comment style is demonstrated here.}
244 % \catexplic{We can make some really impressive things
245 % happen with this command. While comments allow
246 % short explanatory comments on an answer, explics
247 % give us field to go on for a long time, if we want.
248 %
249 % We can put in paragraph breaks, the indentation of which
250 % we can control with fine granularity; and we can even do the
251 % following:
252 %
253 % \begin{compactenum}
254 % \item We can put lists in them!
255 % \item Isn't that cool? This can provide a great way to
256 % give advanced information on a topic that people can read
257 % if they want, or just skip on to the next question!
258 % \end{compactenum}\restoreindents
259 %
260 % You can really produce beautiful catechetical works using
261 % this facility, which will do a great job of instructing
262 % people at all levels of expertise.
263 %
264 % }%
265 % \exline
266 %
267 % You'll note that lists \emph{will} hose all of
268 % |catechis|'s careful indentation, so after using one in a
269 % |\catexplic|, you must issue
270 % \DescribeMacro{\restoreindents}|\restoreindents| to get
271 % everything back to normal.
272 %
273 % Catechisms also routinely provide citations to support
274 % their claims; |catechis| provides for this, too. A
275 % heading for a group of citations is printed by issuing
276 % \DescribeMacro{\catcitetitle}|\catcitetitle|, and each
277 % individual citation is printed by issuing the |\catcite|
278 % command, which takes the citation as the first argument
279 % and the source as the second:
280 %
281 % \begin{center}
282 % \DescribeMacro{\catcite}
283 % \cmd{\catcite} \marg{citation} \marg{source}
284 % \end{center}
285 %
286 % An example:
287 %
288 % \begin{verbatim}
289 % \catcitetitle
290 % \catcite{For the apparel oft proclaims the man.}{Polonius}
291 % \catcite{And this above all: to thine own self be true; /
292 % and it must follow, as the night the day, / that thou
293 % canst not be false to any man.}{Polonius}
294 % \end{verbatim}
295 %
296 % \exline
297 % \catcitetitle
298 % \catcite{For the apparel oft proclaims the man.}{Polonius}
299 % \catcite{And this above all: to thine own self be true; /
300 % and it must follow, as the night the day, / that thou
301 % canst not be false to any man.}{Polonius}
302 % \exline
303 %
304 % Because this will often not result in proper spacing,
305 % |catechis| provides an environment,
306 % \DescribeMacro{catcitations}|catcitations|, which
307 % will insert appropriate spacing before and after the
308 % citations. This environment will automatically run
309 % |\catcitetitle| for you.
310 %
311 % \begin{verbatim}
312 % \begin{catcitations}
313 % \catcite{For the apparel oft proclaims the man.}{Polonius}
314 % \catcite{And this above all: to thine own self be true; /
315 % and it must follow, as the night the day, / that thou
316 % canst not be false to any man.}{Polonius}
317 % \end{catcitations}
318 % \end{verbatim}
319 %
320 % \exline
321 % \begin{catcitations}
322 % \catcite{For the apparel oft proclaims the man.}{Polonius}
323 % \catcite{And this above all: to thine own self be true; /
324 % and it must follow, as the night the day, / that thou
325 % canst not be false to any man.}{Polonius}
326 % \end{catcitations}
327 % \exline
328 %
329 % Lastly, |catechis| gives some provisions for more
330 % customary catechetical enumerates. It uses standard
331 % features from the |paralist| package for this, and simply
332 % makes those the default.
333 %
334 % \begin{verbatim}
335 % \catques{Can we do enumerates?}{Yes, we can do those; we
336 % can even do them in a special way, so that it looks more
337 % like the way catechisms customarily look.}
338 % \catcomment{Just check this out; we have here a comment
339 % giving slightly more detailed information, then an
340 % enumerate giving \emph{much} more detailed information.}
341 % \begin{enumerate}
342 % \item Here, we have the first item, with some extra
343 % details elaborating on what was said before.
344 % \item Here, we have another item.
345 % \item Here, we have still another.
346 % \end{enumerate}
347 % \end{verbatim}
348 %
349 % \exline
350 % \catques{Can we do enumerates?}{Yes, we can do those; we
351 % can even do them in a special way, so that it looks more
352 % like the way catechisms customarily look.}
353 % \catcomment{Just check this out; we have here a comment
354 % giving slightly more detailed information, then an
355 % enumerate giving \emph{much} more detailed information.}
356 % \begin{compactenum}
357 % \item Here, we have the first item, with some extra
358 % details elaborating on what was said before.
359 % \item Here, we have another item.
360 % \item Here, we have still another.
361 % \end{compactenum}
362 % \exline
363 %
364 % \section{Customization}
365 % \label{sect:custom}
366 %
367 % Pretty much everything in the package can be customized.
368 % The names of the necessary commands and lengths are fairly
369 % predictable: they will start with |\cat|, be followed by
370 % the type of thing (|ques|, |comm|, |explic|, etc.), and
371 % then the property to be set (|sty|, |indent|, |hindent|,
372 % etc.).
373 %
374 % In all cases, lengths are set with |\setlength|, while
375 % commands are set with |\newcommand| or |\def|.
376 %
377 % \begin{description}
378 % \vitem|catquesnum| \DescribeMacro{catquesnum} The counter
379 % which |catechis| maintains for the questions. It can be
380 % set or reset with the usual \LaTeX\ counter commands
381 % (e.g., |\setcounter|, |\addtocounter|).
382 % \vitem|\thecatquesnum| \DescribeMacro{\thecatquesnum} The
383 % actual typeset version of |catquesnum|. By default, this
384 % is defined as |\renewcommand{\thecatquesnum}{\arabic{catquesnum}.}|.
385 % \vitem|\catquesnumwd| \DescribeMacro{\catquesnumwd} The
386 % width of the box in which |catechis| typesets the question
387 % number. By default, |2em|.
388 % \vitem|\catquesindent| \DescribeMacro{\catquesindent}
389 % The indentation of the first line of the question in
390 % |\catques|. By default, |0em|.
391 % \vitem|\catqueshindent| \DescribeMacro{\catqueshindent}
392 % The indentation of subsequent lines of the question in
393 % |\catques|. By default, |2em|.
394 % \vitem|\catquessty| \DescribeMacro{\catquessty} The style
395 % in which the question will be printed in |\catques|. By
396 % default, |\bfseries|.
397 % \vitem|\catansindent| \DescribeMacro{\catansindent}
398 % The indentation of the first line of the answer in
399 % |\catques|. By default, |2em|.
400 % \vitem|\catanshindent| \DescribeMacro{\catanshindent}
401 % The indentation of subsequent lines of the answer in
402 % |\catques|. By default, |2em|.
403 % \vitem|\catanssty| \DescribeMacro{\catanssty} The style
404 % in which the answer will be printed in |\catques|. By
405 % default, empty.
406 % \vitem|\catcommindent| \DescribeMacro{\catcommindent}
407 % The indentation of the first line of the comment in
408 % |\catcomment|. By default, |2em|.
409 % \vitem|\catcommhindent| \DescribeMacro{\catcommhindent}
410 % The indentation of subsequent lines of the comment in
411 % |\catcomment|. By default, |2em|.
412 % \vitem|\catcommsty| \DescribeMacro{\catcommsty} The style
413 % in which the comment will be printed in |\catcomment|. By
414 % default, empty.
415 % \vitem|\catexplicindent| \DescribeMacro{\catexplicindent}
416 % The indentation of the first line of the paragraphs in a
417 % |\catexplic|. By default, |4em|.
418 % \vitem|\catexplichindent| \DescribeMacro{\catexplichindent}
419 % The indentation of subsequent lines of the paragraphs in a
420 % |\catexplic|. By default, |2em|.
421 % \vitem|\catexplicsty| \DescribeMacro{\catexplicsty} The style
422 % in which the comment will be printed in |\catexplic|. By
423 % default, |\small|.
424 % \vitem|\catcitetitleword|
425 % \DescribeMacro{\catcitetitleword} The word which the
426 % |\catcitetitle| command will print. By default,
427 % |Citations|.
428 % \vitem|\catcitetitlesty| \DescribeMacro{\catcitetitlesty}
429 % The style in which |\catcitetitle| will print its
430 % contents. By default, |\Large\scshape|.
431 % \vitem|\catcitationbefskip| \DescribeMacro{\catcitationbefskip}
432 % The distance to skip prior to beginning a |catcitations|
433 % environment, before running |\catcitetitle|.
434 % \vitem|\catcitationaftskip| \DescribeMacro{\catcitationaftskip}
435 % The distance to skip after ending a |catcitations|
436 % environment.
437 % \vitem|\catciteindent| \DescribeMacro{\catciteindent} The
438 % indentation of the first line of the citation itself
439 % (that is, the quotation) in a |\catcite|. By default,
440 % |0em|.
441 % \vitem|\catcitehindent| \DescribeMacro{\catcitehindent}
442 % The indentation of subsequent lines in the citation itself
443 % (that is, the quotation) in a |\catcite|. By default,
444 % |0em|.
445 % \vitem|\catcitesty| \DescribeMacro{\catcitesty} The style
446 % in which the citation itself (that is, the quotation) will
447 % be printed in |\catcite|. By default, |\itshape|.
448 % \vitem|\catsrcindent| \DescribeMacro{\catsrcindent} The
449 % indentation of the first line of the source
450 % in a |\catcite|. By default, |2em|.
451 % \vitem|\catsrchindent| \DescribeMacro{\catsrchindent}
452 % The indentation of subsequent lines in the source
453 % in a |\catcite|. By default, |2em|.
454 % \vitem|\catsrcsty| \DescribeMacro{\catsrcsty} The style in
455 % which the source will be printed in |\catcite|. By
456 % default, empty.
457 % \end{description}
458 %
459 % Finally, the list settings are all from |paralist|, so
460 % that package's documentation should be consulted for
461 % changing the defaults set up for them.
462 %
463 % These options are sufficient to manipulate |catechis|
464 % into behaving however you'd like.
465 %
466 % \section{Implementation}
467 %
468 % Start by requiring |paralist|, to take care of our custom
469 % enumerates.
470 % \begin{macrocode}
471 \RequirePackage{paralist}
472 \setdefaultenum{(a)}{(1)}{(i)}{(A)}
473 \setdefaultleftmargin{3.8em}{}{}{}{}{}
474 % \end{macrocode}
475 % Now we create the indentations and styles for the default
476 % question counter, the questions themselves, and the
477 % answers. We also set sensible defaults.
478 % \begin{macrocode}
479 \newlength{\catquesindent}\setlength{\catquesindent}{0em}
480 \newlength{\catqueshindent}\setlength{\catqueshindent}{2em}
481 \newlength{\catansindent}\setlength{\catansindent}{2em}
482 \newlength{\catanshindent}\setlength{\catanshindent}{2em}
483 \newlength{\catquesnumwd}\setlength{\catquesnumwd}{2em}
484 \newcounter{catquesnum}\setcounter{catquesnum}{0}
485 \def\catquesnumsty{\bfseries}
486 \def\catquessty{\bfseries}
487 \def\catanssty{}
488 \renewcommand{\thecatquesnum}{\arabic{catquesnum}.}
489 % \end{macrocode}
490 % Here, we define the catechism question macro. Nothing
491 % much surprising here.
492 % \begin{macrocode}
493 \def\catques#1#2{%
494 \stepcounter{catquesnum}%
495 \def\@currentlabel{\thecatquesnum}%
496 {\parindent=\catquesindent\hangindent=\catqueshindent\hangafter=1%
497 {\par\leavevmode\hbox to\catquesnumwd{\catquesnumsty\thecatquesnum\hfil}%
498 \catquessty #1}\par\nobreak}%
499 {\parindent=\catansindent\hangindent=\catanshindent\hangafter=1%
500 {\par\catanssty #2}\par}%
501 }%
502 % \end{macrocode}
503 % Define the catechism comments, and set sensible defaults
504 % for the settings.
505 % \begin{macrocode}
506 \def\catcommsty{}
507 \newlength{\commindent}\setlength{\commindent}{2em}
508 \newlength{\commhindent}\setlength{\commhindent}{2em}
509 \def\catcomment#1{%
510 {\parindent=\commindent\hangindent=\commhindent\hangafter=1%
511 {\par\catcommsty #1}\par}
512 }%
513 % \end{macrocode}
514 % Define the catechism explications (longer than comments,
515 % allowing paragraph breaks), and set sensible defaults for
516 % their settings.
517 % \begin{macrocode}
518 \def\catexplicsty{\small}
519 \newlength{\explicindent}\setlength{\explicindent}{4em}
520 \newlength{\explichindent}\setlength{\explichindent}{2em}
521 \long\def\catexplic#1{%
522 {\par\everypar={\parindent=\explicindent\hangindent=\explichindent\hangafter=1}%
523 {\par\catexplicsty\ #1}\par}%
524 }%
525 % \end{macrocode}
526 % Because lists always seem to run roughshod over
527 % indentation settings, and because it's easier to do this
528 % than to write custom lists just for this package, we
529 % define |\restoreindents| to fix settings after a list in a
530 % |\catexplic|.
531 % \begin{macrocode}
532 \def\restoreindents{%
533 \par%
534 \everypar={%
535 \parindent=\explicindent%
536 \hangindent=\explichindent%
537 \hangafter=1%
538 }%
539 \par%
540 }%
541 % \end{macrocode}
542 % Define the commands to produce citation titles, and set
543 % sensible defaults; also for the citation environment.
544 % \begin{macrocode}
545 \def\catcitetitlesty{\Large\scshape}%
546 \def\catcitetitleword{Citations}%
547 \def\catcitetitle{%
548 \hbox to\linewidth{%
549 \hfil%
550 {\catcitetitlesty\catcitetitleword}%
551 \hfil%
552 }%
553 \penalty10000%
554 }%
555 \newlength\catcitationbefskip\catcitationbefskip=1em%
556 \newlength\catcitationaftskip\catcitationaftskip=1em%
557 \def\catcitations{%
558 \leavevmode%
559 \vskip\catcitationbefskip%
560 \catcitetitle%
561 }%
562 \def\endcatcitations{%
563 \leavevmode%
564 \vskip\catcitationaftskip%
565 }%
566 % \end{macrocode}
567 % Define actual citations macros and lengths.
568 % \begin{macrocode}
569 \def\catcitesty{\itshape}%
570 \def\catsrcsty{}%
571 \newlength{\catciteindent}\setlength{\catciteindent}{0em}%
572 \newlength{\catcitehindent}\setlength{\catcitehindent}{0em}%
573 \newlength{\catsrcindent}\setlength{\catsrcindent}{2em}%
574 \newlength{\catsrchindent}\setlength{\catsrchindent}{2em}%
575 \def\catcite#1#2{%
576 {\parindent=\catciteindent\hangindent=\catcitehindent\hangafter=1%
577 {\par\catcitesty #1}\par}%
578 \penalty10000%
579 {\parindent=\catsrcindent\hangindent=\catsrchindent\hangafter=1%
580 {\par\catsrcsty#2}\par}%
581 }%
582 \let\scripture=\catcite
583 % \end{macrocode}
584 %
585 % And that's it. Happy \TeX{}ing!
586 %
587 % \PrintIndex