summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/catechis/catechis.dtx
blob: fe184bf45d8286280b2419e61fd9d43b6f06bc30 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
% \iffalse
% +AMDG  This document was begun on E January 1202, and it
% is humbly dedicated to her Immaculate Heart for
% her prayers, and to the Sacred Heart of Jesus for His
% mercy.
%
% This document is copyright 2017 by Donald P. Goodman, and is
% released publicly under the LaTeX Project Public License.  The
% distribution and modification of this work is constrained by the
% conditions of that license.  See
% 	http://www.latex-project.org/lppl.txt
% for the text of the license.  This document is released
% under version 1.3 of that license, and this work may be distributed
% or modified under the terms of that license or, at your option, any
% later version.
% 
% This work has the LPPL maintenance status 'maintained'.
% 
% The Current Maintainer of this work is Donald P. Goodman
% (dgoodmaniii@gmail.com).
% 
% This work consists of catechis.dtx, catechis.ins, and
% derived files catechis.sty and catechis.pdf.
% \fi

% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{catechis}[2021/07/17 v2.6 Support for writing catechism questions and answers]
%<*driver>
\documentclass{ltxdoc}

\usepackage{doc}
\usepackage{array}
\usepackage{lettrine}
	\setcounter{DefaultLines}{3}
	\setlength{\DefaultFindent}{2pt}
	\renewcommand{\LettrineFontHook}{\color{red}}
\usepackage{url}
\usepackage{spverbatim}
\usepackage{fancyvrb}
	\newcommand\vitem[1][]{\SaveVerb[%
		aftersave={\item[\textnormal{\bfseries\UseVerb[#1]{vsave}}]}]{vsave}}
\usepackage[typeone]{dozenal}
\usepackage{lmodern}
\usepackage[]{catechis}
\usepackage[colorlinks]{hyperref}
\usepackage{makeidx}
\EnableCrossrefs
\PageIndex
\CodelineNumbered
\RecordChanges
\makeindex

\def\exline{\bigskip\hrule\bigskip}

\tracingmacros=3 \begin{document} \DocInput{catechis.dtx}
\end{document}
%</driver> \fi
%
% \title{The |catechis| Package, v2.6} \author{Donald P.\
% Goodman III} \date{\today}
%
% \maketitle
%
% \begin{abstract}
% \noindent
% The catechism (a text consisting of explicitly-stated and
% usually numbered questions and answers) has long been an
% important vehicle for teaching the basics of concepts.
% \LaTeX, however, does not by default have much facility
% for producing such texts.  The |catechis| package provides
% a number of highly customizable macros for writing
% catechisms, including a numbered question-and-answer
% environment; comments on answers; and citations.
% \end{abstract}
%
% \tableofcontents
%
% \section{Introduction}
%
% Catechisms are largely known for basic religious
% instruction, and this has indeed been their primary use.
% For this reason alone, \LaTeX\ ought to have some
% facilities for authoring them.  Furthermore, the form is
% useful for other topics, as well; it provides an easy way
% to give basic information on a topic, making it easily
% extractable by eye from the full text, while still
% allowing more advanced discussion for those who wish to
% plunge more deeply into a given question.
%
% |catechis| is packaged according to the \LaTeX\
% \textsc{docstrip} utility, which allows automatic
% extraction of code and documentation from the same files.
%
% This is version 2.0 of |catechis|; it represents a mostly
% complete rewrite of the package, which is therefore much
% simpler and more robust.
%
% \section{The State of the \TeX\ for Catechisms}
% \label{sect:state}
%
% \LaTeX\ has basically no provision for producing
% well-formed catechisms.  It's easy enough to fake it, of
% course; for example:
%
% \begin{verbatim}
% \begin{enumerate}
%		\item\textbf{Who made us?} \\ God made us.
%		\item\textbf{Why did God make us?} \\ God made us to
%			know Him, love Him, and serve Him, and by so doing
%			to gain everlasting life with Him in Heaven.
% \end{enumerate}
% \end{verbatim}
%
% This gives the following result:
%
% \exline
%\begin{enumerate}
%		\item\textbf{Who made us?} \\ God made us.
%		\item\textbf{Why did God make us?} \\ God made us to
%			know Him, love Him, and serve Him, and by so doing
%			to gain everlasting life with Him in Heaven.
%\end{enumerate}
% \exline
%
% However, this solution is far from satisfactory.  It's
% unportable, fit really only for this one document;
% uncustomizable, because it's hard-wired to do only this
% one thing; unmodifiable, at least automatically, because
% it uses explicit visual formatting in the text; and far
% too wordy.  What is desired is something more along the
% lines of the following:
%
% \begin{verbatim}
% \catques{Who made us?}{God made us.}
% \catques{Why did God make us?}{God made us to
%	know Him, love Him, and serve Him, and by so doing
%	to gain everlasting life with Him in Heaven.}
% \end{verbatim}
%
% Which, with the |catechis| package, produces this:
%
% \exline
% \catques{Who made us?}{God made us.}
% \catques{Why did God make us?}{God made us to
%	know Him, love Him, and serve Him, and by so doing
%	to gain everlasting life with Him in Heaven.}
% \catques{What will happen if the question is really long,
% so that it wraps to the next line?}{It will work properly,
% with the wrapped line appropriately indented.  The answer,
% as you have already seen, will behave likewise.}
% \exline
%
% |catechis| provides these facilities and more to produce
% high-quality, useful catechisms.
%
% \section{Basic Usage}
% \label{sect:basics}
%
% The most basic usage of |catechis| is encompassed by the
% \DescribeMacro{\catques}|\catques| macro:
%
% \begin{center}
% \cmd{\catques} \marg{question} \marg{answer}
% \end{center}
%
% There is no more to this than meets the eye.  Both
% arguments are mandatory, though either may be empty; the
% first is the question, and the second is the answer.  It
% is often helpful to indent sensibly to keep these more
% readable in the source:
%
% \begin{verbatim}
% \catques{What is the question?}{%
%        The question is, ``What is the question?''}%
% \end{verbatim}
%
% This produces the following:
%
% \exline
% \catques{What is the question?}{The question is, ``What is the question?''}%
% \exline
%
% Our next macro, \DescribeMacro{\catcomment}|\catcomment|,
% really shows the genius of the catechism concept.  The
% question and answer are the \emph{basic} information; it's
% easily followed up by a comment, which is visually
% separate and can be skipped by those interested in, or
% only ready for, the basics, but is still sensibly placed
% and ready for those who wish it.
%
% \exline
% \catques{What is the question?}{The question is, ``What is the question?''}%
% \catcomment{This is a comment.  It's very interesting, it
% wraps and indents correctly, and the package's default
% comment style is demonstrated here.}
% \catques{How are the questions numbered?  Are they
% numbered sequentially, throughout the text?}{Yes, the
% questions are numbered sequentially throughout the text.
% You can reset the numbers manually, which we'll talk about
% later; but by default, there is one question stream which
% is numbered from 1 on up.}
% \catcomment{We're numbering questions sequentially to show
% that you can have catechism questions scattered throughout
% a text, or your text can be entirely in the form of a
% catechism.  |catechis| works either way.}
% \exline
%
% There is also the \DescribeMacro{\catexplic}|\catexplic|
% command, which works essentially identically to
% |\catcomment| but can include paragraph breaks and is
% intended for much lengthier commentary on the answer.
%
% \begin{verbatim}
% \catques{What is the question?}{The question is, ``What is the question?''}%
% \catcomment{This is a comment.  It's very interesting, it
% wraps and indents correctly, and the package's default
% comment style is demonstrated here.}
% \catexplic{We can make some really impressive things
% happen with this command.  While comments allow
% short explanatory comments on an answer, explics
% give us field to go on for a long time, if we want.
%
% We can put in paragraph breaks, and we can even do the
% following:
% \begin{compactenum}
% \item We can put lists in them!
% \item Isn't that cool?  This can provide a great way to
% give advanced information on a topic that people can read
% if they want, or just skip on to the next question!
% \end{compactenum}\restoreindents
%
% You can really produce beautiful catechetical works using
% this facility, which will do a great job of instructing
% people at all levels of expertise.
% }%
% \end{verbatim}
%
% \exline
% \catques{What is the question?}{The question is, ``What is the question?''}%
% \catcomment{This is a comment.  It's very interesting, it
% wraps and indents correctly, and the package's default
% comment style is demonstrated here.}
% \catexplic{We can make some really impressive things
% happen with this command.  While comments allow
% short explanatory comments on an answer, explics
% give us field to go on for a long time, if we want.
%
% We can put in paragraph breaks, the indentation of which
% we can control with fine granularity; and we can even do the
% following:
%
% \begin{compactenum}
% \item We can put lists in them!
% \item Isn't that cool?  This can provide a great way to
% give advanced information on a topic that people can read
% if they want, or just skip on to the next question!
% \end{compactenum}\restoreindents
%
% You can really produce beautiful catechetical works using
% this facility, which will do a great job of instructing
% people at all levels of expertise.
%
% }%
% \exline
%
% You'll note that lists \emph{will} hose all of
% |catechis|'s careful indentation, so after using one in a
% |\catexplic|, you must issue
% \DescribeMacro{\restoreindents}|\restoreindents| to get
% everything back to normal.
%
% Catechisms also routinely provide citations to support
% their claims; |catechis| provides for this, too.  A
% heading for a group of citations is printed by issuing
% \DescribeMacro{\catcitetitle}|\catcitetitle|, and each
% individual citation is printed by issuing the |\catcite|
% command, which takes the citation as the first argument
% and the source as the second:
%
% \begin{center}
% \DescribeMacro{\catcite}
% \cmd{\catcite} \marg{citation} \marg{source}
% \end{center}
%
% An example:
%
% \begin{verbatim}
% \catcitetitle
% \catcite{For the apparel oft proclaims the man.}{Polonius}
% \catcite{And this above all: to thine own self be true; /
% and it must follow, as the night the day, / that thou
% canst not be false to any man.}{Polonius}
% \end{verbatim}
%
% \exline
% \catcitetitle
% \catcite{For the apparel oft proclaims the man.}{Polonius}
% \catcite{And this above all: to thine own self be true; /
% and it must follow, as the night the day, / that thou
% canst not be false to any man.}{Polonius}
% \exline
%
% Because this will often not result in proper spacing,
% |catechis| provides an environment,
% \DescribeMacro{catcitations}|catcitations|, which
% will insert appropriate spacing before and after the
% citations.  This environment will automatically run
% |\catcitetitle| for you.
%
% \begin{verbatim}
% \begin{catcitations}
% \catcite{For the apparel oft proclaims the man.}{Polonius}
% \catcite{And this above all: to thine own self be true; /
% and it must follow, as the night the day, / that thou
% canst not be false to any man.}{Polonius}
% \end{catcitations}
% \end{verbatim}
%
% \exline
% \begin{catcitations}
% \catcite{For the apparel oft proclaims the man.}{Polonius}
% \catcite{And this above all: to thine own self be true; /
% and it must follow, as the night the day, / that thou
% canst not be false to any man.}{Polonius}
% \end{catcitations}
% \exline
%
% Lastly, |catechis| gives some provisions for more
% customary catechetical enumerates.  It uses standard
% features from the |paralist| package for this, and simply
% makes those the default.
%
% \begin{verbatim}
% \catques{Can we do enumerates?}{Yes, we can do those; we
% can even do them in a special way, so that it looks more
% like the way catechisms customarily look.}
% \catcomment{Just check this out; we have here a comment
% giving slightly more detailed information, then an
% enumerate giving \emph{much} more detailed information.}
% \begin{enumerate}
% \item Here, we have the first item, with some extra
% details elaborating on what was said before.
% \item Here, we have another item.
% \item Here, we have still another.
% \end{enumerate}
% \end{verbatim}
% 
% \exline
% \catques{Can we do enumerates?}{Yes, we can do those; we
% can even do them in a special way, so that it looks more
% like the way catechisms customarily look.}
% \catcomment{Just check this out; we have here a comment
% giving slightly more detailed information, then an
% enumerate giving \emph{much} more detailed information.}
% \begin{compactenum}
% \item Here, we have the first item, with some extra
% details elaborating on what was said before.
% \item Here, we have another item.
% \item Here, we have still another.
% \end{compactenum}
% \exline
%
% \section{Customization}
% \label{sect:custom}
%
% Pretty much everything in the package can be customized.
% The names of the necessary commands and lengths are fairly
% predictable: they will start with |\cat|, be followed by
% the type of thing (|ques|, |comm|, |explic|, etc.), and
% then the property to be set (|sty|, |indent|, |hindent|,
% etc.).
%
% In all cases, lengths are set with |\setlength|, while
% commands are set with |\newcommand| or |\def|.
%
% \begin{description}
% \vitem|catquesnum| \DescribeMacro{catquesnum} The counter
% which |catechis| maintains for the questions.  It can be
% set or reset with the usual \LaTeX\ counter commands
% (e.g., |\setcounter|, |\addtocounter|).
% \vitem|\thecatquesnum| \DescribeMacro{\thecatquesnum}  The
% actual typeset version of |catquesnum|.  By default, this
% is defined as |\renewcommand{\thecatquesnum}{\arabic{catquesnum}.}|.
% \vitem|\catquesnumwd| \DescribeMacro{\catquesnumwd}  The
% width of the box in which |catechis| typesets the question
% number.  By default, |2em|.
%	\vitem|\catquesindent| \DescribeMacro{\catquesindent}
%	The indentation of the first line of the question in
%	|\catques|.  By default, |0em|.
% \vitem|\catqueshindent| \DescribeMacro{\catqueshindent}
% The indentation of subsequent lines of the question in
% |\catques|.  By default, |2em|.
% \vitem|\catquessty| \DescribeMacro{\catquessty} The style
% in which the question will be printed in |\catques|.  By
% default, |\bfseries|.
%	\vitem|\catansindent| \DescribeMacro{\catansindent}
%	The indentation of the first line of the answer in
%	|\catques|.  By default, |2em|.
% \vitem|\catanshindent| \DescribeMacro{\catanshindent}
% The indentation of subsequent lines of the answer in
% |\catques|.  By default, |2em|.
% \vitem|\catanssty| \DescribeMacro{\catanssty} The style
% in which the answer will be printed in |\catques|.  By
% default, empty.
%	\vitem|\catcommindent| \DescribeMacro{\catcommindent}
%	The indentation of the first line of the comment in
%	|\catcomment|.  By default, |2em|.
% \vitem|\catcommhindent| \DescribeMacro{\catcommhindent}
% The indentation of subsequent lines of the comment in
% |\catcomment|.  By default, |2em|.
% \vitem|\catcommsty| \DescribeMacro{\catcommsty} The style
% in which the comment will be printed in |\catcomment|.  By
% default, empty.
%	\vitem|\catexplicindent| \DescribeMacro{\catexplicindent}
%	The indentation of the first line of the paragraphs in a 
%	|\catexplic|.  By default, |4em|.
% \vitem|\catexplichindent| \DescribeMacro{\catexplichindent}
% The indentation of subsequent lines of the paragraphs in a
% |\catexplic|.  By default, |2em|.
% \vitem|\catexplicsty| \DescribeMacro{\catexplicsty} The style
% in which the comment will be printed in |\catexplic|.  By
% default, |\small|.
% \vitem|\catcitetitleword|
% \DescribeMacro{\catcitetitleword}  The word which the
% |\catcitetitle| command will print.  By default,
% |Citations|.
% \vitem|\catcitetitlesty| \DescribeMacro{\catcitetitlesty}
% The style in which |\catcitetitle| will print its
% contents.  By default, |\Large\scshape|.
% \vitem|\catcitationbefskip| \DescribeMacro{\catcitationbefskip}
% The distance to skip prior to beginning a |catcitations|
% environment, before running |\catcitetitle|.
% \vitem|\catcitationaftskip| \DescribeMacro{\catcitationaftskip}
% The distance to skip after ending a |catcitations|
% environment.
%	\vitem|\catciteindent| \DescribeMacro{\catciteindent} The
%	indentation of the first line of the citation itself
%	(that is, the quotation) in a |\catcite|.  By default,
%	|0em|.
% \vitem|\catcitehindent| \DescribeMacro{\catcitehindent}
% The indentation of subsequent lines in the citation itself
% (that is, the quotation) in a |\catcite|.  By default,
% |0em|.
% \vitem|\catcitesty| \DescribeMacro{\catcitesty} The style
% in which the citation itself (that is, the quotation) will
% be printed in |\catcite|.  By default, |\itshape|.
%	\vitem|\catsrcindent| \DescribeMacro{\catsrcindent} The
%	indentation of the first line of the source
%	in a |\catcite|.  By default, |2em|.
% \vitem|\catsrchindent| \DescribeMacro{\catsrchindent}
% The indentation of subsequent lines in the source
% in a |\catcite|.  By default, |2em|.
% \vitem|\catsrcsty| \DescribeMacro{\catsrcsty} The style in
% which the source will be printed in |\catcite|.  By
% default, empty.
% \end{description}
%
% Finally, the list settings are all from |paralist|, so
% that package's documentation should be consulted for
% changing the defaults set up for them.
%
% These options are sufficient to manipulate |catechis|
% into behaving however you'd like.
%
% \section{Implementation}
%
% Start by requiring |paralist|, to take care of our custom
% enumerates.
%    \begin{macrocode}
\RequirePackage{paralist}
	\setdefaultenum{(a)}{(1)}{(i)}{(A)}
	\setdefaultleftmargin{3.8em}{}{}{}{}{}
%    \end{macrocode}
% Now we create the indentations and styles for the default
% question counter, the questions themselves, and the
% answers.  We also set sensible defaults.
%    \begin{macrocode}
\newlength{\catquesindent}\setlength{\catquesindent}{0em}
\newlength{\catqueshindent}\setlength{\catqueshindent}{2em}
\newlength{\catansindent}\setlength{\catansindent}{2em}
\newlength{\catanshindent}\setlength{\catanshindent}{2em}
\newlength{\catquesnumwd}\setlength{\catquesnumwd}{2em}
\newcounter{catquesnum}\setcounter{catquesnum}{0}
\def\catquesnumsty{\bfseries}
\def\catquessty{\bfseries}
\def\catanssty{}
\renewcommand{\thecatquesnum}{\arabic{catquesnum}.}
%    \end{macrocode}
% Here, we define the catechism question macro.  Nothing
% much surprising here.
%    \begin{macrocode}
\def\catques#1#2{%
	\stepcounter{catquesnum}%
	\def\@currentlabel{\thecatquesnum}%
	{\parindent=\catquesindent\hangindent=\catqueshindent\hangafter=1%
	{\par\leavevmode\hbox to\catquesnumwd{\catquesnumsty\thecatquesnum\hfil}%
		\catquessty #1}\par\nobreak}%
	{\parindent=\catansindent\hangindent=\catanshindent\hangafter=1%
		{\par\catanssty #2}\par}%
}%
%    \end{macrocode}
% Define the catechism comments, and set sensible defaults
% for the settings.
%    \begin{macrocode}
\def\catcommsty{}
\newlength{\commindent}\setlength{\commindent}{2em}
\newlength{\commhindent}\setlength{\commhindent}{2em}
\def\catcomment#1{%
	{\parindent=\commindent\hangindent=\commhindent\hangafter=1%
	{\par\catcommsty #1}\par}
}%
%    \end{macrocode}
% Define the catechism explications (longer than comments,
% allowing paragraph breaks), and set sensible defaults for
% their settings.
%    \begin{macrocode}
\def\catexplicsty{\small}
\newlength{\explicindent}\setlength{\explicindent}{4em}
\newlength{\explichindent}\setlength{\explichindent}{2em}
\long\def\catexplic#1{%
	{\par\everypar={\parindent=\explicindent\hangindent=\explichindent\hangafter=1}%
	{\par\catexplicsty\  #1}\par}%
}%
%    \end{macrocode}
% Because lists always seem to run roughshod over
% indentation settings, and because it's easier to do this
% than to write custom lists just for this package, we
% define |\restoreindents| to fix settings after a list in a
% |\catexplic|.
%    \begin{macrocode}
\def\restoreindents{%
	\par%
	\everypar={%
		\parindent=\explicindent%
		\hangindent=\explichindent%
		\hangafter=1%
	}%
	\par%
}%
%    \end{macrocode}
% Define the commands to produce citation titles, and set
% sensible defaults; also for the citation environment.
%    \begin{macrocode}
\def\catcitetitlesty{\Large\scshape}%
\def\catcitetitleword{Citations}%
\def\catcitetitle{%
	\hbox to\linewidth{%
		\hfil%
		{\catcitetitlesty\catcitetitleword}%
		\hfil%
	}%
	\penalty10000%
}%
\newlength\catcitationbefskip\catcitationbefskip=1em%
\newlength\catcitationaftskip\catcitationaftskip=1em%
\def\catcitations{%
	\leavevmode%
	\vskip\catcitationbefskip%
	\catcitetitle%
}%
\def\endcatcitations{%
	\leavevmode%
	\vskip\catcitationaftskip%
}%
%    \end{macrocode}
% Define actual citations macros and lengths.
%    \begin{macrocode}
\def\catcitesty{\itshape}%
\def\catsrcsty{}%
\newlength{\catciteindent}\setlength{\catciteindent}{0em}%
\newlength{\catcitehindent}\setlength{\catcitehindent}{0em}%
\newlength{\catsrcindent}\setlength{\catsrcindent}{2em}%
\newlength{\catsrchindent}\setlength{\catsrchindent}{2em}%
\def\catcite#1#2{%
	{\parindent=\catciteindent\hangindent=\catcitehindent\hangafter=1%
		{\par\catcitesty #1}\par}%
	\penalty10000%
	{\parindent=\catsrcindent\hangindent=\catsrchindent\hangafter=1%
		{\par\catsrcsty#2}\par}%
}%
\let\scripture=\catcite
%    \end{macrocode}
%
% And that's it.  Happy \TeX{}ing!
%
% \PrintIndex