summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ssqquote/ssqquote.dtx
blob: 828f69dbd23e4970b60d67e680639d8281be2c0b (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
% \CheckSum{169}
%% \CharacterTable
%%  {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
%%   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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
%
% \changes{1.0} {1994/05/02}{initial version}
% \changes{1.1} {1994/05/06}{corrected wording of example quotations}
% \changes{1.1a}{1994/05/10}{revised documentation}
% \changes{1.1b}{1994/05/12}{revised documentation}
% \changes{1.1c}{1994/05/16}{fixed typo in example quotations}
% \changes{1.1d}{1994/05/18}{revised documentation}
% \changes{1.2} {1994/05/21}{clean-up for public release}
%
%
% \title{The \texttt{ssqquote} Package for \LaTeXe}
%
% \author{Copyright (C) 1994 by Ulrik Vieth}
%
% \maketitle
% ^^A\tableofcontents
%
% \def\file#1{\texttt{#1}}
% \def\book#1{\textit{#1}}
% \def\Lcs#1{\texttt{\bslash{}#1}}
%
% \def\NFSS{\textsf{NFSS}\@}
% \def\DOCSTRIP{\textsc{Docstrip}\@}
%
%
% \section{Introduction}
%
%    This contributed package for \LaTeXe{} provides the necessary
%    font declarations needed to access the \file{cmssq} font family,
%    i.e.~Computer Modern Sans Serif Quotation Style,
%    in terms of \NFSS.^^A
%    \footnote{Throughout this document, the term \NFSS{} should be
%       understood to refer to release~2 of \NFSS, i.e.~the release
%       that's part of \LaTeXe{} and that's intended to become part
%       of \LaTeX3 in the future.}
%    It also provides a little example package file that shows how
%    to define some appropriate font changing commands.
%
%    \DescribeMacro{\ssqfamily}
%    \DescribeMacro{\textssq}
%    Once you have installed the font definition files
%    \file{OT1cmssq.fd} and \file{T1cmssq.fd} provided here, you
%    can use low-level \NFSS{} commands to access the \file{cmssq}
%    font family in your documents, even if you do not plan to use
%    the example package \file{ssqquote.sty}. Apart from defining
%    the font changing commands |\ssqfamily| and |\textssq|, that
%    package file also provides an example application that uses 
%    the \file{cmssq} font family.
%
%    \DescribeEnv{chapterquotes}
%    The |chapterquotes| environment provided as an example is based
%    on ideas used in the |\endchapter| macro of the \file{manmac}
%    format that was used by DEK in the \TeX{} and \MF{} manuals.
%    Its purpose is to typeset a few nice quotations at the end
%    of chapters using the \file{cmssq} font family in a smaller
%    typesize than the regular text. While keeping the distinctive
%    ragged-left formatting from the |\endchapter| macro, we have 
%    tried to make the |chapterquotes| environment more flexible, 
%    optionally allowing quotations to be placed at the top of the 
%    next page if there isn't enough room left at the bottom of the 
%    current page.
%
% \StopEventually{}
%
%
% \section{The \DOCSTRIP{} modules}
%
%    The following \DOCSTRIP{} modules are used in this package:
%    \begin{quote}
%    \begin{tabular}{ll}
%    |driver|      & produces the documentation driver\\
%    |package|     & produces the example package file\\
%    |OT1cmssq|    & produces the font definition file for the OT1 encoding\\
%    |T1cmssq|     & produces the font definition file for the T1 encoding
%    \end{tabular}
%    \end{quote}
%
%    \noindent
%    Except for the documentation driver every module intended
%    for \TeX{} should contain the following information for
%    identification purposes.
%    \begin{macrocode}
%<*package|OT1cmssq|T1cmssq>
\def\filename{ssqquote.dtx}
\def\filedate{1994/05/21}
\def\fileversion{1.2}
%</package|OT1cmssq|T1cmssq>
%    \end{macrocode}
%
%
% \section[The font defintion files:
%          \file{OT1cmssq.fd} and \file{T1cmssq.fd}]
%         {The font defintion files:\\
%          \file{OT1cmssq.fd} and \file{T1cmssq.fd}}
%
%    Following the tradition of the standard \LaTeXe{} distribution,
%    we begin by identifying the latest version of these files in
%    the \file{log} file.
%    \begin{macrocode}
%<*OT1cmssq|T1cmssq>
\wlog{Fontdef\space file\space produced\space from\string:\space
  \string`ssqquote.dtx\string'\space \fileversion\space
  \string<\filedate\string>\space \string(Ulrik Vieth\string)}
%</OT1cmssq|T1cmssq>
%    \end{macrocode}
%
% \subsection{The font definition file for the OT1 encoding}
%
%    First, we will consider the font definition file for the old
%    encoding scheme~OT1 of the original Computer Modern Fonts
%    by DEK. We start by declaring the font family \file{cmssq}.
%    \begin{macrocode}
%<*OT1cmssq>
\DeclareFontFamily{OT1}{cmssq}{}
%    \end{macrocode}
%
%    The fonts \file{cmssq} and \file{cmssqi} are only available
%    in 8-point design size. Therefore, we will make them available
%    only in rather unusual sizes based on magsteps of~8\,pt. However,
%    in the typical application of typesetting quotations in this
%    font family, you wouldn't want to use large magsteps anyway,
%    thus you needn't really worry about that. If you simply select
%    |\footnotesize|, an appropriate size for quotations will be
%    substituted automatically within the margin of |\fontsubfuzz|
%    allowed by~\NFSS.
%
%    Since the `i' in \file{cmssqi} stands for `inclined' rather
%    than `italics', we allocate it to |\slshape| and add a silent
%    font substitution for |\itshape|. There are no other font
%    shapes currently available in the \file{cmssq} family, and
%    it is very unlikely that there will be any in the future.
%    \begin{macrocode}
\DeclareFontShape{OT1}{cmssq}{m}{n}{
  <8> <8.76> <9.6> <11.52> <13.82> <16.59> <19.91> cmssq8
}{}
\DeclareFontShape{OT1}{cmssq}{m}{sl}{
  <8> <8.76> <9.6> <11.52> <13.82> <16.59> <19.91> cmssqi8
}{}
\DeclareFontShape{OT1}{cmssq}{m}{it}{
  <-> ssub * cmssq/m/sl
}{}
%</OT1cmssq>
%    \end{macrocode}
%
% \subsection{The font definition file for the T1 encoding}
%
%    Next, here are the corresponding font shape declarations for
%    the new encoding scheme~T1 used in the DC~fonts. For some
%    unknown reason, Sans Serif Quotation Style was not supported
%    in the original version~1.0 of the DC~fonts. Support for this
%    style was added only in version~1.1, which was completed in 
%    March~1992 but not released on CTAN before February~1994.
%    However, the fonts \file{dcssq} and \file{dcssqi} are still
%    commented out in the configuration file \file{dcstdedt.tex},
%    thus you will not have them if you simply installed the
%    DC~fonts using the standard setup, but you can create them
%    if you like. In any case we will provide the font defintion
%    file here.
%    \begin{macrocode}
%<*T1cmssq>
\DeclareFontFamily{T1}{cmssq}{}
%    \end{macrocode}
%
%    In the T1 encoding, we will use the same magsteps as in the OT1
%    encoding. Using the scaling mechanism built into the DC fonts,
%    it would be possible to create different design sizes as well,
%    but providing a different choice of sizes in the OT1 and T1
%    encodings would only cause confusion. Therefore, we prefer to 
%    live with an unusual range of sizes in both cases.
%    \begin{macrocode}
\DeclareFontShape{T1}{cmssq}{m}{n}{
  <8> <8.76> <9.6> <11.52> <13.82> <16.59> <19.91> dcssq8
}{}
\DeclareFontShape{T1}{cmssq}{m}{sl}{
  <8> <8.76> <9.6> <11.52> <13.82> <16.59> <19.91> dcssqi8
}{}
\DeclareFontShape{T1}{cmssq}{m}{it}{
  <-> ssub * cmssq/m/sl
}{}
%</T1cmssq>
%    \end{macrocode}
%
%
% \section{The package file: \file{ssqquote.sty}}
%
%    After having discussed the font definition files, we now turn
%    to the example package that shows how to access the \file{cmssq}
%    font family using low-level \NFSS{} commands.
%
%    As usual, we begin by identifying the package and its current
%    version.
%    \begin{macrocode}
%<*package>
\ProvidesPackage{ssqquote}[\filedate\space\fileversion\space
                           Contributed LaTeX2e package]
\typeout{Package: `ssqquote'
  \fileversion\space <\filedate> (Ulrik Vieth)}
%    \end{macrocode}
%
% \subsection{Accessing the \file{cmssq} font family in \NFSS}
%
% \begin{macro}{\ssqfamily}
%    First, we define the declarative font changing command |\ssqfamily|.
%    This is accomplished using the low-level \NFSS{} commands
%    |\fontencoding| and |\fontfamily| followed by |\selectfont|.
%    We assume that |\encodingdefault| is set to either OT1 or~T1.
%    Otherwise, you'll probably get an \NFSS{} error message.
%    \begin{macrocode}
\def\ssqfamily{%
  \fontencoding{\encodingdefault}\fontfamily{cmssq}\selectfont}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\textssq}
%    Next, we define a font changing command with one argument. Since
%    it is very unlikely that the \file{cmssq} font will be used in
%    math mode, we do not attempt to make a robust version, instead
%    the |\textssq| macro defined here simply selects |\ssqfamily| 
%    within a group. However, we will protect it, so that it can be
%    used within moving arguments without problems.
%    \begin{macrocode}
\def\textssq{\protect\ptextssq}
\def\ptextssq#1{{\ssqfamily #1}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{An example application:
%             The \texttt{chapterquotes} environment}
%
%    As an example application, we will define a |chapterquotes|
%    environment that is based on ideas used in the |\endchapter|
%    macro of the \file{manmac} format that was used in the \TeX{}
%    and \MF{} manuals. We have tried to make it more \LaTeX-like
%    and we have added some switches and parameters to customize its
%    behaviour. The purpose of this environment is to typeset a few
%    nice quotations at the end of chapters using the \file{cmssq}
%    font family.
%
% \begin{macro}{\ifbottomquotes}
%    We begin by defining a |\newif| that controls whether quotations
%    should always be placed at the bottom or if they are allowed to
%    appear at the top of the next page in case there isn't enough room
%    at the bottom of the current page. By default, |\ifbottomquotes|
%    is set to false.
%    \begin{macrocode}
\newif\ifbottomquotes \bottomquotesfalse
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\prechapterquotes}
%    Next, we allocate a |\newskip| that controls the minimum amount
%    of space that should be left over on the current page when
%    the |chapterquotes| environment is called. More precisely,
%    |\prechapterquotes| is the amount of stretchable glue inserted
%    in an attempt to eject the current page before starting to
%    typeset the quotations. The default value of |\prechapterquotes|
%    is |10\baselineskip| in |\footnotesize|. If you have longer
%    quotations, you may wish to enlarge this parameter.^^A
%    \footnote{By the way, the name of the \Lcs{prechapterquotes}
%       parameter was inspired by the \Lcs{premulticols} parameter
%       in Frank Mittelbach's \file{multicol} package.}
%    \begin{macrocode}
\newskip\prechapterquotes
{\footnotesize \global\prechapterquotes=10\baselineskip\relax}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{chapterquotes}
%    Now, we are ready to discuss the |chapterquotes| environment
%    itself. We begin by leaving horizontal mode if we are not
%    already in vertical mode at the time when |chapterquotes|
%    is called.
%    \begin{macrocode}
\newenvironment{chapterquotes}{%
  \ifvmode \else \unskip\par \fi
%    \end{macrocode}
%
%    Next, we try to eject the current page by inserting an amount
%    of stretchable glue controlled by |\prechapterquotes|, followed
%    by the negative penalty |\@secpenalty|, followed by negative
%    stretchable glue to compensate the positive stretchable glue
%    in case the negative penalty fails to eject the page. If a
%    page break occurs, the last glue will disappear at the top
%    of the page.
%    \begin{macrocode}
  \vskip\z@\@plus+\prechapterquotes
  \penalty\@secpenalty
  \vskip\z@\@plus-\prechapterquotes
%    \end{macrocode}
%
%    After these preliminaries we come to the central part of the
%    |chapterquotes| environment. If quotations are allowed only
%    at the bottom of the page, we insert an empty hbox to prevent
%    glue from disappearing at the top, followed by |\vfill|.
%
%    We disallow floats at the bottom by setting |\@botnum| to zero.
%    In case quotations are allowed at the top as well, we also set
%    |\@topnum| to zero because we do not know where the quotations
%    will end up. If this causes problems with floats that are left
%    over at the end of the chapter, inserting a |\clearpage| before 
%    the |chapterquotes| environment might help. 
%    \begin{macrocode}
  \ifbottomquotes \null \fi \vfill
  \global\@botnum\z@
  \ifbottomquotes \else \global\@topnum\z@ \fi
%    \end{macrocode}
%
%    Now, we start a group to keep changes local. We switch to
%    |\footnotesize| and select the \file{cmssq} font family
%    using the declarative font changing command |\ssqfamily|.
%    \begin{macrocode}
  \begingroup
    \footnotesize \ssqfamily
%    \end{macrocode}
%
%    We redefine |\bigskipskipamount|, |\medskipamount| and
%    |\smallskipamount| using multiples of |\baselineskip|
%    in |\footnotesize|. We will use these paramters for the
%    spacing in between multiple quotations.
%    \begin{macrocode}
    \bigskipamount=1.0\baselineskip
    \medskipamount=0.5\baselineskip
    \smallskipamount=0.25\baselineskip
%    \end{macrocode}
%
%    Within the group started above, we set |\interlinepenalty|
%    to~10000 to disallow page breaks between quotations. Next,
%    we set up various parameters for ragged-left typesetting.
%    \begin{macrocode}
    \interlinepenalty\@M
    \parindent\z@ \parskip\z@ \parfillskip\z@
    \leftskip\z@\@plus\linewidth \rightskip\z@
%    \end{macrocode}
%
%    We redefine |\par| in order to insert the italics correction
%    automatically at the end of lines and activate |\obeylines|,
%    which means that |\par| is added automatically at the end of
%    every input line. In \LaTeX, we can use |\@@par| to refer to
%    the original meaning of |\par|. Alternatively, we could use
%    |\endgraf| here instead.
%    \begin{macrocode}
    \def\par{\ifhmode\/\@@par\fi} \obeylines
%    \end{macrocode}
% \end{environment} 
%
% \begin{macro}{\nextquote}
%    Individual quotations should start with |\nextquote|. This will
%    insert a |\bigskip| and switch to |\slshape| using the \file{cmssq}
%    family selected earlier at the beginning of the environment.
%    Users might regard |\nextquote| as a special case of |\item|
%    that is only available within the |chapterquotes| environment.
%    However, technically speaking, |\item| is quite different from
%    |\nextquote| and much more complicated.
%    \begin{macrocode}
    \def\nextquote{\bigskip\slshape}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\author}
% \begin{macro}{\title}
%    The source of a quotation can be formatted using the macros
%    |\author| and |\title|. The |\author| macro expects two
%    arguments which will be typeset in upright shape. The first
%    one is meant to be the name of the author or the work that
%    is quoted, while the second one (enclosed in parantheses) is
%    meant to be the date of the quotation. Within the arguments
%    of the |\author| macro, the |\title| macro can be used to
%    typeset the title of the quoted work in slanted shape. We use
%    |\textsl| here, i.e.~the font switching macro with one argument,
%    because this will automatically insert the italics correction
%    if necessary.
%    \begin{macrocode}
    \def\author##1(##2){\medskip\upshape\noindent
      --- \ignorespaces ##1 \unskip\thinspace (##2)\par}
    \def\title##1{\textsl{##1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%    At the end of the |chapterquotes| environment, there is not much
%    left to do. We simply close the group started at the beginning
%    of the environment to restore the paragraphing parameters.
%    In case quotations are placed at the top of the page, we insert
%    |\vfil| to avoid an underfull page. If quotations are placed at
%    the bottom, the |\vfill| at the top is infinitely larger than
%    the |\vfil| at the bottom, thus the last |\vfil| won't have any
%    effect. The very last thing to do is to call a |\pagebreak|.
%    \begin{macrocode}
  }{%
  \endgroup
  \vfil \pagebreak}
%</package>
%    \end{macrocode}
%
%
% \section{The documentation driver file}
%
%    We have our own document class to format the \LaTeXe{}
%    documentation. We also use the \file{mflogo} package
%    that defines the \MF{} logo in terms of a \NFSS{} font
%    family and the \file{ssqquote} package to typeset some
%    example quotations at the end of this file.
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}
\usepackage{mflogo}
\usepackage{ssqquote}
%    \end{macrocode}
%    We do not need an index.
%    \begin{macrocode}
\DisableCrossrefs
%    \end{macrocode}
%    We do want the full details.
%    \begin{macrocode}
\begin{document}
\DocInput{ssqquote.dtx}
% \PrintIndex
% \PrintChanges
\end{document}
%</driver>
%    \end{macrocode}
%
%
% \section{An example of the \texttt{chapterquotes} environment}
%
%    Finally, here's an example of the |chapterquotes| environment
%    and how it was specified. Note that line breaks in the input
%    file are obeyed, thus when long input lines have to be broken
%    across lines, the end of the line has to be commented out.
%    If a quotation consists of multiple paragraphs, |\smallskip|
%    can be used to insert space in between them. As explained
%    earlier, |\medskip| is inserted by the |\author| macro and 
%    |\bigskip| is inserted by |\nextquote|.
%    \begin{macrocode}
%<*example>
\begin{chapterquotes}
   \nextquote
   I've finally learned what `backwards compatibility' means:
   It means we've got to keep all our old mistakes.

   \author RAINER SCH\"OPF, \title{\LaTeXe{} Announcement} (TUG `1993)

   \nextquote
   \emph{Compatibility:} \LaTeXe{} will, as far as possible,
   adhere to the following principles:
   \smallskip
   1. Unmodified version 2.09 document files will produce
      the same output with \LaTeXe{} as with version 2.09.
   \smallskip
   2. All new features will conform to the conventions
      of version 2.09 \dots

   \author \LaTeX3 PROJECT, %
      \title{\LaTeXe{} -- A new version of \LaTeX{}} (TTN~2;4, 1993)
\end{chapterquotes}
%</example>
%    \end{macrocode}
%
% \begin{chapterquotes}
%    \nextquote
%    I've finally learned what `backwards compatibility' means:
%    It means we've got to keep all our old mistakes.
%
%    \author RAINER SCH\"OPF, \title{\LaTeXe{} Announcement} (TUG `1993)
%
%    \nextquote
%    \emph{Compatibility:} \LaTeXe{} will, as far as possible,
%    adhere to the following principles:
%    \smallskip
%    1. Unmodified version 2.09 document files will produce
%       the same output with \LaTeXe{} as with version 2.09.
%    \smallskip
%    2. All new features will conform to the conventions 
%       of version 2.09 \dots
%
%    \author \LaTeX3 PROJECT, ^^A
%       \title{\LaTeXe{} -- A new version of \LaTeX{}} (TTN~2;4, 1993)
%
%    \nextquote
%    \emph{I didn't change anything!} An aggrieved cry often heard
%    as bugs manifest during a regression test \dots
%    \smallskip
%    This is also heard from applications programmers
%    trying to blame an obvious applications problem
%    on an unrelated systems software change \dots
%    \smallskip
%    Usually, their statement is found to be false.
%    Upon close questioning, they will admit
%    some major restructuring of the program
%    that shouldn't have broken anything, in their opinion,
%    but which hosed the code completely.
%
%    \author THE NEW HACKER'S DICTIONARY (1993)
% \end{chapterquotes}
%
% \Finale
%
\endinput