summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/common-parmarkup-en.tex
blob: b2ce3f8a588bc566a3ee6bbec9d0005e625d579e (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
% ======================================================================
% common-parmarkup-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-parmarkup-en.tex}
                 [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $
                  KOMA-Script guide (common paragraph: Paragraph Markup)]
\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and
	Karl Hagen}

\section{Marking Paragraphs}
\seclabel{parmarkup}%
\BeginIndexGroup
\BeginIndex{}{paragraph>marking}%

\IfThisCommonLabelBase{maincls}{%
  The\textnote{paragraph indent vs. paragraph spacing} standard classes
  normally set paragraphs\Index[indexmain]{paragraph} indented and without any
  vertical, inter-paragraph space. This is the best solution when using a
  regular page layout like the ones produced with the \Package{typearea}
  package. If neither indentation nor vertical space is used, only the length
  of the last line would give the reader a guide to the paragraph break. In
  extreme cases, it is very difficult to tell whether a line is full or not.
  Furthermore, typographers find that a signal given at the paragraph's end is
  easily forgotten by the start of the next line. A signal at the paragraph's
  beginning is more easily remembered. Inter-paragraph spacing has the
  drawback of disappearing in some contexts. For instance, after a displayed
  formula it would be impossible to detect if the previous paragraph continues
  or a new one begins. Also, at the top of a new page, it might be necessary
  to look at the previous page to determine if a new paragraph has been
  started or not. All these problems disappear when using indentation. A
  combination of indentation and vertical inter-paragraph spacing is redundant
  and therefore should be avoided. Indentation\Index[indexmain]{indentation}
  alone is sufficient. The only drawback of indentation is that it shortens
  the line length. The use of inter-paragraph spacing\Index{paragraph>spacing}
  is therefore justified when using short lines, such as in a newspaper.%
}{%
  \IfThisCommonLabelBase{scrlttr2}{%
    The preliminaries of \autoref{sec:maincls.parmarkup},
    \autopageref{sec:maincls.parmarkup} explain why paragraph indentation is
    preferred to paragraph spacing. But the elements to which this explanation
    refers, for example figures, tables, lists, equations, and even new pages,
    are rare in normal letters. Letters are usually not so long that an
    unrecognised paragraph will have serious consequences to the readability
    of the document. The arguments for indentation, therefore, are less
    consequential for standard letters. This may be one reason that you often
    find paragraphs in letters marked with vertical spacing. But two
    advantages of paragraph indentation remain. One is that such a letter
    stands out from the crowd. Another is that it maintains the \emph{brand
    identity}, that is the uniform appearance, of all documents from a single
    source.%
  }{\InternalCommonFileUsageError}%
} %
\IfThisCommonFirstRun{}{%
  Apart from these suggestions, the information described in
  \autoref{sec:\ThisCommonFirstLabelBase.parmarkup} for the other
  \KOMAScript{} classes is valid for letters too. So if you have already read
  and understood \autoref{sec:\ThisCommonFirstLabelBase.parmarkup} you can
  skip ahead to \autoref{sec:\ThisCommonLabelBase.parmarkup.next} on
  \autopageref{sec:\ThisCommonLabelBase.parmarkup.next}.%
  \IfThisCommonLabelBase{scrlttr2}{ %
    This also applies if you work not with the
    \Class{scrlttr2}\OnlyAt{scrlttr2} class but with the \Package{scrletter}
    package. The package does not provide its own settings for paragraph
    formatting but relies entirely on the class being used.%
  }{}%
}


\begin{Declaration}
  \OptionVName{parskip}{method}
\end{Declaration}
\IfThisCommonLabelBase{maincls}{%
  Once in a while you may require a document layout with vertical
  inter-paragraph spacing instead of indentation. The \KOMAScript{} classes
  provide several ways to accomplish this with the
  \Option{parskip}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and
    \Class{scrartcl}} option.%
}{%
  \IfThisCommonLabelBase{scrlttr2}{%
    In letters, you often encounter paragraphs marked not by indentation of
    the first line but by a vertical space between them. The \KOMAScript{}
    class \Class{scrlttr2}\OnlyAt{scrlttr2} provides ways to accomplish this
    with the \Option{parskip} option.%
  }{\InternalCommonFileUsageError}%
} %
The \PName{method} consists of two elements. The first element is either
\PValue{full}\important{\OptionValue{parskip}{full}\\
  \OptionValue{parskip}{half}} or \PValue{half}, where \PValue{full} stands
for a paragraph spacing of one line and \PValue{half} stands for a paragraph
spacing of half a line. The second element consists of one of the characters
``\PValue{*}'', ``\PValue{+}'', or ``\PValue{-}'' and can be omitted. Without
the second element\important{\OptionVName{parskip}{distance}}, the final line
of a paragraph will end with a white space of at least 1\Unit{em}. With the
plus character as the second element%
\important{\OptionValue{parskip}{\PName{distance}+}}, the white space will be
at least one third\,---\,and with the
asterisk\important{\OptionValue{parskip}{\PName{distance}*}} one
fourth\,---\,the width of a normal line. With the minus variant%
\important{\OptionValue{parskip}{\PName{Abstand}-}}, no provision is made for
white space in the last line of a paragraph.

You can change the setting at any time. If you change it inside the document,
the \Macro{selectfont}\IndexCmd{selectfont}%
\IfThisCommonLabelBase{maincls}{%
  \ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and
    \Class{scrartcl}}%
}{%
  \IfThisCommonLabelBase{scrlttr2}{%
    \ChangedAt{v3.08}{\Class{scrlttr2}}%
  }{%
    \InternalComonFileUsageError%
  }%
} %
command will be called implicitly. Changes to paragraph spacing within a 
paragraph will not be visible until the end of the paragraph.

In addition to the resulting eight combinations for \PName{method}, you can
use the values for simple switches shown in \autoref{tab:truefalseswitch},
\autopageref{tab:truefalseswitch}. Activating the option%
\important{\Option{parskip}\\\OptionValue{parskip}{true}} corresponds to using
\PValue{full} with no second element and therefore results in inter-paragraph
spacing of one line with at least 1\Unit{em} white space at the end of the
last line of each paragraph. Deactivating%
\important{\OptionValue{parskip}{false}} the option re-activates the default
indentation of 1\Unit{em} at the first line of the paragraph instead of
paragraph spacing. A summary of all possible values for \PName{method} are
shown in \autoref{tab:\ThisCommonFirstLabelBase.parskip}%
\IfThisCommonFirstRun{.%
  \begin{desclist}
%  \begin{table}
  \desccaption
%    \caption
  [{Available values of option \Option{parskip}}]{%
    Available values of option \Option{parskip} to select
    how paragraph are
    distinguished\label{tab:\ThisCommonFirstLabelBase.parskip}%
  }%
  {%
    Available values of option \Option{parskip} (\emph{continuation})%
  }%
  % \begin{desctabular}
  \entry{\PValue{false}, \PValue{off}, \PValue{no}%
    \IndexOption{parskip~=\textKValue{false}}}{%
    Paragraphs are identified by indentation of the first line by 1em.
    There is no spacing requirement at the end of the last line
    of a paragraph.}%
  \entry{\PValue{full}, \PValue{true}, \PValue{on}, \PValue{yes}%
    \IndexOption{parskip~=\textKValue{full}}%
  }{%
    Paragraphs are identified by a vertical space of one line between
    paragraphs. There must be at least 1\Unit{em} of free space at the
    end of the last line of the paragraph.}%
  \pventry{full-}{%
    Paragraphs are identified by a vertical space of one line between
    paragraphs. There is no spacing requirement at the end of the last line
    of a paragraph.\IndexOption{parskip~=\textKValue{full-}}}%
  \pventry{full+}{%
    Paragraphs are identified by a vertical space of one line between
    paragraphs. There must be at least a third of a line of free space at the
    end of a paragraph.\IndexOption{parskip~=\textKValue{full+}}}%
  \pventry{full*}{%
    Paragraphs are identified by a vertical space of one line between
    paragraphs. There must be at least a quarter of a line of free space at
    the end of a paragraph.\IndexOption{parskip~=\textKValue{full*}}}%
  \pventry{half}{%
    Paragraphs are identified by a vertical space of half a line between
    paragraphs. There must be at least 1\Unit{em} free space at the end of the
    last line of a paragraph.\IndexOption{parskip~=\textKValue{half}}}%
  \pventry{half-}{%
    Paragraphs are identified by a vertical space of half a line between
    paragraphs. There is no spacing requirement at the end of the last line
    of a paragraph.\IndexOption{parskip~=\textKValue{half-}}}%
  \pventry{half+}{%
    Paragraphs are identified by a vertical space of half a line between
    paragraphs. There must be at least a third of a line of free space at the
    end of a paragraph.\IndexOption{parskip~=\textKValue{half+}}}%
  \pventry{half*}{%
    Paragraphs are identified by a vertical space of half a line between
    paragraphs. There must be at least a quarter of a line of free space at
    the end of a paragraph.\IndexOption{parskip~=\textKValue{half*}}}%
  \pventry{never}{%
    No%
    \IfThisCommonLabelBase{maincls}{%
      \ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and
        \Class{scrartcl}}%
    }{%
      \IfThisCommonLabelBase{scrlttr2}{%
        \ChangedAt{v3.08}{\Class{scrlttr2}}%
      }{}%
    } %
    inter-paragraph spacing will be inserted even if additional vertical
    spacing is needed for vertical adjustment with
    \Macro{flushbottom}.\IndexCmd{flushbottom}%
    \IndexOption{parskip~=\textKValue{never}}}%
%  \end{desctabular}
%  \end{table}%
  \end{desclist}%
}{ at \autopageref{tab:\ThisCommonFirstLabelBase.parskip}.}

All\textnote{Attention!} eight \PValue{full} and \PValue{half} option values
also change the spacing before, after, and inside list environments. This
prevents these environments or the paragraphs inside them from having
a larger separation than that between the paragraphs of normal text.%
\IfThisCommonLabelBase{maincls}{ %
  Additionally, these options ensure that the table of contents and the lists
  of figures and tables are set without any additional spacing.%
}{ %
  Several elements of the letterhead are always set without inter-paragraph
  spacing.%
}%

The default\textnote{default} behaviour of \KOMAScript{} is
\OptionValue{parskip}{false}. In this case, there is no spacing between
paragraphs, only an indentation of the first line by 1\Unit{em}.%
%
\EndIndexGroup
%
\EndIndexGroup

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "scrguide-en.tex"
%%% coding: utf-8
%%% ispell-local-dictionary: "en_GB"
%%% eval: (flyspell-mode 1)
%%% End: