diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/common-lists-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/common-lists-en.tex | 836 |
1 files changed, 836 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/common-lists-en.tex b/macros/latex/contrib/koma-script/doc/common-lists-en.tex new file mode 100644 index 0000000000..4a2c64b798 --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/common-lists-en.tex @@ -0,0 +1,836 @@ +% ====================================================================== +% common-lists-en.tex +% Copyright (c) Markus Kohm, 2001-2022 +% +% 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.md. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-lists-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (common paragraphs)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} + +\section{Lists} +\seclabel{lists}% +\BeginIndexGroup +\BeginIndex{}{lists}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.lists} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.lists}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.lists.next}, + \autopageref{sec:\ThisCommonLabelBase.lists.next}.% + \IfThisCommonLabelBaseOneOf{scrextend,scrlttr2}{ % + \IfThisCommonLabelBase{scrlttr2}{% + The \Package{scrletter}\OnlyAt{\Package{scrletter}} package does not + define any list environments itself but leaves them to the class + used. If this is not a \KOMAScript{} class, it will load + \hyperref[cha:scrextend]{\Package{scrextend}}\IndexPackage{scrextend}% + \important{\hyperref[cha:scrextend]{\Package{scrextend}}}. % + }{}% + However, the \Package{scrextend} package only defines the + \DescRef{\ThisCommonLabelBase.env.labeling}, + \DescRef{\ThisCommonLabelBase.env.addmargin}, and + \DescRef{\ThisCommonLabelBase.env.addmargin*} environments. All other list + environments are left to the responsibility of the class used.% + }{}% +} + +\IfThisCommonLabelBase{scrextend}{}{% + Both {\LaTeX} and the standard classes\textnote{\KOMAScript{} vs. standard + classes} offer different environments for lists. Naturally, {\KOMAScript} + also offers all these environments, though slightly modified or extended in + some cases. In general, all lists\,---\,even those of different + kinds\,---\,can be nested up to four levels deep. From a typographical view, + anything more would make no sense, as lists of more than three levels cannot + easily be apprehended. In such cases, I recommend\textnote{Hint!} that you + split a large list into several smaller ones.% +} + +\IfThisCommonFirstRun{}{% + Because lists are standard elements of \LaTeX{}, examples have been omitted + in this section. Nevertheless, you can find examples either in + \autoref{sec:\ThisCommonFirstLabelBase.lists}, + \autopageref{sec:\ThisCommonFirstLabelBase.lists} or in any \LaTeX{} + tutorial.% +} + +\IfThisCommonLabelBase{scrextend}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \begin{Environment}{itemize} + \begin{Body} + \Macro{item} \dots + \BodyDots + \end{Body} + \end{Environment} + \Macro{labelitemi} + \Macro{labelitemii} + \Macro{labelitemiii} + \Macro{labelitemiv} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}% + The simplest form of a list is the itemized list\textnote{itemized list}, + \Environment{itemize}. % + \iffalse % Umbruckoptimierungstext + The users of a certain disliked word processing package often refer to this + form of a list as \emph{bullet points}. Presumably, they cannot imagine + that, depending on the level, a symbol other than a large dot could be used + to introduce each point. % + \fi% + Depending on the level, \KOMAScript{} classes use 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 you can redefine using + \Macro{renewcommand}. + \BeginIndex{FontElement}{itemizelabel}\LabelFontElement{itemizelabel}% + \BeginIndex{FontElement}{labelitemi}\LabelFontElement{labelitemi}% + \BeginIndex{FontElement}{labelitemii}\LabelFontElement{labelitemii}% + \BeginIndex{FontElement}{labelitemiii}\LabelFontElement{labelitemiii}% + \BeginIndex{FontElement}{labelitemiv}\LabelFontElement{labelitemiv}% + With the \KOMAScript{} classes the + fonts\Index{font>style}\ChangedAt{v3.33}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} used to format the symbols for the + different levels can be changed using + \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and + \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see + \autoref{sec:\ThisCommonLabelBase.textmarkup}, + \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the elements + \FontElement{labelitemi}\important{\FontElement{labelitemi}}, + \FontElement{labelitemii}\important{\FontElement{labelitemii}}, + \FontElement{labelitemiii}\important{\FontElement{labelitemiii}} and + \FontElement{labelitemiv}\important{\FontElement{labelitemiv}}. By default + these all use the font setting for element + \FontElement{itemizelabel}\important{\FontElement{itemizelabel}}. Only + element \FontElement{labelitemii} additionally uses \Macro{bfseries}. The + default of \FontElement{itemizelabel} itself is \Macro{normalfont}. Every + item is introduced with \Macro{item}.% + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.itemize}% + You have a simple list which is nested in several levels. You write, + for example: +\begin{lstcode} + \minisec{Vehicles in the game} + \begin{itemize} + \item aeroplanes + \begin{itemize} + \item biplane + \item transport planes + \begin{itemize} + \item single-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} + \item twin-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} + \end{itemize} + \item helicopters + \end{itemize} + \item motorcycles + \item automobiles + \begin{itemize} + \item racing cars + \item passenger cars + \item lorries + \end{itemize} + \item bicycles + \end{itemize} +\end{lstcode} + As output you get: + \begin{ShowOutput}[\baselineskip] + \minisec{Vehicles in the game} + \begin{itemize} + \item aeroplanes + \begin{itemize} + \item biplanes + \item transport planes + \begin{itemize} + \item single-engine + \begin{itemize} + \item jet-propelled + \item propeller-driven + \end{itemize} + \item twin-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} + \end{itemize} + \item helicopters + \end{itemize} + \item motorcycles + % \begin{itemize} + % \item historically accurate + % \item futuristic, not real + % \end{itemize} + \item automobiles + \begin{itemize} + \item racing cars + \item passenger cars + \item lorries + \end{itemize} + \item bicycles + \end{itemize} + \end{ShowOutput} + \end{Example} + \fi + % + \EndIndexGroup + + + \begin{Declaration} + \begin{Environment}{enumerate}\labelsuffix[enumerate] + \begin{Body} + \Macro{item} \dots + \BodyDots + \end{Body} + \end{Environment} + \Macro{theenumi}% + \Macro{theenumii}% + \Macro{theenumiii}% + \Macro{theenumiv}% + \Macro{labelenumi}% + \Macro{labelenumii}% + \Macro{labelenumiii}% + \Macro{labelenumiv} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}The numbered + list\textnote{numbered list} is also very common and already provided by the + {\LaTeX} kernel. The numbering\Index{numbering} differs according to the + level, with Arabic numbers, small letters, small Roman numerals, and capital + letters, respectively. The style 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 right parenthesis, the values of + all other levels are followed by a dot. Every item is introduced with + \Macro{item}.% + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.enumerate}% + Let's shorten the previous example, using an + \DescRef{\ThisCommonLabelBase.env.itemize} environment instead of the + \Environment{enumerate} environment: + \begin{ShowOutput}[\baselineskip] + \minisec{Vehicles in the game} + \begin{enumerate} + \item aeroplanes + \begin{enumerate} + \item biplanes + \item transport planes + \begin{enumerate} + \item single-engine + \begin{enumerate} + \item jet-propelled\label{xmp:maincls.jets} + \item propeller-driven + \end{enumerate} + \item twin-engine + \end{enumerate} + % \item helicopters + \end{enumerate} + \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} + Within the list, you can set labels in the normal way with + \Macro{label} and then reference then with \Macro{ref}. + In the example above, a label was set after the jet-propelled, + single-engine transport planes with + ``\Macro{label}\PParameter{xmp:jets}''. The \Macro{ref} value is then + ``\ref{xmp:maincls.jets}''. + \end{Example} + \fi% + % + \EndIndexGroup + + + \begin{Declaration} + \begin{Environment}{description}\labelsuffix[description] + \begin{Body} + \Macro{item}\OParameter{keyword} \dots + \BodyDots + \end{Body} + \end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}Another list + form is the description list\textnote{description list}. It primarily serves + to describe individual items or keywords. The item itself is specified as an + optional parameter in \Macro{item}. % + \BeginIndex{FontElement}{descriptionlabel}% + \LabelFontElement{descriptionlabel}% + The font\Index{font>style}\ChangedAt{v2.8p}{% + \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% + \ used to format the keyword can be changed with the + \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and + \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see + \autoref{sec:\ThisCommonLabelBase.textmarkup}, + \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the + \FontElement{descriptionlabel}\important{\FontElement{descriptionlabel}} + element (see \autoref{tab:\ThisCommonLabelBase.fontelements}, + \autopageref{tab:\ThisCommonLabelBase.fontelements}). The default is + \Macro{sffamily}\linebreak[1]\Macro{bfseries}.% + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.description}% + You want the keywords to be printed bold and in the normal font instead + of bold and sans serif. 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 (abbreviated) source is: +\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 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% + % + \EndIndexGroup% +\fi + +\begin{Declaration} + \begin{Environment}{labeling}\OParameter{delimiter} + \Parameter{widest pattern} + \labelsuffix[labeling] + \begin{Body} + \Macro{item}\OParameter{keyword}\dots + \BodyDots + \end{Body} + \end{Environment} +\end{Declaration}% +Another form of description list\textnote{alternative description list} is +only available in the {\KOMAScript} classes% +\IfThisCommonLabelBase{scrextend}{ and \Package{scrextend} }{% + \IfThisCommonLabelBase{scrlttr2}{ and + \hyperref[cha:scrextend]{\Package{scrextend}}}{}% +}% +: the \Environment{labeling} environment. Unlike +\IfThisCommonLabelBase{scrextend}{% + \DescRef{\ThisCommonFirstLabelBase.env.description}% +}{% + the \DescRef{\ThisCommonLabelBase.env.description} described above% +}, you can specify a pattern for \Environment{labeling} whose length +determines the indentation of all items. Furthermore, you can put an optional +\PName{delimiter} between the item and its description. % +\BeginIndexGroup +\BeginIndex{FontElement}{labelinglabel}\LabelFontElement{labelinglabel}% +\BeginIndex{FontElement}{labelingseparator}% +\LabelFontElement{labelingseparator}% +The font\Index{font>style}% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.02}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.02}{\Class{scrlttr2}}% + }{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.02}{\Package{scrextend}}% + }{\InternalCommonFileUsageError}% + }% +} used to format the item and the separator can be changed with the +\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the element +\FontElement{labelinglabel} and \FontElement{labelingseparator} (see +\autoref{tab:\ThisCommonLabelBase.fontelements}, +\autopageref{tab:\ThisCommonLabelBase.fontelements}). +\IfThisCommonFirstRun{\iftrue}{\par\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.labeling}% + \IfThisCommonLabelBase{scrextend}{% + A small example of a list like this can be written as follows:% + }{% + Slightly changing the example from the + \DescRef{\ThisCommonLabelBase.env.description} environment, we could + write the following:% + }% +\begin{lstcode} + \setkomafont{labelinglabel}{\ttfamily} + \setkomafont{labelingseparator}{\normalfont} + \begin{labeling}[~--]{myheadings} + \item[empty] + Page style without header or 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} + The result is this: + \begin{ShowOutput} + \setkomafont{labelinglabel}{\ttfamily} + \setkomafont{labelingseparator}{\normalfont} + \begin{labeling}[~--]{myheadings} + \item[empty] + Page style without header or 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 this example shows, you can set a font-changing command 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% +\EndIndexGroup +Originally, this environment was implemented for things like ``Premise, +Evidence, Proof'', or ``Given, Find, Solution'' that are often used in +lecture handouts. These days, however, the environment has very different +applications. For example, the environment for examples in this guide was +defined with the \Environment{labeling} environment.% +% +\EndIndexGroup + + +\IfThisCommonLabelBase{scrextend}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \begin{Environment}{verse}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{} The + \Environment{verse} environment\textnote{verse} is not normally 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. Internally, however, both the standard classes as well as + {\KOMAScript} implement it as a list environment. + + In general, the \Environment{verse} environment is used for + poetry\Index{poetry}. 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 can, + as usual, insert \verb|\\*| instead of \verb|\\|. + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.verse}% + \iffalse + 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} + \else + As an example, Emma Lazarus's sonnet from the pedestal of Liberty + Enlightening the World\footnote{The lines from Roald Dahl's poem + ``Little Red Riding Hood and the Wolf'', which was used in former + releases, has been replaced, because in these times certain + politicians around the world really seem to need ``The New + Colossus'' as urgent reminder.}: +\begin{lstcode} + \begin{verse} + Not like the brazen giant of Greek fame\\* + With conquering limbs astride from land to land\\* + Here at our sea-washed, sunset gates shall stand\\* + A mighty woman with a torch, whose flame\\* + Is the imprisoned lightning, and her name\\* + Mother of Exiles. From her beacon-hand\\* + Glows world-wide welcome; her mild eyes command\\* + The air-bridged harbor that twin cities frame.\\* + ``Keep, ancient lands, your storied pomp!'' cries she\\* + With silent lips. ``Give me your tired, your poor,\\* + Your huddled masses yearning to breathe free,\\* + The wretched refuse of your teeming shore.\\* + Send these, the homeless, tempest-tossed to me:\\* + I lift my lamp beside the golden door.'' + \end{verse} +\end{lstcode} + The result is as follows: + \begin{ShowOutput} + \begin{verse} + Not like the brazen giant of Greek fame\\* + With conquering limbs astride from land to land\\* + Here at our sea-washed, sunset gates shall stand\\* + A mighty woman with a torch, whose flame\\* + Is the imprisoned lightning, and her name\\* + Mother of Exiles. From her beacon-hand\\* + Glows world-wide welcome; her mild eyes command\\* + The air-bridged harbor that twin cities frame.\\* + ``Keep, ancient lands, your storied pomp!'' cries she\\* + With silent lips. ``Give me your tired, your poor,\\* + Your huddled masses yearning to breathe free,\\* + The wretched refuse of your teeming shore.\\* + Send these, the homeless, tempest-tossed to me:\\* + I lift my lamp beside the golden door.'' + \end{verse} + \end{ShowOutput} + \fi + However, if you have very long lines of verse where a line + break occurs within a line of verse: +\begin{lstcode} + \begin{verse} + Both the philosopher and the house-owner + always have something to repair.\\* + \bigskip + Don't trust a man, my son, who tells you + that he has never lied. + \end{verse} +\end{lstcode} + \begin{ShowOutput} + \begin{verse} + Both the philosopher and the house-owner always have something to + repair.\\ + \bigskip Don't trust a man, my son, who tells you that he has never + lied. + \end{verse} + \end{ShowOutput} + in this case \verb|\\*| can not prevent a page break occurring within a + verse at such a line break. To prevent such a page break, a change of + \Macro{interlinepenalty}\IndexCmd{interlinepenalty} would have to be + inserted at the beginning of the environment: +\begin{lstcode} + \begin{verse}\interlinepenalty 10000 + Both the philosopher and the house-owner + always have something to repair.\\ + \bigskip + Don't trust a man, my son, who tells you + that he has never lied. + \end{verse} +\end{lstcode} + \iftrue% Umbruchkorrekturtext + Here are two sayings that should always be considered when confronted + with seemingly strange questions about {\LaTeX} or its accompanying + explanations: +\begin{lstcode} + \begin{verse} + A little learning is a dangerous thing.\\* + Drink deep, or taste not the Pierian Spring;\\ + \bigskip + Our judgments, like our watches, none\\* + go just alike, yet each believes his own. + \end{verse} +\end{lstcode} + \begin{ShowOutput} + \iffree{}{\vskip-.8\baselineskip}% Umbruchkorrektur + \begin{verse} + A little learning is a dangerous thing.\\* + Drink deep, or taste not the Pierian Spring;\\ + \bigskip + Our judgments, like our watches, none\\* + go just alike, yet each believes his own. + \end{verse} + \end{ShowOutput} + \fi + Incidentally, \Macro{bigskip} was used in these examples to separate two + sayings. + \end{Example} + \fi + % + \EndIndexGroup + + \iffalse% Umbruchkorrekturvarianten + \begin{Declaration} + \begin{Environment}{quote}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}This is + internally also a list environment\textnote{block quote with paragraph + spacing} and can be found both in the standard classes and in + {\KOMAScript}. The content of the environment is set fully justified. + The environment is often used to format longer quotes\Index{quotes}. + Paragraphs within the environment are distinguished with vertical space.% + \EndIndexGroup + + \begin{Declaration} + \begin{Environment}{quotation}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}This + environment\textnote{block quote with paragraph indent} is comparable to + \DescRef{\ThisCommonLabelBase.env.quote}. While + \DescRef{\ThisCommonLabelBase.env.quote} paragraphs are indicated by + vertical spacing, \Environment{quotation} indents the first line of each + paragraph horizontally. This also applies to the first paragraph of a + \Environment{quotation} environment. If you want to prevent the + indentation there, you must precede it with the + \Macro{noindent}\IndexCmd{noindent} command.% + \else + \begin{Declaration} + \begin{Environment}{quote}\end{Environment} + \begin{Environment}{quotation}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{} These two + environments\textnote{block quotes} are also set internally as list + environments and can be found in both the standard and the {\KOMAScript} + classes. Both environments use justified text which is indented on both + the left and the right side. Often they are used to separate longer + quotations\Index{quotations} from the main text. The difference between + the two lies in in the manner in which paragraphs are typeset. While + \Environment{quote} paragraphs are distinguished by vertical space, in + \Environment{quotation} paragraphs, the first line is indented. This also + applies to the first line of a \Environment{quotation} + environment% Umbruchkorrektur + \IfThisCommonLabelBase{maincls}{% + , unless it is preceded by \Macro{noindent}\IndexCmd{noindent}.% + }{% + \IfThisCommonLabelBase{scrlttr2}{% + . If you want to prevent the indentation there, you must precede it + with the \Macro{noindent} command\IndexCmd{noindent}.% + }{\InternalCommonFileUsageError}% + }% + \fi % Umbruchkorrekturvarianten + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.quote}% + 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 + % + \EndIndexGroup +\fi + +\begin{Declaration} + \begin{Environment}{addmargin} + \OParameter{left indentation}\Parameter{indentation} + \end{Environment} + \begin{Environment}{addmargin*} + \OParameter{inner indentation}\Parameter{indentation} + \end{Environment} +\end{Declaration} +Like \IfThisCommonLabelBase{scrextend}{% + \DescRef{\ThisCommonFirstLabelBase.env.quote} and + \DescRef{\ThisCommonFirstLabelBase.env.quotation}, which are available in + the standard and the \KOMAScript{} classes}{% + \DescRef{\ThisCommonLabelBase.env.quote} and + \DescRef{\ThisCommonLabelBase.env.quotation}% +}, the \Environment{addmargin} environment changes the margin\Index{margin}. +However, unlike the first two environments, \Environment{addmargin} lets the +user change the width of the indentation. Apart from this change, 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 the value \PName{left + indentation} is used for the left margin instead of \PName{indentation}. + +The starred variant \Environment{addmargin*}% +\important{\Environment{addmargin*}} differs from the normal version only in +the two-sided mode. Furthermore, the difference only occurs if the optional +argument \PName{inner indentation} is used. In this case, the value of +\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 allow negative values for all parameters. +\IfThisCommonLabelBase{scrextend}{% + The environment then protrudes into the margin accordingly.% +}{% + This can be done so that the environment protrudes into the margin.% +}% +\IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.addmargin}% +\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 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} +\fi% + +Whether a page is going to be on the left or right side of the book cannot be +determined reliably on the first {\LaTeX} run. For details please refer to +the explanation of the commands +\DescRef{\ThisCommonLabelBase.cmd.Ifthispageodd} +(\autoref{sec:\ThisCommonLabelBase.oddOrEven}, +\DescPageRef{\ThisCommonLabelBase.cmd.Ifthispageodd}) and +\iffree{\Macro{ifthispagewasodd}}{% + \DescRef{maincls-experts.cmd.ifthispagewasodd}} +(\autoref{sec:maincls-experts.addInfos}\iffree{}{, +\DescPageRef{maincls-experts.cmd.Ifthispageodd}}). +\IfThisCommonLabelBase{scrlttr2}{}{% +\begin{Explain} + The interplay of environments such as lists and paragraphs gives rise to + frequent questions. Therefore, you can find further explanation in the + description of the \Option{parskip} option in + \autoref{sec:maincls-experts.addInfos}\iffree{}{, + \DescPageRef{maincls-experts.option.parskip}. Also in the expert section, in + \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.env.addmargin*}, you can find additional + information about page breaks inside \Environment{addmargin*}}.% +\end{Explain}}% +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: |