path: root/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex

% ======================================================================
% introduction.tex
% Copyright (c) Markus Kohm, 2001-2019
%
% 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-2019
%
% 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
%
% ======================================================================

\KOMAProvidesFile{introduction.tex}
                 [$Date: 2019-01-15 08:39:58 +0100 (Tue, 15 Jan 2019) $
                  KOMA-Script guide introduction]
\translator{Kevin Pfeiffer\and Gernot Hassenpflug\and 
  Krickette Murabayashi\and Markus Kohm\and Karl Hagen}

% Date of the translated German file: 2018-02-05

\chapter{Introduction}
\labelbase{introduction}

This chapter contains, among other things, important information about the 
structure of the manual and the history of {\KOMAScript}, which begins 
years before the first version. You will also find information on how to
install {\KOMAScript} and what to do if you encounter errors.

\section{Preface}\seclabel{preface}

{\KOMAScript} is very complex. This is due to the fact that it consists of not
just a single class or a single package but a bundle of many classes and
packages. Although the classes are designed as counterparts to the standard
classes, that does not mean they provide only the commands, environments, and
settings of the standard classes, or that they imitate their appearance. The
capabilities of {\KOMAScript} sometimes far surpass those of the standard
classes. Some of them should be considered extensions to the basic
capabilities of the \LaTeX{} kernel.

The foregoing means that the documentation of {\KOMAScript} has to be
extensive. In addition, {\KOMAScript} is not normally taught. That means there
are no teachers who know their students and can therefore choose the teaching
materials and adapt them accordingly. It would be easy to write documentation
for a specific audience. The difficulty facing the author, however, is that
the manual must serve all potential audiences. I have tried to create a guide
that is equally suitable for the computer scientist and the fishmonger's
secretary. I have tried, although this is actually an impossible task. The
result is numerous compromises, and I would ask you to take this issue into
account if you have any complaints or suggestions to help improve the current
situation.

Despite the length of this manual, I would ask you to consult the
documentation first in case you have problems. You should start by referring
to the multi-part index at the end of this document. In addition to this
manual, documentation includes all the text documents that are part of the
bundle. See \File{manifest.tex} for a complete list.

\section{Structure of the Guide}\seclabel{structure}

This manual is divided into several parts: There is a section for average
users, one for advanced users and experts, and an appendix with further
information and examples for those who want to understand {\KOMAScript}
thoroughly.

\autoref{part:forAuthors} is intended for all {\KOMAScript} users. This means
that some information in this section is directed at newcomers to \LaTeX. In
particular, this part contains many examples that are intended to clarify the
explanations. Do not hesitate to try these examples yourself and discover how
{\KOMAScript} works by modifying them. That said, 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 considerable, you should get at least a rough
overview of it and consult it in case you have problems, as well as this
\iffree{guide}{book}.

\autoref{part:forExperts} is intended for advanced {\KOMAScript} users, those
who are already familiar with \LaTeX{} or who have been working with
{\KOMAScript} for a while and want to understand more about how {\KOMAScript}
works, how it interacts with other packages, and how to perform more
specialized tasks with it. For this purpose, we return to some aspects of the
class descriptions from \autoref{part:forAuthors} and explain them in more
detail. In addition we document some commands that are particularly intended
for advanced users and experts. This is supplemented by the documentation of
packages that are normally hidden from the user, insofar as they do their work
beneath the surface of the classes and user packages. These packages are
specifically designed to be used by authors of classes and packages.

The appendix\iffree{, which can only be found in the German book version,}{}
contains information beyond that which is covered in \autoref{part:forAuthors}
and \autoref{part:forExperts}. Advanced users will find background information
on issues of typography to give them a basis for their own decisions. In
addition, the appendix provides examples for aspiring package authors. These
examples are not intended simply to be copied. Rather, they provide
information about planning and implementing projects, as well as some basic
\LaTeX{} commands for package authors.

The guide's layout should help you read only those parts that are actually of
interest. Each class and package typically has its own chapter.
Cross-references to another chapter are thus usually also references to
another part of the overall package. However, since the three main classes
(\Class{scrbook}, \Class{scrrprt}, and \Class{scrartcl}) largely agree, they
are introduced together in \autoref{cha:maincls}. Differences between the
classes, e.\,g., for something that only affects the class
\Class{scrartcl}\OnlyAt{\Class{scrartcl}}, are clearly highlighted 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}

At this point you should know enough to understand the guide.
It might, however, still be worth reading the rest of this chapter.

\section{History of {\KOMAScript}}\seclabel{history}

%\begin{Explain}
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.

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.''
%\end{Explain}


\section{Special Thanks}
\seclabel{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.

Special thanks go as well to the founders and members of 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 on
the {\TeX} newsgroups and mailing lists who answer questions and have helped
me provide support for {\KOMAScript}.

My thanks also go to all those who have always encouraged me to go further and
to implement this or that feature better, with fewer flaws, or simply as an
extension. I would also like to thank the very generous donor who has given me
the most significant amount of money I have ever been paid for the work done
so far on \KOMAScript{}.

\section{Legal Notes}
\seclabel{legal}

{\KOMAScript} is 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}
\seclabel{installation}

The three most important \TeX{} distributions, Mac\TeX, MiK\TeX, and
\TeX{}~Live, make {\KOMAScript} available through their package management
software. You should install and update {\KOMAScript} using these tools, if
possible. Manual installation without using the package managers is described
in the file \File{INSTALL.txt}, which is part of every {\KOMAScript}
distribution. You should also read the documentation that comes with the
{\TeX} distribution you are using.


\section{Bug Reports and Other Requests}
\seclabel{errors}

If you think you have found an error in the documentation or a bug in one of
the {\KOMAScript} classes, packages, or another part of {\KOMAScript}, please
do the following: First check on CTAN to see if a newer version of
{\KOMAScript} has been released. If a newer version is available, install this
new version and check if the problem persists.

If the bug still occurs and your installation is fully up to date, please
provide a short {\LaTeX} file that demonstrates the problem. Such a file is
known as a minimal working example (MWE). You should include only minimal text
and use only the packages and definitions essential to demonstrate the
problem. Avoid using any unusual packages as much as possible.

By preparing such an example it often becomes clear whether the problem is
truly a {\KOMAScript} bug or caused by something else. To check if another
package or class is actually causing the problem, you can also test your
example with the corresponding standard class instead of a {\KOMAScript}
class. If your problem still occurs, you should address your error report to
the author of the appropriate package than to the author of {\KOMAScript}.
Finally, you should carefully review the instructions for the appropriate
package, classes, and {\KOMAScript} component. A solution to your problem may
already exist, in which case an error report is unnecessary.

If you think you have found a previously unreported error, or if for some
other reason you need to contact the author of {\KOMAScript}, don't forget the
following:

\begin{itemize}
\item Does the problem also occur if a standard class is used instead of a
  {\KOMAScript} class? In this case, the error is most likely not with
  {\KOMAScript}, and it makes more sense to ask your question in a public
  forum, a mailing list, or Usenet.
\item Which {\KOMAScript} version do you use? For related information, see the
  \File{log} file of the \LaTeX{} run of any document that uses a
  {\KOMAScript} class.
\item Which operating system and which \TeX{} distribution do you use? This
  information might seem rather superfluous for a system-independent package
  like {\KOMAScript} or {\LaTeX}, but time and again they have certainly been
  shown to play a role.
\item What exactly is the problem or the error? Describe the problem. It's
  better to be too detailed than too short. Often it makes sense to explain
  the background.
\item What does a minimal working example look like? You can easily create one
  by commenting out content and packages from the document step by step.  The
  result is a document that only contains the packages and parts necessary to
  reproduce the problem. In addition, all loaded images should be replaced by
  \Macro{rule} statements of the appropriate size. Before sending your
  MWE,remove the commented-out parts, insert the command \Macro{listfiles} in
  the preamble, and perform another {\LaTeX} run. At the end of the \File{log}
  file, you will see an overview of the packages used. Add the MWE and the log
  file to the end of your description of the problem.
\end{itemize}

Do not send packages, PDF, PS, or DVI files. If the entire issue or bug
description, including the minimal example and the \File{log} file is larger
than a few tens of kilobytes, you're likely doing something wrong.

If you've followed all these steps, please send your {\KOMAScript} (only) bug
report 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 follow the procedures mentioned above and include a minimal
working example as part of your question, but usually you don't need to
provide the \File{log}-file. Instead, just add the list of packages and
package versions from the \File{log}-file and, if your MWE compiles with
errors, you should quote those messages from the \File{log} file.

Please note that default settings which are not typographically optimal do not
represent errors. For reasons of compatibility, defaults are preserved
whenever possible in new versions of {\KOMAScript}. Furthermore, typographical
best practices are partly a matter of language and culture, and so the default
settings of {\KOMAScript} are necessarily a compromise.

\section{Additional Information}
\seclabel{moreinfos}

Once you become familiar with {\KOMAScript}, you may want examples that show
how to accomplish more difficult tasks. Such examples go beyond the basic
instructional scope of this manual and so are not included. However, you will
find more examples on the website of the {\KOMAScript} Documentation Project
\cite{homepage}. These examples are designed for advanced {\LaTeX} users and
are not particularly suitable for beginners. The main language of the site
is German, but English is also welcome.

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