summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/common-12.tex
blob: 098dee059fd17e4326f648755a5ef1c88e72abc8 (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
% ======================================================================
% common-12.tex
% Copyright (c) Markus Kohm, 2001-2015
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX 
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% common-12.tex
% Copyright (c) Markus Kohm, 2001-2015
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3c ist Teil aller Verteilungen von LaTeX
% Version 2005/12/01 oder spaeter und dieses Werks.
%
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
% (allein durch den Autor verwaltet).
%
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
% 
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
% ======================================================================
%
% Paragraphs that are common for several chapters of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind
% Verwaltet von Markus Kohm
%
% ======================================================================

\KOMAProvidesFile{common-12.tex}
                 [$Date: 2015-03-31 11:10:59 +0200 (Tue, 31 Mar 2015) $
                  KOMA-Script guide (common paragraphs)]
\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi}

% Date of the translated German file: 2015-03-31

\makeatletter
\@ifundefined{ifCommonmaincls}{\newif\ifCommonmaincls}{}%
\@ifundefined{ifCommonscrextend}{\newif\ifCommonscrextend}{}%
\@ifundefined{ifCommonscrlttr}{\newif\ifCommonscrlttr}{}%
\@ifundefined{ifIgnoreThis}{\newif\ifIgnoreThis}{}%
\makeatother


\section{Lists}
\seclabel{lists}%
\ifshortversion\IgnoreThisfalse\IfNotCommon{maincls}{\IgnoreThistrue}\fi%
\ifIgnoreThis %+++++++++++++++++++++++++++++++++++++++++++++ nicht maincls +
What is described in
\autoref{sec:maincls.lists} applies, mutatis mutandis.
\IfCommon{scrextend}{%
  However, \Package{scrextend} does support only the environments
  \Environment{labeling}, \Environment{addmargin} and
  \Environment{addmargin*}. All the other list environments may be supported
  and controlled by the used class.}
\else %------------------------------------------------------- nur maincls -
\BeginIndex{}{lists}%

Both {\LaTeX} and the standard classes offer different environments for
lists. Though slightly changed or extended all these list are of course
offered in {\KOMAScript} as well. In general, all lists\,---\,even of different
kind\,---\,can be nested up to four levels. From a typographical view,
anything more would make no sense, as more than three levels can no longer be
easily perceived. The recommended\textnote{Hint!} procedure in such a case is
to split the large list into several smaller ones.

\IfCommon{scrlttr2}{%
  Because lists are standard elements of \LaTeX{} this section abandons on
  examples. Nevertheless, you may find examples either in
  \autoref{sec:maincls.lists} from \autopageref{sec:maincls.lists} or in
  almost every introduction to \LaTeX.}

\ifCommonscrextend\else
\begin{Declaration}
  \XMacro{begin}\PParameter{\Environment{itemize}}\\
  \quad\Macro{item}\\
  \quad\dots\\
  \XMacro{end}\PParameter{itemize}\\
  \Macro{labelitemi}\\
  \Macro{labelitemii}\\
  \Macro{labelitemiii}\\
  \Macro{labelitemiv}
\end{Declaration}%
\BeginIndex{Env}{itemize}%
\BeginIndex{Cmd}{item}%
\BeginIndex{Cmd}{labelitemi}%
\BeginIndex{Cmd}{labelitemii}%
\BeginIndex{Cmd}{labelitemiii}%
\BeginIndex{Cmd}{labelitemiv}%
The simplest form of a list is an \Environment{itemize} list.
\iffalse % Umbruckoptimierungstext
The users of a certain disliked word processing package often refer to
this form of a list as \emph{bulletpoints}.  Presumably, these users
are unable to envisage that, depending on the level, a different
symbol from a large dot could be used to introduce each
point. %
\fi%
Depending on the level, {\KOMAScript} uses the following marks:
``{\labelitemi}'', ``{\labelitemii}'', ``{\labelitemiii}'' and
``{\labelitemiv}''. The definition of these symbols is specified in
the macros \Macro{labelitemi}, \Macro{labelitemii},
\Macro{labelitemiii} and \Macro{labelitemiv}, all of which can be
redefined using \Macro{renewcommand}. Every item is introduced with
\Macro{item}.%
%
\ifCommonmaincls
\begin{Example}
  \phantomsection\label{desc:maincls.env.itemize.example}%
  You have a simple list which is nested in several levels. You write
  for example:
\begin{lstcode}
  \minisec{Vehicles}
  \begin{itemize}
    \item aeroplanes
    \begin{itemize}
      \item biplane
      \item jets
      \item transport planes
      \begin{itemize}
        \item single-engined
        \begin{itemize}
          \item jet-driven
          \item propeller-driven
        \end{itemize}
        \item multi-engined
      \end{itemize}
      \item helicopters
    \end{itemize}
    \item automobiles
    \begin{itemize}
      \item racing cars
      \item private cars
      \item lorries
    \end{itemize}
    \item bicycles
  \end{itemize}
\end{lstcode}
  As output you get:
  \begin{ShowOutput}[\baselineskip]
  \minisec{Vehicles}
  \begin{itemize}
    \item aeroplanes
    \begin{itemize}
      \item biplanes
      \item jets
      \item transport planes
      \begin{itemize}
        \item single-engined
        \begin{itemize}
          \item jet-driven
          \item propeller-driven
        \end{itemize}
        \item multi-engined
      \end{itemize}
      \item helicopters
    \end{itemize}
% Falls fuer die Umbruchoptimierung erforderlich, kann die Liste
% beispielsweise so erweitert werden:
%    \item motorcycles
%    \begin{itemize}
%      \item historically accurate
%      \item futuristic, not real
%    \end{itemize}
    \item automobiles
    \begin{itemize}
      \item racing cars
      \item private cars
      \item lorries
    \end{itemize}
    \item bicycles
  \end{itemize}
  \end{ShowOutput}
\end{Example}
\fi% \ifCommonmaincls
%
\EndIndex{Env}{itemize}%
\EndIndex{Cmd}{item}%
\EndIndex{Cmd}{labelitemi}%
\EndIndex{Cmd}{labelitemii}%
\EndIndex{Cmd}{labelitemiii}%
\EndIndex{Cmd}{labelitemiv}%


\begin{Declaration}
  \XMacro{begin}\PParameter{\Environment{enumerate}}\\
  \quad\XMacro{item}\\
  \quad\dots\\
  \XMacro{end}\PParameter{enumerate}\\
  \Macro{theenumi}\\
  \Macro{theenumii}\\
  \Macro{theenumiii}\\
  \Macro{theenumiv}\\
  \Macro{labelenumi}\\
  \Macro{labelenumii}\\
  \Macro{labelenumiii}\\
  \Macro{labelenumiv}
\end{Declaration}%
\BeginIndex{Env}{enumerate}%
\BeginIndex{Cmd}{item}%
\BeginIndex{Cmd}{theenumi}%
\BeginIndex{Cmd}{theenumii}%
\BeginIndex{Cmd}{theenumiii}%
\BeginIndex{Cmd}{theenumiv}%
\BeginIndex{Cmd}{labelenumi}%
\BeginIndex{Cmd}{labelenumii}%
\BeginIndex{Cmd}{labelenumiii}%
\BeginIndex{Cmd}{labelenumiv}%
Another form of a list often used is a numbered list which is already
implemented by the {\LaTeX} kernel. Depending on the level, the
numbering\Index{numbering} uses the following characters: Arabic numbers,
small letters, small roman numerals, and capital letters. The kind of numbering
is defined with the macros \Macro{theenumi} down to \Macro{theenumiv}. The
output format is determined by the macros \Macro{labelenumi} to
\Macro{labelenumiv}. While the small letter of the second level is followed by
a round parenthesis, the values of all other levels are followed by a
dot. Every item is introduced with \Macro{item}.%
\ifCommonmaincls
\begin{Example}
  \phantomsection\label{desc:maincls.env.enumerate.example}%
  Replacing every occurrence of an \Environment{itemize} environment
  with an \Environment{enumerate} environment in the example above we
  get the following result:
  \begin{ShowOutput}[\baselineskip]
  \minisec{Vehicles}
  \begin{enumerate}
    \item aeroplanes
    \begin{enumerate}
      \item biplanes
      \item jets
      \item transport planes
      \begin{enumerate}
        \item single-engined
        \begin{enumerate}
          \item jet-driven\label{xmp:maincls.jets}
          \item propeller-driven
        \end{enumerate}
        \item multi-engined
      \end{enumerate}
      \item helicopters
    \end{enumerate}
