summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex
blob: fe43c56e5452e32d8f8ddba36dcb2b06c1fb4720 (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
% ======================================================================
% introduction.tex
% Copyright (c) Markus Kohm, 2001-2012
%
% 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.
% ----------------------------------------------------------------------
% introduction.tex
% Copyright (c) Markus Kohm, 2001-2012
%
% 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.
% ======================================================================
%
% Introduction of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Einleitung der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ======================================================================

\ProvidesFile{introduction.tex}[2012/03/14 KOMA-Script guide introduction]
\translator{Kevin Pfeiffer\and Gernot Hassenpflug\and 
  Krickette Murabayashi\and Markus Kohm}

% Date of translated german file: 2011/10/12

\chapter{Introduction}
\labelbase{introduction}

This chapter includes important information about the structure of the manual
and the history of KOMA-Script, which begins years before the first
version. You will also find information for those who have not installed
KOMA-Script or encounter errors.

\section{Preface}\label{sec:introduction.preface}

\KOMAScript{} is very complex. This is evidenced by the fact that it
consists of
not only a single class or a single package, but a bundle of many classes and
packages. Although the classes are designed as a counterpart to the standard
classes, that does not necessarily mean that they only have the commands,
environments, and setting of the standard classes or imitate their
appearance. The capabilities of \KOMAScript{} surpass the capabilities of the
standard classes considerably. Some of them are to be regarded as a supplement
to the basic skills of the \LaTeX{} kernel.

The foregoing means that the documentation of \KOMAScript{} has to be
extensive. In addition, \KOMAScript{} usually is not taught. That means there
is no teacher who knows his students and can therefore choose the teaching and
learning materials and adapt them accordingly. It would be easy to write the
documentation for any specific audience. The difficulty is, however, that the
guide must service all potential audiences. We, the authors, have tried to
create a guide that is suited for the computer scientist as well as the
secretary or the fishmonger. We have tried, although this is actually % dealing
% with
an impossible task. The result consists of several compromises and we
hope that you will keep this in mind when using it.  Your suggestions for
improvement are, of course, always welcome.

Despite the volume of the manual, % in case of problems 
it is recommended to
consult the documentation. Attention is drawn to the multi-part index at the
end of this document. In addition to this guide, documentation includes all the
text documents that are part of the bundle. See \File{manifest.tex} for a list
of all of them.


\section{Structure of the Guide}\label{sec:introduction.structure}

This manual consists of several parts. There's a part for average users,
another part for advanced users and experts, and an appendix with additional
examples and information for those who always want to know more.

\hyperref[part:forAuthors]{Part~\ref{part:forAuthors}} is recommended for all
\KOMAScript{} users. This means that you may find here even some information
for newcomers to \LaTeX. In particular, this part is enhanced by many examples
to the average user that are intended to illustrate the explanations. Do not
be afraid to try these examples yourself and in modifying them to find out how
\KOMAScript{} works. Nevertheless the {\KOMAScript} user guide is not intended
to be a {\LaTeX} primer.  Those new to {\LaTeX} should look at \emph{The Not
  So Short Introduction to {\LaTeXe}} \cite{lshort} or \emph{{\LaTeXe} for
  Authors} \cite{latex:usrguide} or a {\LaTeX} reference book. You will also
find useful information in the many {\LaTeX} FAQs, including the \emph{{\TeX}
  Frequently Asked Questions on the Web} \cite{UK:FAQ}.
Although the length of the \emph{{\TeX} Frequently Asked Questions
on the Web} is considerably long, it is nevertheless
quite useful not only to those having problems using \LaTeX{} or \KOMAScript. 

\hyperref[part:forExperts]{Part~\ref{part:forExperts}} is recommended for
advanced \KOMAScript{} users. These are all of you who already know
\LaTeX{}, maybe worked with \KOMAScript{} for a while, and want to
learn more about \KOMAScript{} internals, interaction of \KOMAScript{}
with other packages, and how to use \KOMAScript{} as an answer to
special demands. For this purpose we will have a closer look at some
aspects from \autoref{part:forAuthors} again. In addition some
instructions that have been implemented for advanced users and
experts, especially, will be documented. This is complemented by the
documentation of packages that are normally hidden to the user insofar
as they do their work under the surface of the classes and user
packages. These packages are specifically designed to be used by other
authors of classes and packages.

The appendix, which may be found only in the German book version, contains
information which is beyond what is covered in \autoref{part:forAuthors} and
\autoref{part:forExperts}.  Advanced users may find background information on
issues of typography to give them a basis for their own decisions. In
addition, the appendix provides examples for aspiring authors of
packages. These examples are less intended to be simply transferred. Rather,
they convey knowledge of planning and implementation of projects as well as
some basic \LaTeX{} instructions for authors of packages.

If you are only interested in using a single {\KOMAScript} class or package
you can probably successfully avoid reading the entire guide.  Each class and
package typically has its own chapter; however, the three main classes
(\Class{scrbook}, \Class{scrrprt}, and \Class{scrartcl}) are introduced
together in \autoref{cha:maincls}. Where an example or note only
applies to one or two of the three classes, e.\,g.,
\Class{scrartcl}\OnlyAt{\Class{scrartcl}}, it is called out in the
margin, as
shown here with \Class{scrartcl}.

\begin{Explain} 
  The primary documentation for {\KOMAScript} is in German and has been
  translated for your convenience; like most of the {\LaTeX} world, its
  commands, environments, options, etc., are in English. In a few cases, the
  name of a command may sound a little strange, but even so, we hope and
  believe that with the help of this guide, {\KOMAScript} will be usable
  and useful to you.
\end{Explain}


\section{History of {\KOMAScript}}\label{sec:introduction.history}

In the early 1990s, Frank Neukam needed a method to publish an
instructor's lecture notes. At that time {\LaTeX} was {\LaTeX}2.09 and there
was no distinction between classes and packages\,---\,there were only
\emph{styles}.  Frank felt that the standard document styles were not
good enough for his work; he wanted additional commands and
environments. At the same time he was interested in typography and,
after reading Tschichold's \emph{Ausgew\"ahlte Aufs\"atze \"uber Fragen der
Gestalt des Buches und der Typographie} (Selected Articles on the
Problems of Book Design and Typography) \cite{JTsch87}, he decided to
write his own document style\,---\,and not just a one-time solution to his
lecture notes, but an entire style family, one specifically designed for
European and German typography. Thus {\Script} was born.

Markus Kohm, the developer of {\KOMAScript}, came across {\Script} in December
1992 and added an option to use the A5 paper format. At that time neither the
standard style nor {\Script} provided support for A5 paper. Therefore it did
not take long until Markus made the first changes to {\Script}. This and other
changes were then incorporated into {\ScriptII}, released by Frank in December
1993.

Beginning in mid-1994, {\LaTeXe} became available and brought with it
many changes. Users of {\ScriptII} were faced with either limiting their
usage to {\LaTeXe}'s compatibility mode or giving up {\Script}
altogether.  This situation led Markus to put together a new {\LaTeXe}
package, released on 7~July 1994 as {\KOMAScript}; a few months later
Frank declared {\KOMAScript} to be the official successor to {\Script}.
{\KOMAScript} originally provided no \emph{letter} class, but this
deficiency was soon remedied by Axel Kielhorn, and the result became part
of {\KOMAScript} in December 1994.  Axel also wrote the first true
German-language user guide, which was followed by an English-language
guide by Werner Lemberg.

Since then much time has passed. {\LaTeX} has changed in only minor
ways, but the {\LaTeX} landscape has changed a great deal; many new
packages and classes are now available and {\KOMAScript} itself has
grown far beyond what it was in 1994. The initial goal was to provide
good {\LaTeX} classes for German-language authors, but today its
primary purpose is to provide more-flexible alternatives to the
standard classes. {\KOMAScript}'s success has led to e-mail from users
all over the world, and this has led to many new macros\,---\,all
needing documentation; hence this ``small guide.''


\section{Special Thanks}
\label{sec:introduction.thanks}

Acknowledgements in the introduction? No, the proper acknowledgements can be
found in the addendum. My comments here are not intended for the authors of
this guide\,---\,and those thanks should rightly come from you, the reader,
anyhow. I, the author of {\KOMAScript}, would like to extend my personal thanks
to Frank Neukam.  Without his {\Script} family, {\KOMAScript} would not have
come about.  I am indebted to the many persons who have contributed to
{\KOMAScript}, but with their indulgence, I would like to specifically mention
Jens-Uwe Morawski and Torsten Kr\"uger. The English translation of the guide
is, among many other things, due to Jens's untiring commitment. Torsten was
the best beta-tester I ever had. His work has particularly enhanced the
usability of \Class{scrlttr2} and \Class{scrpage2}. Many thanks to all who
encouraged me to go on, to make things better and less error-prone, or to
implement additional features.

Thanks go as well to DANTE, Deutschsprachige
Anwendervereinigung {\TeX}~e.V\kern-.18em, (the German-Language {\TeX} User Group).
Without the DANTE server, {\KOMAScript} could not have been released and
distributed. Thanks as well to everybody in the {\TeX} newsgroups and mailing
lists who answer questions and have helped me to provide support for
{\KOMAScript}.


\section{Legal Notes}
\label{sec:introduction.legal}

{\KOMAScript} was released under the {\LaTeX} Project Public License. You
will find it in the file \File{lppl.txt}. An unofficial German-language
translation is also available in \File{lppl-de.txt} and is valid for all
German-speaking countries.

\iffree{This document and the {\KOMAScript} bundle are provided ``as is'' and
without warranty of any kind.}%
{Please note: the printed version of this guide is not free under the
conditions of the {\LaTeX} Project Public Licence. If you need a free version
of this guide, use the version that is provided as part of the {\KOMAScript}
bundle.}


\section{Installation}
\label{sec:introduction.installation}

The three most important \TeX{} distributions, Mac\TeX, MiK\TeX, and \TeX{}
Live, make \KOMAScript{} available by their package management software. It is
recommended to make installations and updates of \KOMAScript{} using these
tools. Nevertheless the manual installation without using the package managers
has been described in the file \File{INSTALL.txt}, that is part of every legal
\KOMAScript{} bundle. You should also read the documentation that comes with
the {\TeX} distribution you are using.


\section{Bug Reports and Other Requests}
\label{sec:introduction.errors}

If you think you have found an error in the documentation or a bug in one of
the {\KOMAScript} classes, one of the {\KOMAScript} packages, or another part
of {\KOMAScript}, please do the following: first have a look on CTAN to see if
a newer version of {\KOMAScript} is available; if a newer version is
available, % in this case
install the
applicable section and try again.

If you are using the most recent version of {\KOMAScript} and still have a
bug, please provide a short {\LaTeX} document that demonstrates the
problem. You should only use the packages and definitions needed to
demonstrate the problem; do not use any unusual packages.

By preparing such an example it often becomes clear whether the problem is
truly a {\KOMAScript} bug or something else.  To find out the version numbers
of all packages in use, simply put \Macro{listfiles} in the preamble of your
example and read the end of the \File{log}-file.

Please report {\KOMAScript} (only) bugs to
\href{mailto:komascript@gmx.info}{komascript@gmx.info}. If you want to ask
your question in a Usenet group, mailing list, or Internet forum, you should
also include such an example as part of your question.


\section{Additional Information}
\label{sec:introduction.moreinfos}

Once you become an experienced {\KOMAScript} user you may want to look at some
more advanced examples and information. These you will find on the
{\KOMAScript} documentation web site \cite{homepage}. The main language of the
site is German, but nevertheless English is welcome.

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