summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/csquotes/tutorial.tex
blob: 2ccbfed2614c0da4cdc68696676188fa903433fa (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
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
% $Id: tutorial.tex,v 3.6 2006/11/09 21:55:06 lehman stable $
%
% This tutorial will give you an introduction to the csquotes package by way of
% example. All the instructions are included as comments in this file. There is
% nothing fancy to see in the typeset version of this file but you should
% compare the document source to the typeset result while reading this
% tutorial to see what the commands do.
%
% Note that this file uses ISO-8859-1 (Latin 1) encoding.
% Please adjust your text editor as required.

\documentclass[a4paper]{article}

% We're using 8-bit input and T1 encoded fonts for proper output:
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}

% In order to demonstrate babel support we load the babel package:
\usepackage[french,german,portuguese,american]{babel}

% We load csquotes with the `babel' option. The csquotes package works just
% fine without babel, but it will support multilingual typesetting if babel
% has been loaded.
\usepackage[babel]{csquotes}

% In this tutorial, we'll make use of a few active quotes. They will be
% discussed in greater detail below. Active quotes are defined in the document
% preamble or the configuration file.

% The first two are obvious choices:
\MakeOuterQuote{"}
\MakeAutoQuote{«}{»}
% The next one is more or less evident as well:
\MakeBlockQuote{<}{|}{>}

% In general, an active quote must be a single character with category code 12
% or 13 (or a valid UTF-8 sequence representing a single character, if you are
% using UTF-8 encoding). The csquotes package will automatically check all
% characters for validity as you allocate them with a command like
% \MakeOuterQuote. Apart from characters which are not suitable because of
% their category code, csquotes will also reject numbers, punctuation marks,
% the apostrophe, and all characters which are part of LaTeX's syntax or
% reserved for a specific purpose (such as '*', '[', ']', '~'). If you are
% unsure, there is no harm in trying. If a character you choose is unsuitable,
% csquotes will issue an error message.

% Some additional packages used or discussed in this tutorial:
\usepackage[noadjust]{cite}
\usepackage{relsize}

% Some generic settings:
\setcounter{secnumdepth}{1}
\pagestyle{empty}
\frenchspacing
\raggedbottom

\makeatletter
\renewcommand{\@makefntext}[1]{%
  \@hangfrom{\makebox[0.5em][r]{\@thefnmark}%
             \hspace{1em}}%
  #1}
\makeatother

\newcommand*{\example}[1]{%
  \addvspace{\baselineskip}%
  \par\noindent\hspace{-4em}%
  \makebox[3em][r]{\textbf{Ex. #1}}%
  \hspace{1em}\ignorespaces}

% Let's go
\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% We include a short note to anyone looking at the typeset file first:

\noindent This is the typeset version of \texttt{\jobname.tex}. There is
nothing fancy to see here. The tutorial you are looking for consists of a
series of comments which are included in the source.

\clearpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Basic quotations}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Csquotes is able to interface with the babel package. To demonstrate that,
% we will occasionally change the document language. We start off with American
% English:

\selectlanguage{american}

\subsection{\languagename}

% Getting started is simple: just load the package and use the command \enquote
% to enclose a piece of text in quotation marks:

\example{1} \enquote{outer quote \enquote{inner quote} outer quote}

% \enquote can detect nested quotations. It will toggle between outer and inner
% quotation marks depending on the nesting level. There is also a starred
% version of this command which jumps to the inner level right away:

\example{2} \enquote*{inner quote}

% The csquotes package supports two markup styles for quotations: control
% sequences and active characters. An active character is a single character
% functioning as a control sequence. Think of them as `smart quotes' done
% right. The active characters are defined in the document preamble or in the
% configuration file. There are several commands which make that a trivial
% task:
%
% \MakeOuterQuote{<character>}
% \MakeInnerQuote{<character>}
% \MakeAutoQuote{<first character>}{<second character>}
%
% \MakeOuterQuote and \MakeInnerQuote set up active characters which typeset
% outer or inner quotation marks respectively.
%
% Preamble: \MakeOuterQuote{"}

\example{3} "outer quote"

% Using the straight Ascii quote as an active quote is tempting. However, note
% that this may cause problems because it is used as an active character by
% several language extensions of the babel package. It will conflict with the
% following language extensions:
%
% Basque, Bulgarian, Catalan, Danish, Dutch, Estonian, Finnish, Galician,
% German, Greek, Icelandic, Italian, Latin, Norwegian, Polish, Portuguese,
% Russian, Serbian, Slovenian, Spanish, Swedish, Ukrainian, Upper Sorbian.
%
% Looks like a long list? It certainly is. But then again, you could use it in
% conjunction with the English or the French extensions. More hints concerning
% active characters will be given below, so make sure you read the entire
% tutorial.
%
% \MakeAutoQuote sets up two active characters that toggle between outer and
% inner quotation marks like the \enquote command. You need two distinct
% characters in this case.
%
% Preamble: \MakeAutoQuote{«}{»}

\example{4} «outer quote «inner quote» outer quote»

% Since the control sequences and active quotes of csquotes are essentially
% different frontends to a common backend, you may also mix them:

\example{5} \enquote{outer quote «inner quote» outer quote}

\example{6} "outer quote \enquote{inner quote} outer quote"

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% We're switching languages:

\selectlanguage{french}

\subsection{\languagename}

% Csquotes will detect the change and adjust the quotation marks to the new
% language automatically:

\example{1} les guillemets \enquote{à la française}

% Of course the active quotes will obey the language change as well:

\example{2} les guillemets «à la française»

% A note about French: when using \enquote or active quotes, don't add any
% nonbreakable spaces. Csquotes will space out the guillemets automatically as
% is custom in French. The spacing is similar to what you get when using the
% commands \og and \fg provided by the French extension of the babel package.
% This feature is not hard-coded, it is part of the quote styles for French and
% could be modified if desired.

\example{3} les guillemets \og à la française\fg

\example{4} les guillemets "à la française"

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% We're switching languages once again:

\selectlanguage{german}

\subsection{\languagename}

% ... and csquotes will adjust the quotation marks as well:

\example{1} «Zitat «Zitat im Zitat» Zitat»

% Before we continue with the multilingual capabilities of csquotes, a few
% general notes concerning active quotes are in order.

% Like the quotation commands provided by csquotes, the active quotes are
% fully-fledged markup elements which allow for basic validation of the
% document structure. They differ substantially from the quote commands
% provided by the babel package. Conceptually, the latter are input aids.
% Babel's German extension, for example, provides the command \glqq and the
% shorthand "` to typset the opening quotation mark used in German:

\example{2} \glqq Zitat\grqq\ "`Zitat"'

% The shorthand "` is more convenient than something like \quotedblbase, but
% it's not different in concept. If you get the shorthands wrong by mixing up
% "` and "', TeX will happily typeset the wrong quotation marks without giving
% any warning:

\example{3} "'Zitat"`

% If you get the active quotes of this package wrong, TeX will bail out with an
% error message drawing you attention to the problem. This package tracks the
% nesting level of all quotations and issues an error message if they are
% nested in an invalid way. It also employs grouping to make sure that a
% quotation opened with an active quote is also closed properly. All active
% quotes have essentially the same effect as { and } or \begingroup and
% \endgroup. This means that active quotes must always be properly balanced and
% nested.
%
% Some grouping mistakes may trigger a generic TeX error. Note that packages
% cannot catch low-level errors caused by grouping mistakes, nor do they have
% any control over the wording of generic error messages. Error messages like:
%
%    ! Missing } inserted.
% or
%    ! Too many }'s.
%
% could be caused by unbalanced quotes or by intersecting groups. In some
% cases, all a package can do is make sure that there will be *some* kind of
% error message. Bear this in mind when tracking down the cause of such
% seemingly cryptical errors. When running under e-TeX, this package will
% generally catch more errors and print a specific error message instead.

% When defining active quotes, make sure that they don't conflict with other
% packages. Several language extensions of the babel package use the Ascii
% double quote as a shorthand for diacritics and special hyphenation points.
% When switching to one of these languages with \selectlanguage (or any
% command/environment activating babel's specials locally), babel will
% overwrite the definitions set up by csquotes:

\selectlanguage{german}

\example{4} "a "o "u "i

% You can reclaim active quotes after their definitions have been overwritten
% by another package with \EnableQuotes. This command will replay the
% definitions of all active quotes recorded in the configuration file and the
% preamble. Note that it doesn't make sense to use \EnableQuotes in the
% preamble because a lot of packages (including csquotes) defer the activation
% of such characters until \begin{document}.

\EnableQuotes

\example{5} "Zitat"

% Use \EnableQuotes with care as you may break other packages by reclaiming
% active quotes. Even if things don't break outright, you might loose
% functionality. With babel's German extension, for example, you can do without
% the " shorthand as far as diacritics and (babel's) quotes are concerned when
% using inputenc and csquotes. But sooner or later you might still need it to
% mark special hyphenation points.

% Unfortunately, the choice of " as shorthand is hard-coded into babel. All you
% can do is work around the conflict by using babel's \aliasshorthand to define
% an alternative shorthand. This is accomplished by putting something like the
% following right after \begin{document}:
%
% \addto\extrasgerman{%
%   \aliasshorthand{"}{|}%
%   \EnableQuotes}
%
% \selectlanguage{german}
%
% This will define the additional shorthand | which you may use instead of "
% for babel's shorthands. It will then reclaim " as an active quote. If you use
% several languages in your document, this step is required for every language
% using the " shorthand. The change will take effect after \selectlanguage or
% an equivalent command is given.

% The above might be acceptable as a one-time workaround, but it is not really
% advisable as a general solution. Since the choice of active quotes is up to
% you, it is a good idea to choose characters which are not used by any other
% package in the first place. If you are using an input encoding like Latin 1
% or Latin 9 anyway, I recommend using 8-bit characters as active quotes. Such
% characters will not conflict with other packages since they have to make do
% with Ascii for hard-wired active characters. The left and right guillemets
% («») used as an example here are particularly well suited for this purpose.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\selectlanguage{portuguese}

\subsection{\languagename}

% Quote styles for some of the languages covered by babel are still missing
% simply because I'm not familiar with the respective language and nobody has
% contributed a suitable style yet. In this case, csquotes will typeset bold
% question marks and issue a warning:

\example{1} «citação»

% You can easily add support for your language or change a predefined style.
% All you need to do is add a declaration to the configuration file,
% csquotes.cfg. Detailed instructions concerning this are included in the
% manual. The configuration file also includes some example styles.

\selectlanguage{american}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Foreign language quotations}

% In the following, we will have a closer look at the multilingual capabilities
% of csquotes. First of all, we're changing the default language:

\selectlanguage{german}

\example{1} «Zitat in der Standardsprache.» % "quote in the default language"

% Babel offers environments for changing the language locally. This works just
% fine with csquotes:

\begin{otherlanguage*}{american}

\example{2} «This is a quote in a different language.»

\end{otherlanguage*}

% Babel's `hyphenrules' environment merely switches hyphenation patterns but
% does not affect the typesetting in any other way. Consequently, csquotes will
% not change the quotation mark style within this environment either:

\begin{hyphenrules}{american}

\example{3} «quote snippet in a different language»

\end{hyphenrules}

% Babel also features the command \foreignlanguage which changes the language
% for a foreign phrase embedded in the text body. This command corresponds to
% the `otherlanguage*' environment. Csquotes provides a command which combines
% the features of \foreignlanguage and \enquote:

\example{4} \foreignquote{american}{This is a quote in a different language.}

% In addition to that, csquotes provides an inline substitute for the
% `hyphenrules' environment which changes the hyphenation rules used within the
% quotation without adapting the quotation mark style:

\example{5} \hyphenquote{american}{quote snippet in a different language}

% Since the syntax of these commands is somewhat verbose you might want to
% build your own, shorter commands on top of them. Note that all \foreign...
% and \hyphen... commands take the language as their first argument, hence you
% can easily include the language in your own commands if you like:
%
% \newcommand*{\usquot}{\foreignquote{american}}
% \newcommand*{\frhyph}{\hyphenquote{french}}
%
% Which would be used as follows:
% 
% \usquote{This is a quote in American English.}
% \frhyph{Voici une citation en français.}
%
% Or you might prefer using active quotes. There are two commands which
% facilitate that:
%
% \MakeForeignQuote{<language>}{<first character>}{<second character>}
% \MakeHyphenQuote{<language>}{<first character>}{<second character>}
%
% For example:
% 
% \MakeForeignQuote{american}{<}{>}
% \MakeHyphenQuote{french}{«}{»}
%
% Which would be used as follows:
% 
% <This is a quote in American English.>
% «Voici une citation en français.»

\EnableQuotes % because \selectlanguage{german} overwrites the " special
\selectlanguage{american}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Formal quotations}

% A common requirement in academic writing demands that quotations be embedded
% in the flow of text if they are short but set off as an indented paragraph, a
% so-called block quotation, if they are longer than a certain number of lines.
% This package provides commands which will determine the number of lines
% required to typeset the quotation and then decide on the format
% automatically.

\example{1}
This is some filler text demonstrating how the quotation is integrated with
the running text. \blockquote{This is a short quotation. Since it's shorter
than three lines it will be embedded in the running text.} This is some filler
text demonstrating how the quotation is integrated with the running text.
\blockquote{This is a long quotation. Since it's longer than three lines it
will be presented as an indented paragraph. By default, the csquotes package
will use the \texttt{quote} environment for block quotations. Both the line
threshold and the block quotation environment may be adapted to your
requirements.} This is some filler text demonstrating how the quotation is
integrated with the running text.

% Formal quotations are always accompanied by a citation indicating the source
% of the quoted text. The citation will usually have a specific format which is
% used consistently throughout the entire text. For example, it might be
% enclosed in parentheses or put in a footnote. Therefore, the block quotation
% facilities take the citation as an optional argument and pass it to an
% auxiliary command called \mkcitation. This command may be redefined to format
% the citation. Here is an example:

\renewcommand{\mkcitation}[1]{ (#1)} % this is the default

\example{2}
This is some filler text demonstrating how the quotation is integrated with
the running text. \blockquote[Citation]{This is a short quotation. Since it's
shorter than three lines it will be embedded in the running text.} This is
some filler text demonstrating how the quotation is integrated with the
running text. \blockquote[Citation]{This is a long quotation. Since it's
longer than three lines it will be presented as an indented paragraph. By
default, the csquotes package will use the \texttt{quote} environment for
block quotations. Both the line threshold and the block quotation environment
may be adapted to your requirements.} This is some filler text demonstrating
how the quotation is integrated with the running text.

% There is another useful command called \ifblockquote which you may use in the
% definition of \mkcitation to present the citation in a way that depends on
% the format of the corresponding quotation:

\renewcommand{\mkcitation}[1]{%
  \ifblockquote{\footnote{#1.}}{ (#1)}}

% If the quotation is embedded in the running text, this definition will behave
% like the one discussed above. If the quotation is presented as a block
% quotation, however, the citation will be given in a footnote.

\example{3}
This is some filler text demonstrating how the quotation is integrated with
the running text. \blockquote[Citation]{This is a short quotation. Since it's
shorter than three lines it will be embedded in the running text.} This is
some filler text demonstrating how the quotation is integrated with the
running text. \blockquote[Citation]{This is a long quotation. Since it's
longer than three lines it will be presented as an indented paragraph. By
default, the csquotes package will use the \texttt{quote} environment for
block quotations. Both the line threshold and the block quotation environment
may be adapted to your requirements.} This is some filler text demonstrating
how the quotation is integrated with the running text.

% You may also want to present a quotation in inline or in display style,
% regardless of its length. That's what the text and display quotation
% facilities are for. Quotations typeset with the text quotation facilities
% look like a `short' quotation, those typeset by means of the display
% quotation facilities look like a `long' quotation. Citations are supported
% as well and will be formated consistently with \mkcitation. \ifblockquote
% will also work as expected in this context.
%
% This is the current definition of \mkcitation:
%
%    \renewcommand{\mkcitation}[1]{%
%      \ifblockquote{\footnote{#1.}}{ (#1)}}
%
% That's what a text quotation ...

\example{4}
This is some filler text demonstrating how the quotation is integrated with
the running text.
\textquote[Citation]{This is a short quotation typeset with a text quotation
command. It would be presented in inline style even if it were longer than
three lines.}
This is some filler text demonstrating how the quotation is integrated with
the running text. 

% ... and a display quotation looks like:

\example{5}
This is some filler text demonstrating how the quotation is integrated with
the running text.
\begin{displayquote}[Citation]
This is a fairly short quotation. Since it is enclosed in a
\texttt{displayquote} environment, however, it is typeset just like a long
one.
\end{displayquote}
This is some filler text demonstrating how the quotation is integrated with
the running text. 

% See the sections entitled "Fine-tuning block/display quotations" and
% "Fine-tuning terminal punctuation" for additional hints.

% For the remaining examples, we restore the default definition:

\renewcommand{\mkcitation}[1]{ (#1)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% If you prefer using active quotes, you may do so with block quotations as
% well. In the preamble we already defined some active quotes including the
% following:
%
% \MakeBlockQuote{<}{|}{>}
%
% These active quotes are used as follows:

\example{5} <quotation>

\example{6} <quotation|citation>

% This is equivalent to:
%
%    \blockquote{quotation}
%    \blockquote[citation]{quotation}
%
% The delimiter | separates the quotation from the citation. If the delimiter
% is not used, the entire piece of text between the opening and the closing
% mark will be treated as quotation text. Note that the marks and the delimiter
% must not be included in the quoted piece of text and the citation. See the
% section entitled "Controlling active quotes" on how to work around this
% limitation.

% Let's go over our verbose example once again, using active quotes this time:

\example{7}
This is some filler text demonstrating how the quotation is integrated with
the running text. <This is a short quotation. Since it's shorter than three
lines it will be embedded in the running text.|Citation> This is some filler
text demonstrating how the quotation is integrated with the running text.
<This is a long quotation. Since it's longer than three lines it will be
presented as an indented paragraph. By default, the csquotes package will use
the \texttt{quote} environment for block quotations. Both the line threshold
and the block quotation environment may be adapted to your
requirements.|Citation> This is some filler text demonstrating how the
quotation is integrated with the running text.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Integrated quotations}

% For every quotation command/environment which takes a citation as an
% argument, there is also a corresponding `integrated' command/environment with
% the letter `c' for `cite' in its name:
%
%    \textquote            \textcquote
%    \foreigntextquote     \foreigntextcquote
%    \hyphentextquote      \hyphentextcquote
%
%    \blockquote           \blockcquote
%    \foreignblockquote    \foreignblockcquote
%    \hyphenblockquote     \hyphenblockcquote
%
%    displayquote          displaycquote
%    foreigndisplayquote   foreigndisplaycquote
%    hyphendisplayquote    hyphendisplaycquote
%
% The integrated quotation facilities differ from their regular counterparts in
% that they integrate automated citations into their syntax. Instead of adding
% \cite manually, you pass the arguments for \cite to the respective quotation
% command. You would normally give a citation like that:

\example{1} \enquote{This is the quotation.} \cite[174]{citekey}

% The commands for formal quotations already take the citation as an argument,
% but using \cite in an optional argument may lead to some rather convoluted
% constructs with multiple nested pairs of brackets and braces:
%
%    \textquote[{\cite[174]{citekey}}]{This is the quotation.}
%
% The integrated quotation facilities allow you to write that in a much more
% readable, sequential way:

\example{2} \textcquote[174]{citekey}{This is the quotation.}

% This works with block quotations as well:

\example{3} \blockcquote[174]{citekey}{This is the quotation.}

% The \cite command will format the citation in a certain way (it is enclosed
% in square brackets by default). Since csquotes' \mkcitation would interfere
% with \cite's formatting, all integrated quotation facilities use \mkccitation
% instead of \mkcitation. The citation arguments are handed over to \cite and
% this entire unit is passed to \mkccitation.
%
% When using citation packages such as cite, natbib, or jurabib, you might want
% to put the format of the citation completely under the control of the
% respective package and have \mkccitation do nothing at all:
%
%    \renewcommand*{\mkccitation}[1]{#1}
%
% Obviously, anything inserted by \cite cannot be removed by \mkccitation.
% Hence you might need additional packages which redefine \cite in order to
% adjust the format of the automated citations. Here's an example using the
% cite package to present the citation in a way that is better suited for the
% author-year citation format:

\renewcommand*{\mkccitation}[1]{ #1} % this is the default (note the space)
\renewcommand*{\citeleft}{(}    % -> cite.sty
\renewcommand*{\citeright}{)}   % -> cite.sty
\renewcommand*{\citemid}{, p.~} % -> cite.sty

\example{4} \textcquote[174]{doe96}{This is the quotation.}

% Of course you may also combine \mkccitation and the features of additional
% citation packages. Depending on the citation package, there may be more than
% one way to achieve a certain result.
%
% Suppose that we wanted to put all citations in a footnote. The jurabib
% package offers a \footcite command which does just that. In this case,
% \mkccitation need not do anything:
%
%    \renewcommand*{\mkccitation}[1]{#1}
%    \SetCiteCommand{\footcite}
%
% With natbib, \mkccitation may take care of the footnote but we still need to
% use an alternative \cite command to get a suitable citation format:
%
%    \renewcommand*{\mkccitation}[1]{\footnote{#1}}
%    \SetCiteCommand{\citealp}
%
% Here's one last example combining \mkccitation with the features of the cite
% package to achieve a similar result. \mkccitation will put the citation in a
% footnote while the cite package is used to format the citation:

\renewcommand*{\mkccitation}[1]{\footnote{#1}}
\SetCiteCommand{\cite}

\renewcommand*{\citeleft}{}
\renewcommand*{\citeright}{.}
\renewcommand*{\citemid}{, p.~}

\example{5} \blockcquote[174]{doe96}{This is the quotation.}

% All of this also works with the text...

\example{6} \textcquote[174]{doe96}{This is the quotation.}

% ...and the display quotation facilities:

\example{7}
This is some filler text.
\begin{displaycquote}[174]{doe96}
This is the quotation.
\end{displaycquote}
This is some filler text.

% The natbib and jurabib packages redefine \cite so that it takes two optional
% arguments. If one of these packages is loaded, all integrated quotation
% facilities will automatically accept this additional argument as well:
%
%    \usepackage{natbib}
%    ...
%    \textcquote[See][174]{doe96}{...}
%
% The citation arguments are handed over to \cite in the order in which they
% were given. How they are interpreted is at the discretion of \cite. With the
% natbib package, the first optional argument is a pre-note. With jurabib, it
% has a different function by default.

% See the section entitled "Fine-tuning terminal punctuation" for additional
% hints.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Miscellaneous hints}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Fine-tuning block/display quotations}

% The most frequent complaint about the traditional `quote' and `quotation'
% environments is that they do not adjust the font size of the quoted text. It
% is very common to set block quotations slightly smaller than the surrounding
% text. This problem is easily remedied:
%
%    \newenvironment{smallquote}
%      {\begin{quote}\small}
%      {\end{quote}}
%
% Because of the way environments are implemented in LaTeX, it is better to
% avoid nesting \begin and \end when including an environment in the definition
% of another one. Another problem with this definition is that \small will
% effectively hard-code the font size. It is advisable to use the \smaller
% command from the relsize package. \smaller will decrease the font size by one
% step (from \normalsize to \small or from \footnotesize to \scriptsize) so
% that this environment will also work as expected when used in a footnote.
%
% Hence our final definition is written as follows:

\newenvironment*{smallquote}
  {\quote\smaller}
  {\endquote}

% Now we instruct csquotes to use the new environment:

\SetBlockEnvironment{smallquote}

\example{1}
This is some filler text. \blockquote{This is a quotation typeset with one of
the block quotation commands of the \texttt{csquotes} package. The block
quotation environment has been modified so that the font size of the quotation
is decreased by one step with respect to the size of the surrounding text.}
This is some filler text.

% All adjustments made by means of \SetBlockEnvironment will automatically
% apply to the `display' environments as well:

\example{2}
This is some filler text.
\begin{displayquote}
This is a quotation typeset with one of the quotation environments of the
\texttt{csquotes} package. Quotations typeset by way of these environments
will behave exactely like a long quotation set with the block quotation
commands.
\end{displayquote}
This is some filler text.

% If you want to use this setup by default, add the following to csquotes.cfg:
%
%    \RequirePackage{relsize}
%
%    \newenvironment{smallquote}
%      {\quote\smaller}
%      {\endquote}
%
%    \SetBlockEnvironment{smallquote}
%
% Of course you could also redefine the original `quote' environment, but keep
% in mind that the `quote' and `quotation' environments are not part of the
% LaTeX kernel. They are defined in the document class. Since any definition
% given in csquotes.cfg should be independent of the document class, it's
% better to build a new environment on top of `quote'.

% For the next examples, we'll switch back to the default:

\SetBlockEnvironment{quote}

% You may have noticed that the first line of text after the quotation is not
% indented in the example above. This is possibly not what you would expect.
% However, this is in fact a feature of the standard `quote' environment which
% is used for long quotations by default. Strictly speaking, it is a feature of
% LaTeX's list environments and both `quote' and `quotation' are implemented as
% lists. If they are part of a paragraph, the first line after the environment
% will not be indented:

\example{3}
This is some filler text.
\begin{quote}
This is a quotation typeset with the standard \texttt{quote} environment. In
the source of this example the environment is part of a paragraph, hence the
first line after the environment is not indented.
\end{quote}
This line is not indented.

% If the environment is separated from the surrounding text by \par or by a
% blank line, the first line after the environment will get regular paragraph
% indentation:

\example{4}
This is some filler text.

\begin{quote}
This is a quotation typeset with the standard \texttt{quote} environment. In
the source of this example the environment is separated from the surrounding
text by blank lines, hence the first line after the environment gets regular
paragraph indentation.
\end{quote}

This line gets regular paragraph indentation.

% Block quotation commands such as \blockquote will usually be integrated in
% the text in the document source since \blockquote may decide to typeset its
% argument inline. When using the `quote' environment for long quotations, this
% implies that the first line after the environment will not get regular
% paragraph indentation:

\example{5}
This is some filler text. \blockquote{This is a quotation typeset with one of
the block quotation commands of the \texttt{csquotes} package. In the source
of this example the quotation is part of a paragraph. By default, the block
quote commands will use the standard \texttt{quote} environment for long
quotations. Therefore, the first line after the block quotation is not
indented.} This line is not indented.

% This behavior is perfectly in line with LaTeX's list environments, but it can
% lead to inconsistencies in the layout. The csquotes package will not insert
% an explicit \par before and after block quotations automatically since you
% might prefer it the other way and suppressing the indentation later on is a
% somewhat tricky thing to do. It is much easier to force indentation after
% paragraph quotations automatically. If you want to force indentation in all
% cases, a suitable environment is easily defined:
%
%    \newenvironment*{paraquote}
%      {\par\begin{quote}}
%      {\end{quote}\par}
%
% As mentioned above, it is better to avoid nesting \begin and \end:

\newenvironment*{paraquote}
  {\begingroup\quote}
  {\endquote\endgroup}

% We instruct csquotes to use the new environment:

\SetBlockEnvironment{paraquote}

% Now all long quotes will be treated as separate paragraphs:

\example{6}
This is some filler text. \blockquote{This is a quotation typeset with one of
the block quotation commands of the \texttt{csquotes} package. In the source
of this example the quotation is also part of a larger paragraph. However, the
block quotation environment has been redefined so that the first line after
the quotation gets regular paragraph indentation.} This line gets regular
paragraph indentation.

% Our `paraquote' environment may also be merged with the `smallquote'
% environment discussed above:
%
%    \newenvironment*{smallparaquote}
%      {\begingroup\quote\smaller}
%      {\endquote\endgroup}
%
%    \SetBlockEnvironment{smallparaquote}

\subsection{Fine-tuning terminal punctuation}

% Style guides often include subtleties such as detailed provisions concerning
% the placement of terminal punctuation. With \blockquote, such provisions can
% complicate matters quite a bit since you don't know in advance how the
% quotation is going to be typeset.
% 
% The csquotes package is designed to cope with as many of these provisions as
% possible. The facilities for formal quotations provide a combination of
% `hooks' and tests which may be used to deal with them automatically. We'll
% consider MLA-style quotations as an example. The APA style uses a different
% citation format (author-year) but is very similar in concept otherwise.

% The MLA style guide demands that quotations of up to four lines be set inline
% and quotations of five or more lines be presented as an indented paragraph.
% The \blockquote command and its various companions can deal with this task
% automatically. The required settings are obvious:

\SetBlockThreshold{4} % the default is 3 lines
\SetBlockEnvironment{quote} % this is the default

% The source of the quotation is indicated in the body by a short citation in
% parentheses. This is what the default definition of \mkcitation already does:

\renewcommand*{\mkcitation}[1]{ (#1)} % this is the default

% What complicates this further is the placement of the terminal punctuation.
% With long quotations, the period is simply placed at the end of the
% quotation. With short quotations, however, the final period is omitted from
% the quotation and placed after the whole unit formed by quotation and
% citation. This can be automated as follows:

\renewcommand*{\mkmidblockpunct}[1]{%
  \ifblockquote{.}{}}

\renewcommand*{\mkfinblockpunct}[1]{%
  \ifblockquote{}{.}}

% Note that both \mkmidblockpunct and \mkfinblockpunct must take one mandatory
% argument, even if it is not used in their definition. We will use it further
% down, though.
%
% Now, when quoting, we simply omit the terminal period:

\example{1}
\blockquote[Doe 174]{This is a short quotation. The terminal period is omitted
from the quotation and inserted automatically}

\blockquote[Doe 174]{This is a long quotation. Apart from this absolutely
pointless filler text (which serves no purpose whatsoever besides making the
quotation exceed the block threshold so that the command used to typeset the
quotation will finally have mercy and present it as an indented paragraph) it
is similar to the short quotation above. The terminal period is also omitted
from the quotation and inserted automatically}

% But what if the quotation ends with a question mark? With short quotations
% there is no problem because the whole unit including the citation should
% still be closed with a terminal period. Therefore, our definition of
% \mkfinblockpunct does not require any adjustments. With long quotations,
% however, this would result in `?.' at the end of the quotation. We need an
% additional test in the definition of \mkmidblockpunct: \ifquotepunct tells
% us if the quotation ends with a punctuation mark. If so, we don't add a
% terminal period to the block quotations:

\renewcommand*{\mkmidblockpunct}[1]{%
  \ifblockquote
    {\ifquotepunct{}{.}}
    {}}

\example{2}
\blockquote[Doe 174]{This is a short quotation ending with a question
mark. You see?}

\blockquote[Doe 174]{This is a long quotation. Apart from this absolutely
pointless filler text (which serves no purpose whatsoever besides making the
quotation exceed the block threshold so that the command used to typeset the
quotation will finally have mercy and present it as an indented paragraph) it
is similar to the short quotation above. It also ends with a question mark.
You see?}

% But it gets even more complicated. What about inline quotations with a
% terminal question mark which is not part of the quotation? For example,
% consider something like the following:
%
%    Is it true, as Epimenides claims, that "all Cretans are liars"?
%
% This might be given as follows in the source document:
%
%    Is it true, as Epimenides claims, that
%    \blockquote[][?]{all Cretans are liars}
%
% Note that the `punctuation' argument is passed to both \mkmidblockpunct and
% \mkfinblockpunct. (But only on of them should actually insert it!) In the
% above definitions of these commands, the argument was simply discarded. Our
% final definitions will subject #1 to an \ifstringblank test to find out if
% the `punctuation' argument is used and handle it in an appropriate way:

\renewcommand*{\mkmidblockpunct}[1]{%
  \ifblockquote
    {\ifstringblank{#1}
       {\ifquotepunct{}{.}}
       {}}
    {}}

\renewcommand*{\mkfinblockpunct}[1]{%
  \ifblockquote
    {\ifstringblank{#1}{}{#1}}
    {\ifstringblank{#1}{.}{#1}}}

\example{3}
\blockquote[Doe 174][?]{This is a short quotation closed with a question mark
which is not part of the quotation itself}

\blockquote[Doe 174][?]{This is a long quotation. Apart from this absolutely
pointless filler text (which serves no purpose whatsoever besides making the
quotation exceed the block threshold so that the command used to typeset the
quotation will finally have mercy and present it as an indented paragraph) it
is similar to the short quotation above. It is closed with a question mark
which is not part of the quotation itself}

% Setting the long quotation this way is not a good idea because it's still
% somewhat ambiguous. Let's make that more explicit:

\renewcommand*{\mkmidblockpunct}[1]{%
  \ifblockquote
    {\ifstringblank{#1}
       {\ifquotepunct{}{.}}
       { [\dots\unkern]\,[#1]}}
    {}}

\renewcommand*{\mkfinblockpunct}[1]{%
  \ifblockquote
    {}
    {\ifstringblank{#1}{.}{#1}}}

\example{4}
\blockquote[Doe 174][?]{This is a short quotation closed with a question mark
which is not part of the quotation itself}

\blockquote[Doe 174][?]{This is a long quotation. Apart from this absolutely
pointless filler text (which serves no purpose whatsoever besides making the
quotation exceed the block threshold so that the command used to typeset the
quotation will finally have mercy and present it as an indented paragraph) it
is similar to the short quotation above. It is closed with a question mark
which is not part of the quotation itself}

% There's an additional benefit to this last solution: if you quote a partial
% sentence, that is, if the end of the quotation is not the end of the quoted
% sentence, you can have csquotes mark the omission automatically be passing
% a period as the optional `punctuation' argument:

\blockquote[Doe 174][.]{This is a long quotation. Apart from this absolutely
pointless filler text (which serves no purpose whatsoever besides making the
quotation exceed the block threshold so that the command used to typeset the
quotation will finally have mercy and present it as an indented paragraph) it
is similar to the quotation above. In this case, however, the end of the
quotation is not the end of the quoted sentence%, which goes on like this.
}

% For the remaining examples, we restore the defaults:

\SetBlockThreshold{3}
\SetBlockEnvironment{quote}
\renewcommand*{\mkcitation}[1]{ (#1)}
\renewcommand*{\mkmidblockpunct}[1]{}
\renewcommand*{\mkfinblockpunct}[1]{#1}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Babel and csquotes}

% Let's take another, more systematic look at the commands and environments
% provided by the babel package to see how csquotes fits into the picture.
%
% First of all, we (re)set the main document language to `american'. This will
% reset strings like \chaptername and the date as printed by \today to the
% defaults:

\selectlanguage{american}

\example{1} \chaptername: \today

% Babel's `otherlanguage' environment switches hyphenation patterns and
% activates all extra definitions for the respective language, such as
% shorthands and language specific adjustments. It will also translate strings
% like \chaptername and localize the date format of \today. Essentially, it's
% like \selectlanguage but restricted to the scope of the environment.
%
% We'll use French as an example here because the language specific adjustments
% are obvious in this case (note the spaced out colon):

{\begin{otherlanguage}{french}

\example{2} \chaptername: \today

\end{otherlanguage}}

% Note that the extra set of braces in the example above was merely added to
% work around a bug in older versions of the babel package. They are not
% related to csquotes in any way and should not be required with a recent
% version of babel.

% The starred version of this environment switches hyphenation patterns and
% activates the language specific adjustments without modifying the strings:

\begin{otherlanguage*}{french}

\example{3} \chaptername: \today

\end{otherlanguage*}

% Babel's \foreignlanguage command is an inline version of the `otherlanguage*'
% environment:

\example{4} \foreignlanguage{french}{\chaptername: \today}

% Csquotes' \foreignquote command and all active quotes defined with
% \MakeForeignQuote behave the same as \foreignlanguage. The quotation mark
% style will be adapted to the language of the quotation:

\example{5} \foreignquote{french}{\chaptername: \today}

% Babel's `hyphenrules' environment switches hyphenation patterns without
% making any further adjustments. You won't see it in the typeset version of
% the example below, but inside the environment the active hyphenation patterns
% are actually the French ones while everything else adheres to the standards
% of the main document language (`american' here):

\begin{hyphenrules}{french}

\example{6} \chaptername: \today

\end{hyphenrules}

% The \hyphenquote command and all active quotes defined with \MakeHyphenQuote
% are inline versions of babel's `hyphenrules' environment plus quotation
% marks. They will switch hyphenation patterns without making any further
% adjustments. The quotation marks match the text surrounding the quotation:

\example{7} \hyphenquote{french}{\chaptername: \today}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Controlling active quotes}

% Once made active, the active quotes cannot be used any more as if they were
% ordinary characters. You may always include them literally in the text by
% using a verbatim environment, but it is also possible to control their
% current state in situations in which a verbatim environment is not feasible.

% The commands \EnableQuotes and \DisableQuotes will turn the active quotes on
% and off:

\example{1}
"text" «text» <text>

\DisableQuotes
"" «» <>

\EnableQuotes
"text" «text» <text>

% Like verbatim environments, these commands modify category codes. This
% implies that you cannot use them to change the behavior of the argument read
% in by a command. In this case, use \VerbatimQuotes instead. This command
% will print all active quotes literally without changing category codes.
% Since the scope of this command is local, you don't even need \EnableQuotes
% if you put everything in a group. Here's an example:

\newcommand{\printverbquotes}[1]{\begingroup\VerbatimQuotes #1\endgroup}

\example{2}
"text" «text» <text>

\printverbquotes{"" «» <>}

"text" «text» <text>

% Note that the situation is slighly different with active block quotes. Only
% the opening mark really is an active quote. The delimiter and the closing
% mark are also active characters, but their behavior is different. Outside
% the scope of a block quotation they may be employed as usual:

\example{3} \printverbquotes{<} | >

% When included in a block quotation, however, they would confuse TeX's
% argument scanner. You can prevent that by wrapping the offending character
% in curly brackets:

\example{4} <quotation \printverbquotes{<} {|} {>}|citation>

% Of course you can always use control sequences instead:

\example{5} <quotation \textless\ \textbar\ \textgreater|citation>

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% That's it.

\clearpage

% The bibliography is required by the integrated quotation commands discussed
% above.

\begin{thebibliography}{Doe 1996}
\bibitem{citekey} This is an example\dots
\bibitem[Doe 1996]{doe96} This is an example\dots
\end{thebibliography}

\end{document}