% Wie oben:
%    \item motorcycles
%    \begin{enumerate}
%      \item historically accurate
%      \item futuristic, not real
%    \end{enumerate}
    \item automobiles
    \begin{enumerate}
      \item racing cars
      \item private cars
      \item lorries
    \end{enumerate}
    \item bicycles
  \end{enumerate}
  \end{ShowOutput}
  Using \Macro{label} within a list you can set labels which are
  referenced with \Macro{ref}. In the example above, a label was set
  after the jet-driven, single-engined transport planes with
  \Macro{label}\PParameter{xmp:jets}. The \Macro{ref} value is then
  \ref{xmp:maincls.jets}.
\end{Example}
\fi% \ifCommonmaincls
%
\EndIndex{Env}{enumerate}%
\EndIndex{Cmd}{item}%
\EndIndex{Cmd}{theenumi}%
\EndIndex{Cmd}{theenumii}%
\EndIndex{Cmd}{theenumiii}%
\EndIndex{Cmd}{theenumiv}%
\EndIndex{Cmd}{labelenumi}%
\EndIndex{Cmd}{labelenumii}%
\EndIndex{Cmd}{labelenumiii}%
\EndIndex{Cmd}{labelenumiv}%


\begin{Declaration}
  \XMacro{begin}\PParameter{\Environment{description}}\\
  \quad\XMacro{item}\OParameter{keyword}\\
  \quad\dots\\
  \XMacro{end}\PParameter{description}
\end{Declaration}%
\BeginIndex{Env}{description}%
\BeginIndex{Cmd}{item}%
A further list form is the description list. Its main use is the description
of several items. The item itself is an optional parameter in
\Macro{item}. The font\Index{font>style}\ChangedAt{v2.8p}{%
  \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}%
 which is responsible for emphasizing the item can be changed with the commands
\Macro{setkomafont} and \Macro{addtokomafont} (see \autoref{sec:\csname
  label@base\endcsname.textmarkup}, \autopageref{desc:\csname
  label@base\endcsname.cmd.setkomafont}) for the element
\FontElement{descriptionlabel}\IndexFontElement{descriptionlabel} (see
\autoref{tab:\csname label@base\endcsname.elementsWithoutText},
\autopageref{tab:\csname label@base\endcsname.elementsWithoutText}). Default
setting is \Macro{sffamily}\linebreak[2]\Macro{bfseries}.%
\ifCommonmaincls
\begin{Example}
  \phantomsection\label{desc:maincls.env.description.example}%
  Instead of items in sans serif and bold, you want them printed in the
  standard font in bold. Using
\begin{lstcode}
  \setkomafont{descriptionlabel}{\normalfont\bfseries}
\end{lstcode}
  you redefine the font accordingly.

  An example for a description list is the output of the page styles
  listed in \autoref{sec:maincls.pagestyle}. The heavily
  abbreviated source could be:
\begin{lstcode}
  \begin{description}
  \item[empty] is the page style without any header or footer.
    \item[plain] is the page style without headings.
    \item[headings] is the page style with running headings.
    \item[myheadings] is the page style for manual headings.
  \end{description}
\end{lstcode}
  This abbreviated version gives:
  \begin{ShowOutput}
    \begin{description}
    \item[empty] is the page style without any header or footer.
    \item[plain] is the page style without headings.
    \item[headings] is the page style with running headings.
    \item[myheadings] is the page style for manual headings.
    \end{description}
  \end{ShowOutput}
\end{Example}
\fi% \ifComminmaincls
%
\EndIndex{Env}{description}%
\EndIndex{Cmd}{item}%
\fi % \ifCommonscrextend\else

\begin{Declaration}
  \XMacro{begin}\PParameter{\Environment{labeling}}%
  \OParameter{delimiter}\Parameter{widest pattern}\\
  \quad\XMacro{item}\OParameter{keyword}\\
  \quad\dots\\
  \XMacro{end}\PParameter{labeling}
\end{Declaration}%
\BeginIndex{Env}{labeling}%
\BeginIndex{Cmd}{item}%
An additional form of a description list is only available in the
{\KOMAScript} classes%
\IfCommon{scrextend}{ and the package \Package{scrextend}}: the
\Environment{labeling} environment. Unlike the
\Environment{description} environment, you can provide a pattern whose length
determines the indentation of all items. Furthermore, you can put an optional
\PName{delimiter} between the item and its description.  The
font\Index{font>style}\ChangedAt{v3.01}{%
  \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and
  \Package{scrextend}}%
 which is responsible for emphasizing the item and the separator can be changed
with the commands \Macro{setkomafont} and \Macro{addtokomafont} (see \autoref{sec:\csname
  label@base\endcsname.textmarkup}, \autopageref{desc:\csname
  label@base\endcsname.cmd.setkomafont}) for the element
\FontElement{labelinglabel}\IndexFontElement{labelinglabel} and
\FontElement{labelingseparator}\IndexFontElement{labelingseparator} (see
\ifCommonscrextend
\autoref{tab:maincls.elementsWithoutText},
\autopageref{tab:maincls.elementsWithoutText}
\else
\autoref{tab:\csname label@base\endcsname.elementsWithoutText},
\autopageref{tab:\csname label@base\endcsname.elementsWithoutText}%
\fi).
\ifCommonscrlttr\par\else
\begin{Example}
  \phantomsection\label{desc:\csname
    label@base\endcsname.env.labeling.example}%
  \IfCommon{maincls}{Slightly changing the example from the
    \Environment{description} environment, we could write:}%
  \IfCommon{scrextend}{A small example of a list like this may be written:}%
\begin{lstcode}
  \setkomafont{labelinglabel}{\ttfamily}
  \setkomafont{labelingseparator}{\normalfont}
  \begin{labeling}[~--]{myheadings}
    \item[empty]
      Page style without header and footer
    \item[plain]
      Page style for chapter beginnings without headings
    \item[headings]
      Page style for running headings
    \item[myheadings]
      Page style for manual headings
  \end{labeling}
\end{lstcode}
  As the result we get:
  \begin{ShowOutput}
    \setkomafont{labelinglabel}{\ttfamily}
    \setkomafont{labelingseparator}{\normalfont}
    \begin{labeling}[~--]{myheadings}
    \item[empty]
      Page style without header and footer
    \item[plain]
      Page style for chapter beginnings without headings
    \item[headings]
      Page style for running headings
    \item[myheadings]
      Page style for manual headings
    \end{labeling}
  \end{ShowOutput}
  As can be seen in this example, a font changing command may be set
  in the usual way. But if you do not want the font of the separator to
  be changed in the same way as the font of the label, you have to set
  the font of the separator as well.
\end{Example}
\fi% \ifCommonscrlttr \else
Originally, this environment was implemented for things like ``Precondition,
Assertion, Proof'', or ``Given, Required, Solution'' that are often used in
lecture hand-outs.  By now this environment has found many different
applications. For example, the environment for examples in this guide was
defined with the \Environment{labeling} environment.%
%
\EndIndex{Env}{labeling}%
\EndIndex{Cmd}{item}%


\ifCommonscrextend\else
\begin{Declaration}
  \XMacro{begin}\PParameter{\Environment{verse}}\\
  \quad\dots\\
  \XMacro{end}\PParameter{verse}
\end{Declaration}%
\BeginIndex{Env}{verse}%
Usually the \Environment{verse} environment is not perceived as a list
environment because you do not work with \Macro{item}
commands. Instead, fixed line breaks are used within the
\Environment{flushleft} environment. Yet internally in both the
standard classes as well as {\KOMAScript} it is indeed a list
environment.

In general, the \Environment{verse} environment is used for
poems\Index{poems}.  Lines are indented both left and
right. Individual lines of verse are ended by a fixed line break
\verb|\\|. Verses are set as paragraphs, separated by an empty
line. Often also \Macro{medskip}\IndexCmd{medskip} or
\Macro{bigskip}\IndexCmd{bigskip} is used instead. To avoid a page
break at the end of a line of verse you could, as usual, insert \verb|\\*|
instead of \verb|\\|.
\ifCommonmaincls
\begin{Example}
  \phantomsection\label{desc:maincls.env.verse.example}%
  As an example, the first lines of ``Little Red Riding Hood and the
  Wolf'' by Roald Dahl:
\begin{lstcode}
  \begin{verse}
    As soon as Wolf began to feel\\*
    that he would like a decent meal,\\*
    He went and knocked on Grandma's door.\\*
    When Grandma opened it, she saw\\*
    The sharp white teeth, the horrid grin,\\*
    And Wolfie said, `May I come in?'
  \end{verse}
\end{lstcode}
  The result is as follows:
  \begin{ShowOutput}
  \begin{verse}
    As soon as Wolf began to feel\\*
    That he would like a decent meal,\\*
    He went and knocked on Grandma's door.\\*
    When Grandma opened it, she saw\\*
    The sharp white teeth, the horrid grin,\\*
    And Wolfie said, `May I come in?'
  \end{verse}
  \end{ShowOutput}
  However, if you have very long lines of verse, for instance:
\begin{lstcode}
  \begin{verse}
    Both the philosopher and the house-owner
    have always something to repair.\\
    \bigskip
    Don't trust a man, my son, who tells you
    that he has never lied.
  \end{verse}
\end{lstcode}
  where a line break occurs within a line of verse:
\begin{ShowOutput}
  \begin{verse}
    Both the philosopher and the house-owner
    have always something to repair.\\
    \bigskip
    Don't trust a man, my son, who tells you
    that he has never lied.
  \end{verse}
\end{ShowOutput}
  there \verb|\\*| can not prevent a page break occurring within a verse
  at such a line break. To prevent such a page break, a
  \Macro{nopagebreak}\IndexCmd{nopagebreak} would have to be inserted
  somewhere in the first line:
\begin{lstcode}
  \begin{verse}
    Both the philosopher and the house-owner\nopagebreak
    have always something to repair.\\
    \bigskip
    Don't trust a man, my son, who tells you\nopagebreak
    that he has never lied.
  \end{verse}
\end{lstcode}

  In the above example, \Macro{bigskip} was used to separate the lines
  of verse.
\end{Example}
\fi % \ifCommonmaincls
%
\EndIndex{Env}{verse}%

\begin{Declaration}
  \XMacro{begin}\PParameter{\Environment{quote}}\\
  \quad\dots\\
  \XMacro{end}\PParameter{quote}\\
  \XMacro{begin}\PParameter{\Environment{quotation}}\\
  \quad\dots\\
  \XMacro{end}\PParameter{quotation}
\end{Declaration}%
\BeginIndex{Env}{quote}%
\BeginIndex{Env}{quotation}%
These two environments are also list environments and can be found
both in the standard and the {\KOMAScript} classes. Both environments
use justified text which is indented both on the left and right side.
Usually they are used to separate long citations\Index{citations} from
the main text. The difference between these two lies in the manner in
which paragraphs are typeset. While \Environment{quote} paragraphs are
highlighted by vertical space, in \Environment{quotation} paragraphs
the first line is indented. This is also true for the first line of a
\Environment{quotation} environment. To prevent indentation you have
to insert a \Macro{noindent} command\IndexCmd{noindent} before the
text.
\ifCommonmaincls
\begin{Example}
  \phantomsection\label{desc:maincls.env.quote.example}%
  You want to highlight a short anecdote. You write the following
  \Environment{quotation} environment for this:
  %
\begin{lstcode}
  A small example for a short anecdote:
  \begin{quotation}
    The old year was turning brown; the West Wind was
    calling;
        
    Tom caught the beechen leaf in the forest falling.
    ``I've caught the happy day blown me by the breezes!
    Why wait till morrow-year? I'll take it when me pleases.
    This I'll mend my boat and journey as it chances
    west down the withy-stream, following my fancies!''
    
    Little Bird sat on twig. ``Whillo, Tom! I heed you.
    I've a guess, I've a guess where your fancies lead you.
    Shall I go, shall I go, bring him word to meet you?''
  \end{quotation}
\end{lstcode}
  The result is:
  \begin{ShowOutput}
    A small example for a short anecdote:
    \begin{quotation}
    The old year was turning brown; the West Wind was
    calling;
    
    Tom caught the beechen leaf in the forest falling.
    ``I've caught the happy day blown me by the breezes!
    Why wait till morrow-year? I'll take it when me pleases.
    This I'll mend my boat and journey as it chances
    west down the withy-stream, following my fancies!''
    
    Little Bird sat on twig. ``Whillo, Tom! I heed you.
    I've a guess, I've a guess where your fancies lead you.
    Shall I go, shall I go, bring him word to meet you?''
    \end{quotation}
  \end{ShowOutput}
  %
  Using a \Environment{quote} environment instead you get:
  %
  \begin{ShowOutput}
    A small example for a short anecdote:
     \begin{quote}\setlength{\parskip}{4pt plus 2pt minus 2pt}
    The old year was turning brown; the West Wind was
    calling;

    Tom caught the beechen leaf in the forest falling.
    ``I've caught the happy day blown me by the breezes!
    Why wait till morrow-year? I'll take it when me pleases.
    This I'll mend my boat and journey as it chances
    west down the withy-stream, following my fancies!''
    
    Little Bird sat on twig. ``Whillo, Tom! I heed you.
    I've a guess, I've a guess where your fancies lead you.
    Shall I go, shall I go, bring him word to meet you?''
    \end{quote}
  \end{ShowOutput}
  %
\end{Example}
\fi % \ifCommonmaincls
%
\EndIndex{Env}{quote}%
\EndIndex{Env}{quotation}%
\fi % \ifCommonscrextend\else

\begin{Declaration}
  \XMacro{begin}\PParameter{\Environment{addmargin}}%
  \OParameter{left indentation}\Parameter{indentation}\\
  \quad\dots\\
  \XMacro{end}\PParameter{addmargin}\\
  \XMacro{begin}\PParameter{\Environment{addmargin*}}%
  \OParameter{inner indentation}\Parameter{indentation}\\
  \quad\dots\\
  \XMacro{end}\PParameter{addmargin*}
\end{Declaration}
\BeginIndex{Env}{addmargin}%
\BeginIndex{Env}{addmargin*}%
Similar to \Environment{quote} and \Environment{quotation}%
\IfCommon{scrextend}{ which are available at the standard classes and also the
  \KOMAScript{} classes}%
, the \Environment{addmargin} environment changes the margin\Index{margin}.
In contrast to the first two environments, with \Environment{addmargin} the
user can set the width of the indentation. Besides this, this environment does
not change the indentation of the first line nor the vertical spacing between
paragraphs.

If only the obligatory argument \PName{indentation} is given, both the
left and right margin are expanded by this value. If the optional
argument \PName{left indentation} is given as well, then at the left
margin the value \PName{left indentation} is used instead of
\PName{indentation}.

The starred \Environment{addmargin*} only differs from the normal
version in a two-sided layout. Furthermore, the difference only occurs
if the optional argument \PName{inner indentation} is used. In this
case this value \PName{inner indentation} is added to the normal inner
indentation. For right-hand pages this is the left margin, for
left-hand pages the right margin. Then the value of
\PName{indentation} determines the width of the opposite margin.

Both versions of this environment take also negative values for all
parameters. This has the effect of expanding the environment into the
margin.
\ifCommonscrlttr\else
\begin{Example}
  \phantomsection\label{desc:maincls.env.addmargin.example}%
\begin{lstcode}
  \newenvironment{SourceCodeFrame}{%
    \begin{addmargin*}[1em]{-1em}%
      \begin{minipage}{\linewidth}%
        \rule{\linewidth}{2pt}%
  }{%
      \rule[.25\baselineskip]{\linewidth}{2pt}%
      \end{minipage}%
    \end{addmargin*}%
  }
\end{lstcode}
  If you now put your source code in such an environment it will show
  up as:
  \begin{ShowOutput}
  \newenvironment{SourceCodeFrame}{%
    \begin{addmargin*}[1em]{-1em}%
      \begin{minipage}{\linewidth}%
        \rule{\linewidth}{2pt}%
  }{%
      \rule[.25\baselineskip]{\linewidth}{2pt}%
      \end{minipage}%
    \end{addmargin*}%
  }
  You define yourself the following environment:
  \begin{SourceCodeFrame}
\begin{lstcode}
\newenvironment{\SourceCodeFrame}{%
  \begin{addmargin*}[1em]{-1em}%
    \begin{minipage}{\linewidth}%
      \rule{\linewidth}{2pt}%
}{%
    \rule[.25\baselineskip]{\linewidth}{2pt}%
    \end{minipage}%
  \end{addmargin*}%
}
\end{lstcode}
  \end{SourceCodeFrame}
  This may be feasible or not. In any case it shows the usage of this
  environment.
  \end{ShowOutput}
  The optional argument of the \Environment{addmargin*} environment
  makes sure that the inner margin is extended by 1\Unit{em}. In turn
  the outer margin is decreased by 1\Unit{em}. The result is a shift
  by 1\Unit{em} to the outside.  Instead of \PValue{1em} you can of
  course use a length, for example, \PValue{2\Macro{parindent}}.
\end{Example}

Whether a page is going to be on the left or right side
of the book can not be determined for certain in the first {\LaTeX}
run.  For details please refer to the explanation of the commands
\Macro{ifthispageodd} (\autoref{sec:\csname
  label@base\endcsname.oddOrEven}, \autopageref{desc:\csname
  label@base\endcsname.cmd.ifthispageodd}) and \Macro{ifthispagewasodd}
(\autoref{sec:maincls-experts.addInfos},
\autopageref{desc:maincls-experts.cmd.ifthispageodd}).

\begin{Explain}
  There may be several questions about coexistence of lists and
  paragraphs. Because of this additional information may be found at the
  description of option \Option{parskip} in
  \autoref{sec:maincls-experts.addInfos},
  \autopageref{desc:maincls-experts.option.parskip}. Also at the expert part,
  in \autoref{sec:maincls-experts.addInfos},
  \autopageref{desc:maincls-experts.env.addmargin*}, you may find additional
  information about page breaks inside of \Environment{addmargin*}.%
\end{Explain}%
\fi% \ifCommonscrlttr\else
%
\EndIndex{Env}{addmargin}%
\EndIndex{Env}{addmargin*}%
%
\EndIndex{}{lists}
\fi %**************************************************** Ende nur maincls *


%%% Local Variables:
%%% mode: latex
%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End: